文件Marketo 開發人員指南

大量程式成員擷取

Last update: Tue Aug 05 2025 00:00:00 GMT+0000 (Coordinated Universal Time)
  • 主題：

建立對象：

  • 管理員

大量程式成員擷取端點參考

REST API的批次程式成員擷取集提供程式化介面，可從Marketo中擷取大型程式成員記錄集。 此為建議使用的介面，用於需要在Marketo與一或多個外部系統之間持續交換資料（用於ETL、資料倉儲和封存）的使用案例。

權限

大量程式成員擷取API要求擁有的API使用者必須擁有具有唯讀銷售機會或讀寫銷售機會許可權之一或兩者的角色。

說明

描述方案成員是欄位是否可供使用的主要信任來源，以及有關這些欄位的中繼資料。 name屬性包含REST API名稱。

GET /rest/v1/programs/members/describe.json

{
    "requestId": "f813#1791563c7cc",
    "result": [
        {
            "name": "API Program Membership",
            "description": "Map for API program membership fields",
            "createdAt": "2021-03-20T01:30:05Z",
            "updatedAt": "2021-03-20T01:30:05Z",
            "dedupeFields": [
                "leadId",
                "programId"
            ],
            "searchableFields": [
                [
                    "leadId"
                ],
                [
                    "myCustomField"
                ],
                [
                    "reachedSuccess"
                ],
                [
                    "statusName"
                ]
            ],
            "fields": [
                {
                    "name": "acquiredBy",
                    "displayName": "acquiredBy",
                    "dataType": "boolean",
                    "updateable": false,
                    "crmManaged": false
                },
                {
                    "name": "attendanceLikelihood",
                    "displayName": "attendanceLikelihood",
                    "dataType": "integer",
                    "updateable": false,
                    "crmManaged": false
                },
                {
                    "name": "createdAt",
                    "displayName": "createdAt",
                    "dataType": "datetime",
                    "updateable": false,
                    "crmManaged": false
                },
                {
                    "name": "isExhausted",
                    "displayName": "isExhausted",
                    "dataType": "boolean",
                    "updateable": false,
                    "crmManaged": false
                },
                {
                    "name": "leadId",
                    "displayName": "leadId",
                    "dataType": "integer",
                    "updateable": false,
                    "crmManaged": false
                },
                {
                    "name": "membershipDate",
                    "displayName": "membershipDate",
                    "dataType": "datetime",
                    "updateable": false,
                    "crmManaged": false
                },
                {
                    "name": "nurtureCadence",
                    "displayName": "nurtureCadence",
                    "dataType": "string",
                    "length": 4,
                    "updateable": false,
                    "crmManaged": false
                },
                {
                    "name": "program",
                    "displayName": "program",
                    "dataType": "string",
                    "length": 255,
                    "updateable": false,
                    "crmManaged": false
                },
                {
                    "name": "programId",
                    "displayName": "programId",
                    "dataType": "integer",
                    "updateable": false,
                    "crmManaged": false
                },
                {
                    "name": "reachedSuccess",
                    "displayName": "reachedSuccess",
                    "dataType": "boolean",
                    "updateable": false,
                    "crmManaged": false
                },
                {
                    "name": "reachedSuccessDate",
                    "displayName": "reachedSuccessDate",
                    "dataType": "datetime",
                    "updateable": false,
                    "crmManaged": false
                },
                {
                    "name": "registrationLikelihood",
                    "displayName": "registrationLikelihood",
                    "dataType": "integer",
                    "updateable": false,
                    "crmManaged": false
                },
                {
                    "name": "statusName",
                    "displayName": "statusName",
                    "dataType": "string",
                    "length": 255,
                    "updateable": false,
                    "crmManaged": false
                },
                {
                    "name": "statusReason",
                    "displayName": "statusReason",
                    "dataType": "string",
                    "length": 255,
                    "updateable": false,
                    "crmManaged": false
                },
                {
                    "name": "trackName",
                    "displayName": "trackName",
                    "dataType": "string",
                    "length": 255,
                    "updateable": false,
                    "crmManaged": false
                },
                {
                    "name": "updatedAt",
                    "displayName": "updatedAt",
                    "dataType": "datetime",
                    "updateable": false,
                    "crmManaged": false
                },
                {
                    "name": "waitlistPriority",
                    "displayName": "waitlistPriority",
                    "dataType": "integer",
                    "updateable": false,
                    "crmManaged": false
                },
                {
                    "name": "myCustomField",
                    "displayName": "myCustomField",
                    "dataType": "string",
                    "length": 255,
                    "updateable": true,
                    "crmManaged": false
                },
                {
                    "name": "registrationCode",
                    "displayName": "registrationCode",
                    "dataType": "string",
                    "length": 100,
                    "updateable": true,
                    "crmManaged": false
                },
                {
                    "name": "webinarUrl",
                    "displayName": "webinarUrl",
                    "dataType": "string",
                    "length": 2000,
                    "updateable": true,
                    "crmManaged": false
                }
            ]
        }
    ],
    "success": true
}

