アクティビティの一括抽出
Bulk Activity Extract REST APIは、Marketoから大量のアクティビティデータを取得します。 CRM統合、ETL、データウェアハウス、データアーカイブなど、低遅延を必要としないプロセスに使用できます。
権限
API ユーザーには、「読み取り専用アクティビティ」または「読み取り/書き込みアクティビティ」権限が必要です。
フィルター
createdAtstartAtとendAtを含むJSON オブジェクト。 startAtは透かしの少ない日時で、endAtは透かしの多い日時です。 範囲は 31日以内にする必要があります。 このジョブは、日付範囲内で作成されたすべてのアクセス可能なレコードを返します。 ミリ秒なしでISO-8601日時値を使用します。activityTypeIdsprimaryAttributeValueIds オプション primaryattributevalueids-options
primaryAttributeValueIdsを使用する場合は、activityTypeIds フィルターも含める必要があります。 このフィルターには、対応するアセットグループに一致するアクティビティ IDのみを含めることができます。 例えば、Web フォームアセットをフィルタリングする場合、activityTypeIdsには「フォームに入力」アクティビティタイプ IDのみを含めることができます。
次のリクエストには、primaryAttributeValueIds フィルターが含まれています。
{
"filter": {
"createdAt": {
"startAt": "2021-07-01T23:59:59-00:00",
"endAt": "2021-07-02T23:59:59-00:00"
},
"activityTypeIds": [
2
],
"primaryAttributeValueIds": [
16,102,95,8
]
}
}
primaryAttributeValueIds と primaryAttributeValues は併用できません。
primaryAttributeValues オプション primaryattributevalues-options
<program>.<asset>表記法を使用して、マーケティングプログラム、静的リスト、およびWeb フォームアセットグループの名前を指定します。 例えば、「GL_OP_ALL_2021」プログラムの「MPS Outbound」フォームを「GL_OP_ALL_2021.MPS Outbound」と指定します。
次のリクエストには、primaryAttributeValues フィルターが含まれています。
{
"filter": {
"createdAt": {
"startAt": "2021-07-01T23:59:59-00:00",
"endAt": "2021-07-02T23:59:59-00:00"
},
"activityTypeIds": [
2
],
"primaryAttributeValues": [
"GL_OP_ALL_2021.MPS Outbound"
]
}
}
primaryAttributeValuesを使用する場合は、activityTypeIds フィルターも含める必要があります。 このフィルターには、対応するアセットグループに一致するアクティビティ IDのみを含めることができます。 例えば、Web フォームアセットをフィルタリングする場合、activityTypeIdsには「フォームに入力」アクティビティタイプ IDのみを含めることができます。
primaryAttributeValues と primaryAttributeValueIds は併用できません。
オプション
filtercreatedAt フィルターのみを含めます。 activityTypeIds フィルターを含めることもできます。 書き出しジョブは、結果のアクティビティセットを返します。formatcolumnHeaderNamesfieldsmarketoGUID、leadId、activityDate、activityTypeId、campaignId、primaryAttributeValueId、primaryAttributeValueおよびattributesが含まれます。 サブセットを返すには、このリストから"fields": ["leadId", "activityDate", "activityTypeId"]などのフィールドを指定します。 actionResultを指定して、アクティビティ アクション ("succeeded", "skipped", or "failed")を含めることもできます。ジョブの作成
取得するレコードを定義するエクスポート ジョブを作成します。 書き出しアクティビティ ジョブの作成 エンドポイントを使用します。
すべてのジョブにはcreatedAt フィルターが必要です。 そのstartAtおよびendAt日時パラメーターは、許可されたアクティビティの作成日の最も早い日付と最も新しい日付を定義します。 関連しないアクティビティタイプを除外するには、オプションのactivityTypeIds フィルターも含めます。
次のリクエストは、日付範囲内の選択したアクティビティタイプに対してCSV書き出しジョブを作成します。
POST /bulk/v1/activities/export/create.json
{
"format": "CSV",
"filter": {
"createdAt": {
"startAt": "2017-07-01T23:59:59-00:00",
"endAt": "2017-07-31T23:59:59-00:00"
},
"activityTypeIds": [
1,
12,
13
]
}
}
{
"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とステータス「作成済み」を返します。 作成されたジョブはまだ処理キューにありません。
ジョブをキューに追加するには、作成応答からexportIdを含むEnqueue Export Activity Job エンドポイントを呼び出します。
POST /bulk/v1/activities/export/{exportId}/enqueue.json
{
"requestId": "e42b#14272d07d78",
"success": true,
"result": [
{
"exportId": "ce45a7a1-f19d-4ce2-882c-a3c795940a7d",
"status": "Queued",
"createdAt": "2017-01-21T11:47:30-08:00",
"queuedAt": "2017-01-21T11:48:30-08:00",
"format": "CSV"
}
]
}
応答ステータスが「キューに入りました」。 ワーカーが使用可能になると、ステータスは「処理中」に変わり、ジョブはMarketoからレコードの集計を開始します。
ジョブステータスのポーリング
ジョブステータスを取得できるのは、同じ API ユーザによって作成されたジョブのみです。
一括アクティビティ抽出では、ジョブを非同期で処理します。 Get Export Activity Job Status エンドポイントをポーリングして、ジョブがいつ完了したかを判断します。
GET /bulk/v1/activities/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": 15423,
"fileSize": 12342,
"fileChecksum": "sha256:c16514c7e80fcac5ea055dacae9617fc3c29aff5365e3743071313ce0ed2a815"
}
]
}
status フィールドは、次のいずれかの値を返します。
CreatedQueuedProcessingCanceledCompletedFailed
データの取得
ジョブのステータスが「完了」の場合、書き出しアクティビティファイルを取得 エンドポイントを使用して、書き出したデータを取得します。
GET /bulk/v1/activities/export/{exportId}/file.json
応答本文には、ジョブ用に設定された形式のファイルが含まれます。
リクエストされたアクティビティフィールドにデータが含まれていない場合、nullが対応する書き出しファイル フィールドに表示されます。 次の例は、書き出されたアクティビティデータを示しています。
marketoGUID,leadId,activityDate,activityTypeId,campaignId,primaryAttributeValueId,primaryAttributeValue,attributes
783957693,5414087,2022-02-13T14:06:20Z,104,8497,1670,MembershipTest1,"{""Reason"":""Changed by Smart Campaign MembershipTestCampaignStepChoice.MembershipTestCampaignStepChoiceSetUp action Change Data Value"",""Program Member ID"":3240303,""Acquired By"":true,""Old Status"":""Not in Program"",""New Status ID"":21,""Success"":false,""New Status"":""On List"",""Old Status ID"":20}"
783958220,5414094,2022-02-13T14:08:50Z,104,17240,3569,SuccessWebCPS,"{""Program Member ID"":3240305,""Acquired By"":false,""Old Status"":""Not in Program"",""New Status ID"":6,""Success"":true,""New Status"":""Attended"",""Old Status ID"":1}"
783958306,5414094,2022-02-13T14:09:16Z,104,17240,3569,SuccessWebCPS,"{""Program Member ID"":3240305,""Acquired By"":false,""Old Status"":""Attended"",""New Status ID"":6,""Success"":false,""New Status"":""Attended"",""Old Status ID"":6}"
783961924,5316669,2022-02-13T14:27:21Z,104,11614,2333,Nurture Automation,"{""Program Member ID"":3240306,""Acquired By"":false,""Old Status"":""Not in Program"",""New Status ID"":27,""Success"":false,""New Status"":""Member"",""Old Status ID"":26}"
部分的または再開可能な取得の場合、ファイルエンドポイントはbytes範囲のオプションのHTTP Range ヘッダーをサポートします。 このヘッダーを省略すると、エンドポイントはファイル全体を返します。 Range ヘッダーの使用について詳しくは、一括抽出を参照してください。
ジョブのキャンセル
正しく設定されていないジョブや不要なジョブを停止するには、書き出しアクティビティ ジョブをキャンセル エンドポイントを呼び出します。
POST /bulk/v1/activities/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"
}
]
}
応答ステータスは、ジョブがキャンセルされたことを示します。