一括抽出

Marketoには、一括抽出と呼ばれる、顧客および顧客関連の大きなデータセットを取得するためのインターフェイスが用意されています。 現在、インターフェイスは次の 3 つのオブジェクトタイプで提供されています。

一括抽出を実行するには、ジョブを作成し、取得するデータのセットを定義し、ジョブをキューに入れ、ジョブがファイルの書き込みを完了するのを待ってから、HTTP 経由でファイルを取得します。 これらのジョブは非同期で実行され、ポーリングによって書き出しのステータスを取得できます。

Note: 他のエンドポイントとは異なり、 Bulk API エンドポイントの先頭には「/rest」は付いていません。

認証

Bulk extract API では、他のMarketo REST API と同じ OAuth 2.0 認証方式を使用します。 これには、有効なアクセストークンを HTTP ヘッダー Authorization: Bearer {_AccessToken_} として送信する必要があります。

制限

UpdatedAt およびスマートリスト用の一括リード抽出フィルターは、一部の購読タイプでは使用できません。 使用できない場合、エクスポートリードジョブを作成エンドポイントの呼び出しで、「1035、ターゲット購読でサポートされていないフィルタータイプ」というエラーが返されます。 お客様は、Marketo サポートに連絡して、この機能をサブスクリプションで有効にすることができます。

キュー

一括抽出 API は、ジョブキュー（リード、アクティビティ、プログラムメンバー、カスタムオブジェクトの間で共有）を使用します。 抽出ジョブを最初に作成する必要があります。次に、「エクスポートリード/アクティビティ/プログラムメンバージョブを作成」および「エクスポートリード/アクティビティ/プログラムメンバージョブをエンキュー」エンドポイントを呼び出して、キューに入れます。 キューに入ると、ジョブはキューから取り出され、計算リソースが使用可能になったときに開始されます。

キュー内のジョブの最大数は 10 です。 キューがいっぱいになったときにジョブをエンキューしようとすると、エンキュー書き出しジョブ エンドポイントで「1029, キュー内のジョブが多すぎます」というエラーが返されます。 最大 2 つのジョブを同時に実行できます（ステータスは「処理中」）。

ファイルサイズ

一括抽出 API は、一括抽出ジョブで取得したデータのディスク上のサイズに基づいて計測されます。 エクスポートジョブの完了ステータス応答から fileSize 属性を読み取ることで、ジョブの明示的なサイズ（バイト単位）を決定できます。

1 日の割り当て量は最大 500 MB/日で、リード、アクティビティ、プログラムメンバー、カスタムオブジェクトで共有されます。 クォータを超えた場合、毎日のクォータが午前 0 時（ 中央時間にリセットされるまで、別のジョブを作成またはキューに入れることができせん。 その時点まで、「1029、書き出し日の割り当て量を超過」というエラーが返されます。 毎日の割り当て量を除き、ファイルの最大サイズはありません。

ジョブがキューに入れられるか処理されると、完了まで実行されます（エラーまたはジョブのキャンセルが許可されません）。 ジョブが何らかの理由で失敗した場合は、再作成する必要があります。 ジョブが完了状態に達した場合にのみ、ファイルが完全に書き込まれます（部分的なファイルは書き込まれません）。 ファイルが完全に書き込まれたことを確認するには、ファイルの SHA-256 ハッシュを計算し、ジョブステータスエンドポイントから返されるチェックサムと比較します。

「Get Export Lead/Activity/Program Member Jobs」を呼び出すことで、現在の日付に使用されているディスクの合計容量を判断できます。 これらのエンドポイントは、過去 7 日間のすべてのジョブのリストを返します。 このリストは、status 属性と finishedAt 属性を使用して、当日に完了したジョブのみにフィルタリングできます。 次に、これらのジョブのファイルサイズを合計して、使用される合計量を算出します。 ディスク領域を再利用するためにファイルを削除する方法はありません。

権限

一括抽出では、Marketo REST API と同じ権限モデルを使用し、使用するために特別な権限は必要ありませんが、エンドポイントのセットごとに専用の権限が必要になります。

一括抽出ジョブは、ジョブを作成した API ユーザーからのみアクセスできます（ステータスのポーリングやファイル内容の取得など）。

Bulk Extract エンドポイントは、Marketo ワークスペースを認識しません。 抽出リクエストには、カスタムサービスの API のみのユーザーを定義する方法に関係なく、常にすべてのワークスペースにわたるデータが含まれます。

ジョブの作成

Marketoの一括抽出 API は、データ抽出を開始および実行するためのジョブの概念を使用します。 簡単なリードエクスポートジョブの作成を見てみましょう。

POST /bulk/v1/leads/export/create.json