篩選器

計畫成員支援各種篩選選項。 可以為一個作業指定多個篩選器型別，在這種情況下，它們會一起進行AND運算。 您必須指定programId或programIds篩選器。 所有其他篩選器皆為選用專案。 updatedAt篩選器需要額外的基礎結構元件，這些元件尚未轉出到所有訂閱。

篩選器型別
資料類型
附註
programId
整數
接受方案的ID。 工作會傳回工作開始處理時屬於程式成員的所有可存取記錄。使用取得程式端點擷取程式ID。無法搭配programIds篩選器使用。
programIds
Array[整數]
接受最多10個計畫ID的陣列。 作業會傳回作業開始處理時屬於程式成員的所有可存取記錄。匯出檔案中會新增一個額外欄位「programId」，作為第一個欄位。 此欄位識別從擷取程式成員資格記錄的程式。使用取得程式端點擷取程式ID。無法搭配programId篩選器使用。
isExhausted
布林值
接受用於篩選已用完內容的人之方案成員資格記錄的布林值。
nurtureCadence
字串

接受用來篩選特定Nurture步調之程式成員資格記錄的字串。允許的值有：

  • pause — 節奏已暫停
  • 標準 — 步調正常
statusName
Array[字串]

接受程式成員狀態名稱的陣列。 多個狀態名稱會同時進行OR。具有此篩選型別的工作會傳回其程式成員狀態符合任何指定狀態名稱的所有可存取記錄。 可以使用預設狀態名稱和使用者定義的狀態名稱。如果statusNames篩選器與'programIds'篩選器一起使用，則會檢查每個方案的成員資格記錄，其狀態符合任何狀態名稱。 如果在任何程式中找不到狀態名稱，則會傳回「1003， Invalid Data」錯誤。

table 0-row-3 1-row-3 2-row-3 3-row-3 4-row-3 5-row-3 6-row-3 7-row-3 8-row-3 html-authored no-header
已出席 已出席隨選 已退回
已點按 已聯絡 已轉換
已參與 填寫表單 受影響的
已邀請 成員 無節目
不在計畫中 在清單上 已開啟
已註冊 註冊中 註冊錯誤
已傳送 已訂閱 已取消訂閱
已檢視 已造訪 造訪的攤位
輪候 網頁內容
更新時間*
日期範圍
接受具有成員startAt和endAt的JSON物件。 startAt接受代表低浮水印的日期時間，而endAt接受代表高浮水印的日期時間。 範圍必須為31天或更少。 日期時間應採用ISO-8601格式，不含毫秒。具有此篩選型別的作業會傳回日期範圍內最近更新的所有可存取記錄。

部分訂閱無法使用篩選器型別。 如果您的訂閱無法使用，您在呼叫「建立匯出程式成員工作」端點時會收到錯誤（「1035，目標訂閱不受支援的篩選器型別」）。 客戶可以聯絡Marketo支援，以便在他們的訂閱中啟用此功能。

選項

「建立匯出程式成員作業」端點提供數個格式選項。 這些選項讓使用者能夠：

  • 指定要包含在匯出檔案中的欄位
  • 重新命名這些欄位的欄標題
  • 指定匯出檔案的格式
