> ## Documentation Index
> Fetch the complete documentation index at: https://developers.hubspot.jp/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# エクスポート

export const ScopesList = ({scopes = [], description = "この API には、次のいずれかのスコープが必要です。"}) => {
  if (!scopes || scopes.length === 0) {
    return null;
  }
  const sortedScopes = scopes.sort((a, b) => a.localeCompare(b));
  return <div>
      <div className="text-sm mb-2">{description}</div>
      <div>
        {sortedScopes.map((scope, index) => <div key={index}>
            <code>
              <span className="text-xs">{scope}</span>
            </code>
          </div>)}
      </div>
    </div>;
};

<RelatedApiLink />

エクスポートAPIを使用すると、HubSpotアカウントからのレコードやプロパティーデータのエクスポート、エクスポートファイルのダウンロードURL取得、およびエクスポートステータスの確認を行えます。また、HubSpotでは、[レコードをエクスポート](https://knowledge.hubspot.com/ja/import-and-export/export-records)することや、[アカウントで過去のエクスポートのログを表示](https://knowledge.hubspot.com/ja/import-and-export/view-a-log-of-your-users-exports-in-your-account)することもできます。

<Accordion title="スコープ要件">
  <ScopesList
    scopes={[
  'crm.export'
]}
  />
</Accordion>

## エクスポートを開始する

エクスポートを開始するには、`POST`リクエストを`/crm/v3/exports/export/async`に送信します。リクエスト本文では、ファイル形式、エクスポートするオブジェクトとプロパティー、実行するエクスポートの種類（例：オブジェクトビューまたはリストのエクスポート）などの情報を指定する必要があります。特定の演算子に基づいてエクスポートするプロパティーデータを絞り込むこともできます。

ビューとリストのどちらのエクスポートの場合も、リクエストに以下のフィールドを含めることができます。

| パラメーター                                              | 説明                                                                                                                                                                                                                                                                             |
| --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `exportType`                                        | エクスポートのタイプ。`VIEW`（オブジェクトのインデックスページからビューをエクスポートする場合）または`LIST`（リストをエクスポートする場合）のどちらかを指定します。                                                                                                                                                                                       |
| `format`                                            | ファイル形式。オプションは、`XLSX`、`CSV`、または`XLS`です。                                                                                                                                                                                                                                         |
| `exportName`                                        | エクスポートの名前。                                                                                                                                                                                                                                                                     |
| `language`                                          | エクスポートファイルの言語。オプションは、`DE`、`EN`、`ES`、`FI`、`FR`、`IT`、`JA`、`NL`、`PL`、`PT`、または`SV`です。詳細については[HubSpotの対応言語](https://knowledge.hubspot.com/ja/help-and-resources/hubspot-language-offerings)をご確認ください。                                                                                |
| `objectType`                                        | エクスポートするオブジェクトの名前またはID。標準オブジェクトの場合はオブジェクトの名前（例：`CONTACT`）を使用できますが、カスタムオブジェクトの場合は`objectTypeId`値を使用する必要があります。この値は、`GET`リクエストを`/crm/v3/schemas`に送信することで取得できます。                                                                                                                   |
| `associatedObjectType`                              | エクスポートに含める関連付けられたオブジェクトの名前またはID。1回のリクエストにつき最大4つの関連付けられたオブジェクトをエクスポートできます。関連付けられたオブジェクトの場合、エクスポートにはそのオブジェクトに関連付けられたレコードIDが含まれます。関連付けられたオブジェクトを1つだけエクスポートするか、`includePrimaryDisplayPropertyForAssociatedObjects`フィールドを`true`に設定した場合、レコードのプライマリー表示プロパティー値もエクスポートされます（例：`name`会社）。 |
| `objectProperties`                                  | エクスポートに含めるプロパティーのリスト。デフォルトでは、プロパティーの名前と値は人間が判読できるラベルとして表示されますが、`exportInternalValuesOptions`パラメーターを使用して内部の名前と値を要求できます。                                                                                                                                                         |
| `includePrimaryDisplayPropertyForAssociatedObjects` | 関連付けられた全てのレコードのプライマリー表示プロパティー値をエクスポートするには、このフィールドを値`true`とともに含めます（例：会社の場合は`name`）。関連付けられたオブジェクトを1つだけエクスポートする場合（`associatedObjectType`フィールドで示されます）、これはデフォルトで`true`に設定されます。複数の関連付けられたオブジェクトをエクスポートする場合、この値は既定で`false`に設定されます。                                                    |
| `includeLabeledAssociations`                        | このフィールドを値`true`と共に含めると、[関連付けラベル](https://developers.hubspot.jp/docs/api-reference/latest/crm/associations/associate-records/guide#create-and-manage-association-types)をエクスポートして、関連付けられたレコード間の関係性を記述できます。                                                                       |
| `exportInternalValuesOptions`                       | プロパティーの内部名や内部値をエクスポートするには、この配列を含めます。配列に、プロパティーの内部名（列ヘッダーとして表示されます）をエクスポートするための`NAMES`や、プロパティーの内部値（人間が判読できる日付ではなく、カスタム パイプライン ステージやタイムスタンプの数値など）をエクスポートするための`VALUES`を含めます。                                                                                                      |
| `overrideAssociatedObjectsPerDefinitionPerRowLimit` | デフォルトの1行当たり関連付け1,000件までの[上限](https://developers.hubspot.jp/docsguides/api/crm/exports#limits)をオーバーライドするには、値を`true`にしてこのフィールドを含めます。                                                                                                                                             |

### ビューをエクスポートする

[インデックスページのビュー](https://knowledge.hubspot.com/ja/records/view-and-filter-records)をエクスポートする場合、`exportType`の値を`VIEW`に設定する必要があります。また、以下のフィールドを含めることで、エクスポートするレコードの絞り込みや並べ替えも行えます。

| パラメーター                   | 説明                                                                                                                                                                                                        |
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `publicCrmSearchRequest` | 特定のプロパティー値と検索クエリーに基づいてエクスポートするデータを示します。このオブジェクトには、次のフィールドを含めることができます。<br />`filters`：レコードを絞り込む基準とするプロパティーとプロパティー値。<br />`sorts`：プロパティー値の並べ替え順。昇順（`ASC`）、降順（`DES`）のいずれかです。<br />`query`：レコードの値を検索するための文字列。 |

例えば、コンタクトとコンタクトに関連付けられている会社レコードのビューを、`email`プロパティーでフィルタリングして、プロパティーの内部名と内部値を含めてエクスポートする場合、リクエストは次のようになります。

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    ///Example request body
    {
      "exportType": "VIEW",
      "exportName": "All contacts",
      "format": "xlsx",
      "language": "DE",
      "objectType": "CONTACT",
      "exportInternalValuesOptions": ["NAMES", "VALUES"],
      "objectProperties": ["email", "firstname", "lastname"],
      "associatedObjectType": "COMPANY",
      "publicCrmSearchRequest": {
        "filters": [
          {
            "value": "hello@test.com",
            "propertyName": "email",
            "operator": "EQ"
          }
        ],
        "query": "hello",
        "sorts": [
          {
            "propertyName": "email",
            "order": "ASC"
          }
        ]
      }
    }
    ```
  </Tab>
</Tabs>

### リストをエクスポートする

[リスト](https://knowledge.hubspot.com/ja/segments/create-active-or-static-lists)をエクスポートする場合、`exportType`の値を`LIST`に設定する必要があります。また、次のフィールドを使用して、エクスポートするリストを指定する必要もあります。

| パラメーター   | 説明                                                                                                                                                                                                                                                                                                |
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `listId` | エクスポートするリストの[ILSリストID](https://knowledge.hubspot.com/ja/lists/troubleshoot-lists#ils-list)。ILSリストIDの値は、HubSpotのリストの詳細から確認できます。［コンタクト］＞［リスト］の順に進み、表内のいずれかのリストにカーソルを合わせて、［詳細］をクリックします。右側のパネルで、ILSリストIDの値の横に表示される［リストIDをコピー］をクリックします。コンタクトリストには2つの異なるID値がありますが、リクエストではILSリストIDの値を使用することが<u>必須</u>です。 |

例えば、コンタクトのEメールを含むリストをエクスポートする場合、リクエストは次のようになります。

<Tabs>
  <Tab title="JSON">
    ```json theme={null}
    ///Example request body
    {
      "exportType": "LIST",
      "listId": 1234567,
      "exportName": "Marketing email contacts",
      "format": "xlsx",
      "language": "EN",
      "objectType": "CONTACT",
      "objectProperties": ["email"]
    }
    ```
  </Tab>
</Tabs>

## エクスポートを取得する

エクスポートが正常に完了すると、レスポンスでエクスポートの`id`が返されます。HubSpotアカウントからエクスポートを取得するには、`GET`リクエストを`/crm/v3/exports/export/async/tasks/{exportId}/status`に送信します。

エクスポートを取得する際は、エクスポートの`status`も返されます。返される可能性があるステータスには、`COMPLETE`、`PENDING`、`PROCESSING`、`CANCELED`があります。エクスポートのステータスが`COMPLETE`の場合、エクスポートしたファイルをダウンロードするために使用できるURLが返されます。ダウンロードURLは、リクエストが完了してから5分後に期限切れになります。期限切れになると、別の`GET`リクエストを実行して、新しい一意のURLを生成できます。

<Warning>
  ### 注：

  有効期限が切れるまでは、追加の承認なしでエクスポートのダウンロードURLにアクセスできます。データを保護するために、URLの共有や、このAPIを介したHubSpotとの連携は慎重に進めてください。
</Warning>

## 上限

次の上限が適用されます。

* 24時間以内に最大30回のエクスポートを実行できます。一度に実行できるエクスポートは1つのみです。追加のエクスポートは、前回のエクスポートが完了するまでキューに入れられます。
* 大量のエクスポートを行う場合、複数のファイルが単一のzipファイルにまとめられることがあります。1,000,000行を超えるCSVファイルまたはXLSXファイル、および65,535行を超えるXLSファイルで発生します。CSVファイルも、ファイルが2MBを超えていれば、行数が1,000,000行未満であっても自動的にzip化されます。
* デフォルトでは、1行当たりの関連付けの数は1,000件までに制限されています。この上限をオーバーライドする場合は、`overrideAssociatedObjectsPerDefinitionPerRowLimit`フィールドを含めて値を`true`に指定します。