一括抽出

Marketo Bulk Extractは、個人および人物関連の大量のデータを取得するためのインターフェイスを提供します。 インターフェイスは現在、次の4つのオブジェクトタイプで使用できます。

一括抽出を実行するには：

一括抽出ジョブは非同期で実行されます。 ジョブをポーリングして、書き出しステータスを取得します。

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

認証

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

制限

一部のサブスクリプションタイプでは、UpdatedAt およびスマートリストのリードの一括抽出フィルターは使用できません。 これらのフィルターが使用できない場合、Create Export Lead Job エンドポイントは「1035, Unsupported filter type for target subscription」というエラーを返します。 Marketo サポートに連絡して、サブスクリプションでこの機能を有効にします。

キュー

一括抽出APIでは、リード、アクティビティ、プログラムメンバー、カスタムオブジェクト間で共有される1つのジョブキューを使用します。 最初に、「リード/アクティビティ/プログラムメンバーの作成」ジョブエンドポイントを呼び出して、抽出ジョブを作成します。 次に、対応するEnqueue Export Lead/Activity/Program Member Job エンドポイントを呼び出して、ジョブをエンキューします。 ジョブは、コンピューティングリソースが利用可能になると開始されます。

キューには最大10個のジョブを含めることができます。 キューがいっぱいになったときにジョブをエンキューしようとすると、Enqueue Export Job エンドポイントに「1029, Too many jobs in queue」というエラーが返されます。 最大2つのジョブに「処理中」というステータスを設定し、同時に実行することができます。

ファイルサイズ

一括抽出APIは、一括抽出ジョブが取得するデータのディスク上のサイズに基づいて測定されます。 ファイルサイズをバイト単位で判断するには、書き出しジョブの完了したステータス応答のfileSize属性を読み取ります。

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

ジョブがキューまたは処理された後、エラーが発生するかジョブをキャンセルしない限り、ジョブは完了するまで実行されます。 ジョブが失敗した場合は、再作成する必要があります。

APIは、ジョブが完了状態に達したときにのみ完全なファイルを書き込みます。 部分的なファイルは書き込まれません。 ファイルを検証するには、その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"
      }
   }
}

このリクエストは、2023年1月1日から2023年1月31日の間に作成された各リードを書き出すジョブを作成します。 CSV ファイルには、「firstName」フィールドと「lastName」フィールドの値が含まれ、列ヘッダー「First Name」と「Last Name」が使用されます。

{
   "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 Export Jobs エンドポイントを使用して、最近のジョブを取得します。 各Get Export Jobs エンドポイントは、次のパラメーターをサポートしています。

次のリクエストは、ステータスが「完了」または「失敗」のリード書き出しジョブを取得します。

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日間にそのオブジェクトタイプ用に作成された各ジョブのステータス応答が含まれます。 応答には、呼び出しを行うAPI ユーザーが所有するジョブのみが含まれます。

ジョブの開始

ジョブを作成した後、ジョブ IDを使用してキューに入れ、ジョブを開始します。

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

リクエストはジョブを開始し、ステータス応答を返します。 書き出しは非同期で実行されるので、ジョブステータスをポーリングして、書き出しが完了したタイミングを判断します。

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

ステータスエンドポイントをポーリングして、ジョブの進行状況を判断します。 ジョブを作成したAPI ユーザーのみがステータスをポーリングできます。

ジョブステータスは、60秒ごとに1回以上更新されることはありません。 それ以上に頻繁に調査しないでください。 ほとんどのユースケースでは、5分に1回のポーリングで十分です。 成功した各書き出しのデータは 10 日間保持されます。

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が含まれている場合、ファイルエンドポイントは404 Not Found ステータスとプレーンテキストエラーメッセージを返します。 この応答は、他のほとんどのMarketo REST エンドポイント応答とは異なります。

部分的かつ再利用可能な取得をサポートするために、ファイルエンドポイントは、RFC 7233で定義されているように、bytes型のオプションのHTTP Range ヘッダーをサポートします。 ヘッダーを設定しない場合、エンドポイントはファイル全体を返します。

ファイルの最初の10,000 バイトを取得するには、GET リクエストに次のヘッダーを渡します。 範囲はバイト 0から始まります。

Range: bytes=0-9999

部分的なファイルの場合、エンドポイントはステータスコード 206、Accept-ranges、Content-Length、およびContent-Range ヘッダーを返します。

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

部分的な取得と再開

Range ヘッダーを使用して、ファイルの一部を取得するか、取得を再開します。 ファイル範囲はバイト 0から始まり、fileSize マイナス 1の値で終了します。 Get Export File エンドポイントは、ファイルの長さをContent-Range応答ヘッダーの分母としてレポートします。

取得が部分的に失敗した場合は、再開できます。 例えば、1000 バイトのファイルを取得しようとしたが、最初の725 バイトのみを受け取った場合は、エンドポイントを再度呼び出して新しい範囲を渡します。

Range: bytes=725-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",
      }
   ]
}

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