參數
資料類型
必要
附註
欄位
陣列[字串]
是
欄位引數接受字串的JSON陣列。 列出的欄位會包含在匯出的檔案中。 下列欄位型別可以匯出： LeadCustom LeadProgram MemberCustom ProgramMember。 使用REST API名稱來指定欄位，您可以使用「描述銷售機會2」和/或「描述方案成員」端點來擷取該欄位。
columnHeaderName
物件
無
包含欄位和欄標題名稱之索引鍵/值組的JSON物件。 索引鍵必須是匯出作業中包含的欄位名稱。 值是該欄位匯出的欄標題的名稱。
格式
字串
無
接受以下其中之一：CSV、TSV、SSV。 匯出的檔案會分別呈現為逗號分隔值、定位字元分隔值或空格分隔值檔案（如果設定）。 如果未設定，則預設為CSV。

建立工作

使用建立匯出程式成員工作端點開始匯出之前，會定義工作的引數。 我們必須定義包含方案ID的filter，以及匯出所需的fields。 我們可選擇定義檔案的format，以及columnHeaderNames。

POST /bulk/v1/program/members/export/create.json

{
   "format": "CSV",
   "fields": [
        "firstName",
        "lastName",
        "email",
        "membershipDate",
        "program",
        "statusName",
        "leadId",
        "reachedSuccess",
        "leadCustomField01",
        "leadCustomField02",
        "pMCustomField01",
        "pMCustomField02"
   ],
   "filter": {
      "programId":1044
   }
}

{
    "requestId": "4d44#16f92734f6e",
    "result": [
        {
            "exportId": "b5ca52a9-5ecb-4966-b5a9-11659a8b4c2b",
            "format": "CSV",
            "status": "Created",
            "createdAt": "2020-01-11T02:33:48Z"
        }
    ],
    "success": true
}

這會傳回狀態回應，指出工作已建立。 工作已定義並建立，但尚未開始。 若要這麼做，必須使用建立狀態回應中的呼叫排入佇列匯出程式成員工作exportId端點：

POST /bulk/v1/program/members/export/{exportId}/enqueue.json

{
    "requestId": "d70b#16f9273ae32",
    "result": [
        {
            "exportId": "b5ca52a9-5ecb-4966-b5a9-11659a8b4c2b",
            "format": "CSV",
            "status": "Queued",
            "createdAt": "2020-01-11T02:33:48Z",
            "queuedAt": "2020-01-11T02:34:13Z"
        }
    ],
    "success": true
}

這會以初始status的「已排入佇列」回應，之後當有可用的匯出位置時，會設為「正在處理」。

輪詢工作狀態

注意：只能為相同API使用者建立的作業擷取狀態。

由於這是非同步端點，在建立作業後，我們必須輪詢其狀態以判斷其進度。 使用取得匯出程式成員工作狀態端點進行輪詢。 狀態只會每60秒更新一次，因此不建議使用低於此值的輪詢頻率，並且在幾乎所有情況下仍然會太高。 狀態列位可能會以下列任一專案回應：已建立、已排入佇列、正在處理、已取消、已完成、失敗。

GET /bulk/v1/program/members/export/{exportId}/status.json

{
    "requestId": "9a40#16f9274d250",
    "result": [
        {
            "exportId": "b5ca52a9-5ecb-4966-b5a9-11659a8b4c2b",
            "format": "CSV",
            "status": "Processing",
            "createdAt": "2020-01-11T02:33:48Z",
            "queuedAt": "2020-01-11T02:34:13Z",
            "startedAt": "2020-01-11T02:35:19Z"
        }
    ],
    "success": true
}

狀態端點回應指出工作仍在處理中，因此檔案尚不可擷取。 工作status變更為「已完成」後，便可供下載。

{
    "requestId": "11ad1#16f9ff6da23",
    "result": [
        {
            "exportId": "1118dc83-273b-4d44-becb-4d212fece550",
            "format": "CSV",
            "status": "Completed",
            "createdAt": "2020-01-11T02:33:48Z",
            "queuedAt": "2020-01-11T02:34:13Z",
            "startedAt": "2020-01-11T02:35:19Z"
            "finishedAt": "2020-01-11T02:36:12Z",
            "numberOfRecords": 13,
            "fileSize": 1752,
            "fileChecksum": "sha256:b3c8e70e6e501cf1025e345a66b409d4fd07364c7da773cfa68a2b68ce1a7212"
        }
    ],
    "success": true
}

