일괄 프로그램 멤버 추출
REST API의 벌크 프로그램 멤버 추출 세트는 Marketo에서 큰 프로그램 멤버 레코드 세트를 검색할 수 있는 프로그래밍 인터페이스를 제공합니다. ETL, 데이터 웨어하우징 및 보관 목적으로 Marketo과 하나 이상의 외부 시스템 간에 데이터를 지속적으로 교환해야 하는 사용 사례에 권장되는 인터페이스입니다.
권한
벌크 프로그램 멤버 추출 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 필터에는 아직 모든 구독으로 롤아웃되지 않은 추가 인프라 구성 요소가 필요합니다.
일부 구독에서는 필터 유형을 사용할 수 없습니다. 구독에 사용할 수 없는 경우 내보내기 프로그램 구성원 작업 만들기 끝점을 호출할 때 오류가 발생합니다("1035, 대상 구독에 대해 지원되지 않는 필터 유형"). 고객은 Marketo 지원 센터에 문의하여 구독에서 이 기능을 활성화할 수 있습니다.
옵션
내보내기 프로그램 구성원 작업 만들기 끝점은 몇 가지 서식 옵션을 제공합니다. 이러한 옵션을 통해 사용자는 다음과 같은 작업을 수행할 수 있습니다.
- 내보낸 파일에 포함할 필드 지정
- 이 필드의 열 헤더 이름 바꾸기
- 내보낸 파일의 형식 지정
LeadCustom LeadProgram MemberCustom ProgramMember 필드 형식을 내보낼 수 있습니다. 리드2 설명 및/또는 프로그램 멤버 엔드포인트 설명을 사용하여 검색할 수 있는 REST API 이름을 사용하여 필드를 지정합니다.작업 생성
내보내기 프로그램 구성원 작업 만들기 끝점을 사용하여 내보내기를 시작하기 전에 작업에 대한 매개 변수를 정의합니다. 프로그램 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
}
작업이 생성되었음을 나타내는 상태 응답이 반환됩니다. 작업이 정의되고 생성되었지만 아직 시작되지 않았습니다. 이렇게 하려면 만들기 상태 응답의 을(를) 사용하여Enqueue 내보내기 프로그램 구성원 작업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 일괄 추출에서 범위 헤더 사용에 대한 자세한 내용을 읽을 수 있습니다.
작업 취소
작업이 잘못 구성되었거나 불필요하게 된 경우 프로그램 구성원 작업 내보내기 취소 끝점을 사용하여 작업을 쉽게 취소할 수 있습니다.
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에 응답합니다.