カスタムオブジェクトの一括抽出
Bulk Custom Object Extract REST APIは、Marketoから大規模なカスタムオブジェクトレコードのセットを取得します。 これらのAPIを使用すると、Marketoと外部システム、ETL、データウェアハウス、アーカイブ間で継続的にデータをやり取りできます。
このAPIは、リードに直接リンクされたファーストレベルのMarketo カスタムオブジェクトレコードを書き出します。 カスタムオブジェクト名とリンクされたリードのリストを指定します。 各リードについて、APIは一致するリンクされたカスタムオブジェクトレコードをエクスポートファイルの行として書き込みます。
カスタムオブジェクトデータは、Marketo UI🔗のリードの詳細ページの「 カスタムオブジェクト」タブで確認できます。
権限
API ユーザーには、読み取り専用カスタムオブジェクト権限、読み取り/書き込みカスタムオブジェクト権限、またはその両方を持つ役割が必要です。
フィルター
カスタムオブジェクト抽出フィルターは、カスタムオブジェクトにリンクされたリードのリストを指定します。 リストされたリードが指定されたカスタムオブジェクト名に一致するレコードにリンクされている場合、APIはそれらのレコードをエクスポートファイルに書き込みます。
書き出しジョブごとに1つのフィルタータイプのみを指定します。
updatedAtstartAtおよびendAt  を含むJSON オブジェクトを受け入れます。;startAtは低い透かしを表す日時を受け入れ、endAtは高い透かしを表す日時を受け入れます。 範囲は 31日以内にする必要があります。 このフィルタータイプのジョブは、日付範囲内で更新されたアクセス可能なすべてのレコードを返します。 日付と時刻は、ミリ秒を含まない ISO-8601 形式にする必要があります。staticListNamestaticListIdsmartListName*smartListId*一部のサブスクリプションはこのフィルタータイプをサポートしていません。 使用できない場合は、「リードジョブを書き出し作成」エンドポイントは1035, Unsupported filter type for target subscriptionを返します。 Marketo サポートに連絡して、サブスクリプションにこの機能をリクエストしてください。
オプション
カスタムオブジェクトの書き出し作成ジョブ エンドポイントには、次のオプションがあります。
- 書き出しファイルに含めるフィールドを指定します。
- 書き出した列ヘッダーの名前を変更します。
- 書き出しファイル形式を指定します。
fieldscolumnHeaderNamesformatジョブの作成
カスタムオブジェクトジョブの作成 エンドポイントを使用して、書き出しジョブを定義します。
リクエストでは、次のパラメーターを使用します。
apiName:必須のパス パラメーター。 カスタムオブジェクトの説明 エンドポイントから返された名前を使用して、書き出すMarketo カスタムオブジェクトを指定します。 CRM カスタムオブジェクトは許可されていません。filter:必須。 静的リストまたはスマートリストを参照して、リンクされたリードを指定します。fields:必須。 書き出しファイルに含めるカスタムオブジェクト属性のAPI名を指定します。format:オプション。 書き出しファイル形式を指定します。columnHeaderNames:オプション。 置換する列ヘッダー名を指定します。
この例では、Color、Make、Model、VINのフィールドを持つCar カスタムオブジェクトを使用しています。 リンクフィールドはリード ID で、重複の除外フィールドは VIN です。
カスタムオブジェクトの定義
カスタムオブジェクトフィールド
カスタムオブジェクトを記述呼び出して カスタムオブジェクト属性をプログラムで調べます。 応答はfieldsの属性を返します。
GET /rest/v1/customobjects/car_c/describe.json
{
"requestId": "148ef#1793e00f64f",
"result": [
{
"name": "car_c",
"displayName": "Car",
"description": "It's a car.",
"createdAt": "2021-05-05T16:14:41Z",
"updatedAt": "2021-05-05T16:14:42Z",
"idField": "marketoGUID",
"dedupeFields": [
"vIN"
],
"searchableFields": [
[
"vIN"
],
[
"marketoGUID"
],
[
"leadID"
]
],
"relationships": [
{
"field": "leadID",
"type": "child",
"relatedTo": {
"name": "Lead",
"field": "Id"
}
}
],
"fields": [
{
"name": "createdAt",
"displayName": "Created At",
"dataType": "datetime",
"updateable": false,
"crmManaged": false
},
{
"name": "marketoGUID",
"displayName": "Marketo GUID",
"dataType": "string",
"length": 36,
"updateable": false,
"crmManaged": false
},
{
"name": "updatedAt",
"displayName": "Updated At",
"dataType": "datetime",
"updateable": false,
"crmManaged": false
},
{
"name": "color",
"displayName": "Color",
"dataType": "string",
"length": 255,
"updateable": true,
"crmManaged": false
},
{
"name": "leadID",
"displayName": "Lead ID",
"dataType": "integer",
"updateable": true,
"crmManaged": false
},
{
"name": "make",
"displayName": "Make",
"dataType": "string",
"length": 255,
"updateable": true,
"crmManaged": false
},
{
"name": "model",
"displayName": "Model",
"dataType": "string",
"length": 255,
"updateable": true,
"crmManaged": false
},
{
"name": "vIN",
"displayName": "VIN",
"dataType": "string",
"length": 255,
"updateable": true,
"crmManaged": false
}
]
}
],
"success": true
}
カスタムオブジェクトレコードを作成し、各レコードをリードにリンクするには、 カスタムオブジェクトの同期 エンドポイントを使用します。 1つのリードを複数のカスタムオブジェクトレコードにリンクして、1対多の関係を作成できます。
POST /rest/v1/customobjects/car_c.json
{
"action":"createOrUpdate",
"input":[
{
"leadId": 11,
"color": "Pearl White",
"make": "Tesla",
"model": "Model S",
"vIN": "5YJSA1E41FF156789"
},
{
"leadId": 12,
"color": "Midnight Silver Metallic",
"make": "Tesla",
"model": "Model X",
"vIN": "LRWXB2B41FF198765"
},
{
"leadId": 13,
"color": "Fusion Red",
"make": "Tesla",
"model": "Roadster",
"vIN": "SFGRC3C41FF154321"
}
]
}
{
"requestId": "50d9#1793e066088",
"result": [
{
"seq": 0,
"marketoGUID": "d911eaa1-fd0b-4a99-9b71-c6a7233c782c",
"status": "created"
},
{
"seq": 1,
"marketoGUID": "20d04ffb-51f0-4336-924c-c783b9bb4215",
"status": "created"
},
{
"seq": 2,
"marketoGUID": "e7da4331-8e7a-473b-85c8-047638eb6c7f",
"status": "created"
}
],
"success": true
}
この例の3つのリードは、Car Buyersの静的リストに属しており、1081のidがあります。 リスト ID 🔗 エンドポイントでGet リードを呼び出して、リスト メンバーを取得します。
GET /rest/v1/lists/1081/leads.json
{
"requestId": "d023#1793e1e982b",
"result": [
{
"id": 11,
"firstName": "Hanna",
"lastName": "Crawford",
"email": "208161Hanna.Crawford@pookmail.com",
"updatedAt": "2020-01-16T02:38:22Z",
"createdAt": "2017-07-27T01:38:42Z"
},
{
"id": 12,
"firstName": "Bertha",
"lastName": "Fulton",
"email": "208160Bertha.Fulton@trashymail.com",
"updatedAt": "2020-01-16T02:38:22Z",
"createdAt": "2017-07-27T01:38:42Z"
},
{
"id": 13,
"firstName": "Faith",
"lastName": "England",
"email": "208159Faith.England@dodgit.com",
"updatedAt": "2020-01-16T02:38:22Z",
"createdAt": "2017-07-27T01:38:42Z"
}
],
"success": true
}
これらのレコードを取得するには、 カスタムオブジェクトジョブの作成 エンドポイントを呼び出します。 fieldsのカスタムオブジェクト属性とfilterの静的リスト IDを指定します。
POST /bulk/v1/customobjects/car_c/export/create.json
{
"fields": [
"leadId",
"color",
"make",
"model",
"vIN"
],
"filter": {
"staticListId": 1081
}
}
{
"requestId": "8d2f#1793e289e87",
"result": [
{
"exportId": "f2c03f1d-226f-47c1-a557-357af8c2b32a",
"format": "CSV",
"status": "Created",
"createdAt": "2021-05-05T20:12:01Z"
}
],
"success": true
}
応答は、ジョブが作成されたことを確認しますが、書き出しは自動的に開始されません。 apiNameと返されたexportIdをEnqueue カスタムオブジェクト書き出しジョブ エンドポイントに渡して、ジョブを開始します。
POST /bulk/v1/customobjects/car_c/export/f2c03f1d-226f-47c1-a557-357af8c2b32a/enqueue.json
{
"requestId": "cfaf#1793e2a0762",
"result": [
{
"exportId": "f2c03f1d-226f-47c1-a557-357af8c2b32a",
"format": "CSV",
"status": "Queued",
"createdAt": "2021-05-05T20:12:01Z",
"queuedAt": "2021-05-05T20:13:32Z"
}
],
"success": true
}
エンキュー応答は、最初にQueued ステータスを返します。 書き出しスロットが使用可能になると、ステータスがProcessingに変わります。
ジョブステータスのポーリング
同じAPI ユーザーが作成したジョブに対してのみ、ステータスを取得できます。
書き出しは非同期で実行されるので、 カスタムオブジェクトジョブステータスの書き出しを取得 エンドポイントを使用して、進行状況を調査します。 ステータスは60秒ごとに1回しか更新されないので、より頻繁にポーリングしないでください。
ステータスはCreated、Queued、Processing、Canceled、CompletedまたはFailedです。
GET /bulk/v1/customobjects/{apiName}/export/{exportId}/status.json
{
"requestId": "14daa#1793e2cf9de",
"result": [
{
"exportId": "f2c03f1d-226f-47c1-a557-357af8c2b32a",
"format": "CSV",
"status": "Processing",
"createdAt": "2021-05-05T20:12:01Z",
"queuedAt": "2021-05-05T20:13:32Z",
"startedAt": "2021-05-05T20:14:15Z"
}
],
"success": true
}
この応答は、ジョブがまだ処理中であるため、ファイルが利用できないことを示します。 ジョブのステータスがCompletedに変更されると、ファイルをダウンロードする準備が整います。
{
"requestId": "14daa#1793e2cf9de",
"result": [
{
"exportId": "f2c03f1d-226f-47c1-a557-357af8c2b32a",
"format": "CSV",
"status": "Completed",
"createdAt": "2021-05-05T20:12:01Z",
"queuedAt": "2021-05-05T20:13:32Z",
"startedAt": "2021-05-05T20:14:15Z",
"finishedAt": "2021-05-05T20:14:28Z",
"numberOfRecords": 3,
"fileSize": 182,
"fileChecksum": "sha256:fac0cabc2352229c12e18b2fde03d1f24178bc71e9e926f520ae8d61bbe98c01"
}
],
"success": true
}
データの取得
完了したカスタムオブジェクトの書き出しを取得するには、apiNameとexportIdを カスタムオブジェクトファイルの書き出しの取得 エンドポイントに渡します。
エンドポイントは、ジョブ用に設定された形式でファイルを返します。 要求されたカスタムオブジェクト属性にデータが含まれていない場合、対応する書き出しフィールドにはnullが含まれます。
GET /bulk/v1/customobjects/car_c/export/f2c03f1d-226f-47c1-a557-357af8c2b32a/file.json
leadId,color,make,model,vIN
11,Pearl White,Tesla,Model S,5YJSA1E41FF156789
12,Midnight Silver Metallic,Tesla,Model X,LRWXB2B41FF198765
13,Fusion Red,Tesla,Roadster,SFGRC3C41FF154321
部分的または再開可能な取得の場合、ファイルエンドポイントは、範囲タイプがbytesのオプションのHTTP Range ヘッダーをサポートします。 ヘッダーを設定しない場合、エンドポイントはファイル全体を返します。 詳しくは、一括抽出を参照してください。
ジョブのキャンセル
正しく設定されていないか、不要になったジョブをキャンセルするには、 カスタムオブジェクトジョブの書き出しをキャンセル エンドポイントを呼び出します。 応答ステータスは、ジョブがキャンセルされたことを示します。
POST /bulk/v1/customobjects/car_c/export/f2c03f1d-226f-47c1-a557-357af8c2b32a/cancel.json
{
"requestId": "e5f9#179391286a7",
"result": [
{
"exportId": "4a8cdd80-0d16-4dd6-9923-6ec97e30e91b",
"format": "CSV",
"status": "Cancelled",
"createdAt": "2021-05-04T20:24:33Z"
}
],
"success": true
}