リードの一括抽出

リード抽出の一括処理エンドポイント リファレンス

Bulk Lead Extract REST APIは、Marketoからリード/個人レコードの大規模なセットを取得します。 また、レコード作成日、最新の更新、静的リストメンバーシップ、スマートリストメンバーシップにもとづいて、リードを段階的に取得することもできます。

Bulk Lead Extractを使用すれば、ETL、データウェアハウス、アーカイブワークフローなどのMarketoと外部システムとの間で継続的にデータをやり取りできます。

権限

ジョブを所有するAPI ユーザーは、読み取り専用リード権限、読み取り/書き込みリード権限、またはその両方の権限を持つ役割を持っている必要があります。

フィルター

リード書き出しジョブは、複数のフィルタータイプをサポートしています。 各エクスポートジョブで使用できるフィルタータイプは1つだけです。

updatedAt、smartListNameおよびsmartListIdのフィルターには、すべてのサブスクリプションで利用できないインフラストラクチャが必要です。

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

オプション

リードジョブの作成エンドポイントには、書き出されたフィールドの選択、列ヘッダーの名前変更、ファイル形式の設定を行うオプションが用意されています。

ジョブの作成

書き出しリードジョブの作成 エンドポイントを使用して、書き出しジョブを定義します。 書き出すfields、1つのfilter タイプとそのパラメーター、ファイル format、および任意のカスタム列ヘッダー名を指定します。

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

{
   "fields": [
      "firstName",
      "lastName",
      "id",
      "email"
   ],
   "format": "CSV",
   "columnHeaderNames": {
      "firstName": "First Name",
      "lastName": "Last Name",
      "id": "Marketo Id",
      "email": "Email Address"
   },
   "filter": {
      "createdAt": {
         "startAt": "2017-01-01T00:00:00Z",
         "endAt": "2017-01-31T00:00:00Z"
      }
   }
}

このリクエストは、2017年1月1日から2017年1月31日の間に作成されたリードのエクスポートジョブを作成します。 書き出しには、firstName、lastName、id、およびemail フィールドの値が含まれます。

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

応答は、ジョブが作成されたが開始されていないことを確認します。 ジョブを開始するには、作成応答からexportIdを含むEnqueue Export Lead Job エンドポイントを呼び出します。

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

{
    "requestId": "147e4#16b24d9b913",
    "result": [
        {
            "exportId": "fad2cd1b-e822-4025-be1e-9caa9cf1d4b8",
            "format": "CSV",
            "status": "Queued",
            "createdAt": "2019-06-04T23:35:43Z",
            "queuedAt": "2019-06-04T23:36:17Z"
        }
    ],
    "success": true
}

エンキュー応答の値はstatusで「キューに入れました」です。 書き出しスロットが使用可能になると、ステータスは「処理中」に変わります。

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

同じAPI ユーザーが作成したジョブに対してのみ、ステータスを取得できます。

リード書き出しジョブは非同期で実行されます。 Get Export Lead Job Status エンドポイントをポーリングして、ジョブの進行状況を追跡します。

ステータスは60秒ごとに1回だけ更新されます。 より頻繁に調査しないでください。ほとんどの場合、その間隔はまだ過剰です。

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

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

この応答は、ジョブがまだ処理中であるため、ファイルが利用できないことを示します。 ジョブのステータスが「完了」に変わると、ファイルをダウンロードする準備が整います。

status フィールドは、次のいずれかの値を返すことができます。

データの取得

完了したリード書き出しを取得するには、​ リードファイルの書き出しの取得 エンドポイントにexportIdを呼び出します。

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

応答本文には、ジョブ用に設定された形式のファイルが含まれます。

リクエストされたリードフィールドにデータが含まれていない場合、書き出しファイルの対応するフィールドにnullが含まれます。 次の例では、返されたリードのメールフィールドが空です。

firstName,lastName,email,cookies
Russell,Wilson,null,_mch-localhost-1536605780000-12105

部分的または再開可能な取得の場合、ファイルエンドポイントは、bytes タイプのオプションのHTTP Range ヘッダーをサポートします。 ヘッダーを設定しない場合、エンドポイントはすべてのコンテンツを返します。 Marketo 一括抽出でのRange ヘッダーの使用について詳しくは、こちらを参照してください。

ジョブのキャンセル

正しく設定されていないジョブまたは不要なジョブをキャンセルするには、​ リードジョブのエクスポートをキャンセル ​ エンドポイントを呼び出します。

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"
      }
   ]
}

応答は、ジョブがキャンセルされたことを確認します。