{
   "fields": [
      "firstName",
      "lastName"
   ],
   "format": "CSV",
   "columnHeaderNames": {
      "firstName": "First Name",
      "lastName": "Last Name"
   },
   "filter": {
      "createdAt": {
         "startAt": "2023-01-01T00:00:00Z",
         "endAt": "2023-01-31T00:00:00Z"
      }
   }
}

この単純なリクエストでは、2023 年 1 月 1 日（PT）から 2023 年 1 月 31 日（PT）の間に作成された各リードを含む、「firstName」フィールドと「lastName」フィールドに含まれる値を返すジョブを作成し、列ヘッダー「First Name」と「Last Name」を CSV ファイルとして含めます。

{
   "requestId": "e42b#14272d07d78",
   "success": true,
   "result": [
      {
         "exportId": "ce45a7a1-f19d-4ce2-882c-a3c795940a7d",
         "status": "Created",
         "createdAt": "2023-01-21T11:47:30-08:00",
         "queuedAt": "2023-01-21T11:48:30-08:00",
         "format": "CSV",
      }
   ]
}

ジョブを作成すると、exportId 属性のジョブ ID が返されます。 その後、このジョブ ID を使用して、ジョブをキューに入れたり、キャンセルしたり、ステータスを確認したり、完了したファイルを取得したりできます。

共通パラメーター

各ジョブ作成エンドポイントは、一括抽出ジョブのファイル形式、フィールド名、フィルターを設定するための一般的なパラメーターをいくつか共有しています。 抽出ジョブの各サブタイプには、追加のパラメーターを指定できます。

ジョブを取得中

最近のジョブを取得する必要が生じる場合があります。 これは、対応するオブジェクトタイプの「書き出しジョブを取得」を使用すると簡単に実行できます。 各 Get 書き出しジョブ エンドポイントは、status のフィルターフィールド、  返されるジョブの数を制限し、大きな結果セットをページングする nextPageToken を batchSize 定します。 ステータスフィルターでは、エクスポートジョブの有効な各ステータス（作成済み、待機中、処理中、キャンセル済み、完了および失敗）がサポートされます。 batchSize の最大値とデフォルトは 300 です。 リードエクスポートジョブのリストを取得しましょう。

GET /bulk/v1/leads/export.json?status=Completed,Failed

{
   "requestId": "e42b#14272d07d78",
   "success": true,
   "result": [
      {
         "exportId": "ce45a7a1-f19d-4ce2-882c-a3c795940a7d",
         "status": "Completed",
         "createdAt": "2017-01-21T11:47:30-08:00",
         "queuedAt": "2017-01-21T11:48:30-08:00",
         "startedAt": "2017-01-21T11:51:30-08:00",
         "finishedAt": "2017-01-21T12:59:30-08:00",
         "format": "CSV",
         "numberOfRecords": 122323,
         "fileSize": 123424,
         "fileChecksum": "sha256:c16514c7e80fcac5ea055dacae9617fc3c29aff5365e3743071313ce0ed2a815"
      }
      ...
   ]
}

エンドポイントは status 結果の配列のそのオブジェクトタイプに対して過去 7 日間に作成された各ジョブの応答で応答します。 応答には、呼び出しを行う API ユーザーが所有するジョブの結果のみが含まれます。

ジョブの開始

ジョブ ID を手にして、ジョブを開始しましょう。

POST /bulk/v1/leads/export/{exportId}/enqueue.json

これにより、ジョブの実行が開始され、ステータス応答が返されます。 エクスポートは常に非同期で行われるので、ジョブのステータスをポーリングして、完了したかどうかを確認する必要があります。 特定のジョブのステータスは、60 秒に 1 回以上更新されないので、それ以上の頻度でポーリングしないでください。 ただし、ほとんどのユースケースでは、5 分に 1 回を超える頻度でポーリングを行う必要はありません。 正常に書き出された各データは 10 日間保持されます。

ジョブステータスのポーリング

ジョブのステータスは簡単に判断できます。

ステータスは、作成した API ユーザーと同じ API ユーザーによって作成されたジョブに対してのみポーリングできます。

GET /bulk/v1/leads/export/{exportId}/status.json

{
   "requestId": "e42b#14272d07d78",
   "success": true,
   "result": [
      {
         "exportId": "ce45a7a1-f19d-4ce2-882c-a3c795940a7d",
         "status": "Completed",
         "createdAt": "2017-01-21T11:47:30-08:00",
         "queuedAt": "2017-01-21T11:48:30-08:00",
         "startedAt": "2017-01-21T11:51:30-08:00",
         "finishedAt": "2017-01-21T12:59:30-08:00",
         "format": "CSV",
         "numberOfRecords": 122323,
         "fileSize": 123424,
         "fileChecksum": "sha256:d9c73f0b6960c71623c8bafe29603b3e8e20fd0e4eeaefd119c0227506ea9be4"
      }
   ]
}