正在擷取您的資料

若要擷取已完成程式成員匯出的檔案，只要使用您的呼叫取得匯出程式成員檔案exportId端點即可。

回應包含以設定作業方式格式化的檔案。 端點會以檔案內容回應。 如果要求的程式成員欄位是空的（不包含任何資料），則會將null放置在匯出檔案中的對應欄位中。

GET /bulk/v1/program/members/export/{exportId}/file.json

firstName,lastName,email,Member Date,Program,Status,Lead Id,Success,leadCustomField01,leadCustomField02,pMCustomField01,pMCustomField02
Meera,Reed,mree@housestark.com,2020-01-08T18:10:26Z,PMCF Program,On List,1789,false,Lead01_Value,Lead02_Value,PM01_Value,PM02_Value
Jon,Umber,jumb@housestark.com,2020-01-08T18:10:26Z,PMCF Program,On List,1790,false,Lead01_Value,Lead02_Value,PM01_Value,PM02_Value
Lyanna,Mormont,lmor@housestark.com,2020-01-08T18:10:26Z,PMCF Program,On List,1791,false,Lead01_Value,Lead02_Value,PM01_Value,PM02_Value
Rickon,Stark,rsta@housestark.com,2020-01-08T18:10:26Z,PMCF Program,On List,1792,false,Lead01_Value,Lead02_Value,PM01_Value,PM02_Value
Hodor,null,hodor@housestark.com,2020-01-08T18:10:26Z,PMCF Program,On List,1793,false,Lead01_Value,Lead02_Value,PM01_Value,PM02_Value
Osha,null,osha@housestark.com,2020-01-08T18:10:26Z,PMCF Program,On List,1794,false,Lead01_Value,Lead02_Value,PM01_Value,PM02_Value
Jojen,Reed,Jree@housestark.com,2020-01-08T18:10:26Z,PMCF Program,On List,1795,false,Lead01_Value,Lead02_Value,PM01_Value,PM02_Value
Rickard,Karstark,rkar@housestark.com,2020-01-08T18:10:26Z,PMCF Program,On List,1796,false,Lead01_Value,Lead02_Value,PM01_Value,PM02_Value
Maester,Luwin,mluw@housestark.com,2020-01-08T18:10:26Z,PMCF Program,On List,1797,false,Lead01_Value,Lead02_Value,PM01_Value,PM02_Value
Rodrik,Cassel,rcas@housestark.com,2020-01-08T18:10:26Z,PMCF Program,On List,1798,false,Lead01_Value,Lead02_Value,PM01_Value,PM02_Value
Jory,Cassel,jcas@housestark.com,2020-01-08T18:10:26Z,PMCF Program,On List,1799,false,Lead01_Value,Lead02_Value,PM01_Value,PM02_Value
Septa,Mordane,smor@housestark.com,2020-01-08T18:10:26Z,PMCF Program,On List,1800,false,Lead01_Value,Lead02_Value,PM01_Value,PM02_Value

為了支援擷取資料的部份擷取和便於恢復擷取，檔案端點可選擇性地支援型別位元組的HTTP標頭範圍。 如果未設定標頭，將會傳回所有內容。 您可以閱讀更多有關搭配Marketo 大量擷取使用Range標頭的資訊。

取消工作

如果工作設定不正確或變得不必要，可以使用取消匯出程式成員工作端點輕鬆取消工作：

POST /bulk/v1/program/members/export/{exportId}/cancel.json

{
    "requestId": "bb4f#16f86727f89",
    "result": [
        {
            "exportId": "f0d3520c-3a60-4568-9e71-2e619d3805a4",
            "format": "CSV",
            "status": "Cancelled",
            "createdAt": "2020-01-07T21:47:35Z"
        }
    ],
    "success": true
}

此回應中包含status，指出工作已取消。

recommendation-more-help
bb269a6d-047a-4bf7-9acd-23ad9a63dc59