一括抽出

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

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

Note: Bulk API エンドポイントには、他のエンドポイントのように「/rest」というプレフィックスは付きません。

認証

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

制限

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

キュー

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

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

ファイルサイズ

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

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

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

リード／アクティビティ／プログラムメンバーを書き出しジョブを取得を呼び出すことで、現在の日付に使用されたディスクの合計量を判断できます。 これらのエンドポイントは、過去 7 日間のすべてのジョブのリストを返します。 このリストは、現在の日付に完了したジョブのみにフィルタリングできます（status 属性と finishedAt 属性を使用）。 次に、これらのジョブのファイルサイズを合計して、使用される合計量を算出します。 ディスクスペースを再利用するのにファイルを削除する方法はありません。

権限

一括抽出では、Marketo REST API と同じ権限モデルが使用され、使用する追加の特別な権限は必要ありませんが、各エンドポイントのセットには特定の権限が必要です。

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

一括抽出エンドポイントでは、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"
      }
   }
}

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

{
   "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 を使用して、ジョブをキューに入れたり、キャンセルしたり、ステータスを確認したり、完了したファイルを取得したりできます。

一般的なパラメーター

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

ジョブの取得

場合によっては、最近のジョブを取得する必要があります。 これは、対応するオブジェクトタイプの「書き出しジョブを取得」を使用すると簡単に実行できます。 各「書き出しジョブを取得」エンドポイントでは、status フィルターフィールド、返されるジョブの数を制限する batchSize、大規模な結果セットをページングする nextPageToken をサポートしています。 ステータスフィルターでは、書き出しジョブの有効なステータス（作成済み、キュー済み、処理中、キャンセル済み、完了、失敗）をサポートしています。 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"
      }
      ...
   ]
}

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

ジョブの開始

ジョブ ID を用意したら、ジョブを開始しましょう。

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

これにより、ジョブの実行が開始され、ステータス応答が返されます。 書き出しは常に非同期で実行されるので、ジョブのステータスをポーリングして、完了したかどうかを判断する必要があります。 特定のジョブのステータスは 60 秒ごとに 1 回より頻繁に更新されることはありません。したがって、ステータスはそれより頻繁にポーリングする必要はありません。 ただし、ほとんどのユースケースでは、5 分ごとに 1 回よりも頻繁にポーリングする必要はありません。 成功した各書き出しのデータは 10 日間保持されます。

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

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

ステータスをポーリングできるのは、ジョブを作成した同じ 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 メンバーはジョブの進行状況を示し、作成済み、キュー済み、処理中、キャンセル済み、完了、失敗のいずれかの値になります。 この場合、ジョブは完了しているので、ポーリングを停止してファイルを引き続き取得できます。 完了すると、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 を引いた値で終わります。 また、ファイルの長さは、「書き出しファイルを取得」エンドポイントを呼び出す際に、Content-Range 応答ヘッダーの値の分母としても報告されます。 取得が部分的に失敗した場合は、後で再開できます。 例えば、長さが 1000 バイトのファイルを取得しようとしたが、最初の 725 バイトしか受信されなかった場合、エンドポイントを再度呼び出して新しい範囲を渡すことで、失敗した時点から取得を再試行できます。

Range: bytes 724-999

これにより、ファイルの残りの 275 バイトが返されます。

ファイルの整合性の検証

ジョブステータスエンドポイントでは、status が「完了」の場合に、fileChecksum 属性にチェックサムを返します。 チェックサムは、書き出したファイルの 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",
      }
   ]
}

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