内部の status メンバーは、ジョブの進行状況を示します。Created、Queued、Processing、Cancelled、Completed、Failed のいずれかの値になります。 この場合、ジョブが完了したので、ポーリングを停止して、ファイルを取得し続けることができます。 完了すると、fileSize メンバーはファイルの全長をバイト単位で示し、fileChecksum メンバーにはファイルの SHA-256 ハッシュが含まれます。 ジョブのステータスは、完了または失敗ステータスに達してから 30 日間利用できます。

データの取得

ジョブが完了したら、ファイルを簡単に取得できます。

GET /bulk/v1/leads/export/{exportId}/file.json

応答には、ジョブの設定方法に従ってフォーマットされたファイルが含まれています。 エンドポイントは、ファイルのコンテンツを使用して応答します。 ジョブが完了していない場合や、無効なジョブ ID が渡された場合は、他の多くのMarketo REST エンドポイントとは異なり、ファイルエンドポイントは 404 Not Found のステータスで応答し、ペイロードとしてプレーンテキストのエラーメッセージが表示されます。

抽出されたデータの部分的で再開に適した取得をサポートするために、ファイルエンドポイントはオプションで bytes タイプの HTTP ヘッダー Range をサポートします（RFC 7233 準拠）。 ヘッダーが設定されていない場合は、コンテンツ全体が返されます。 ファイルの最初の 10,000 バイトを取得するには、GETリクエストの一部として、バイト 0 から始まる次のヘッダーをエンドポイントに渡します。

Range: bytes=0-9999

部分ファイルを取得する場合、エンドポイントは応答としてステータスコード 206 を返し、Accept-ranges、Content-Length および Content-Range ヘッダーを返します。

Accept-Ranges: bytes
Content-Length: 1000
Content-Range: bytes 0-9999/123424

部分的な取得と再開

ファイルは、一部を取得することも、Range ヘッダーを使用して後で再開することもできます。 ファイルの範囲は、バイト 0 から始まり、fileSize から 1 を引いた値で終わります。 また、ファイルの長さは、Get Export File エンドポイントを呼び出す際に、Content-Range 応答ヘッダーの値の分母としてレポートされます。 部分的に検索が失敗した場合は、後で再開できます。 例えば、1000 バイトの長さのファイルを取得しようとしたときに、最初の 725 バイトしか受け取っていない場合、エンドポイントを再度呼び出し、新しい範囲を渡すことにより、失敗した時点から取得を再試行できます。

Range: bytes 724-999

これは、ファイルの残りの 275 バイトを返します。

ファイルの整合性の検証

ジョブステータスエンドポイントは、「完了」の場合、fileChecksum 属性のチェックサム status 返します。 チェックサムは、書き出されたファイルの SHA-256 ハッシュです。 チェックサムを取得したファイルの SHA-256 ハッシュと比較して、ファイルが完全であることを確認できます。

チェックサムを含む応答の例を次に示します。

{
    "exportId": "45547609-6732-418a-bb7b-17b0160b2317",
    "format": "CSV",
    "status": "Completed",
    "createdAt": "2019-06-04T23:13:12Z",
    "queuedAt": "2019-06-04T23:14:02Z",
    "startedAt": "2019-06-04T23:15:19Z",
    "finishedAt": "2019-06-04T23:36:40Z",
    "numberOfRecords": 1776,
    "fileSize": 400785,
    "fileChecksum": "sha256:83aca1351c9398d2770330e21a9e278880fd2f1eeaf8c8238bf7676d5c21d1c6"
}

次に、sha256sum コマンドラインユーティリティを使用して「bulk_lead_export.csv」という名前の取得したファイルの SHA-256 ハッシュを作成する例を示します。

$ sha256sum bulk_lead_export.csv
83aca1351c9398d2770330e21a9e278880fd2f1eeaf8c8238bf7676d5c21d1c6 *bulk_lead_export.csv

ジョブのキャンセル

ジョブが誤って設定されていた場合や不要になった場合は、簡単にキャンセルできます。

POST /bulk/v1/leads/export/{exportId}/cancel.json

{
   "requestId": "e42b#14272d07d78",
   "success": true,
   "result": [
      {
         "exportId": "ce45a7a1-f19d-4ce2-882c-a3c795940a7d",
         "status": "Cancelled",
         "createdAt": "2017-01-21T11:47:30-08:00",
         "format": "CSV",
      }
   ]
}

ジョブがキャンセルされたことを示すステータスで応答します。