벌크 납 추출

잠재 고객 추출 끝점 참조

REST API의 벌크 리드 추출 세트는 Marketo에서 대규모 리드/개인 레코드 세트를 검색하는 프로그래밍 방식 인터페이스를 제공합니다. 또한 레코드의 생성 날짜, 가장 최근 업데이트, 정적 목록 멤버십 또는 스마트 목록 멤버십에 따라 점진적으로 리드를 검색하는 데 사용할 수 있습니다. ETL, 데이터 웨어하우징 및 보관 목적으로 Marketo과 하나 이상의 외부 시스템 간에 데이터를 지속적으로 교환해야 하는 사용 사례에 권장되는 인터페이스입니다.

권한

벌크 리드 추출 API를 사용하려면 소유 API 사용자에게 읽기 전용 리드 또는 읽기-쓰기 리드 권한 중 하나 또는 둘 다를 가진 역할이 있어야 합니다.

필터

리드는 다양한 필터 옵션을 지원합니다. updatedAt, smartListName 및 smartListId을(를) 포함한 특정 필터에는 모든 구독으로 아직 롤아웃되지 않은 추가 인프라 구성 요소가 필요합니다. 내보내기 작업당 하나의 필터 유형만 지정할 수 있습니다.

일부 구독에서는 필터 유형을 사용할 수 없습니다. 구독에 사용할 수 없는 경우 리드 작업 내보내기 만들기 엔드포인트를 호출할 때 오류가 발생합니다("1035, 대상 구독에 대해 지원되지 않는 필터 유형"). 고객은 Marketo 지원 센터에 문의하여 구독에서 이 기능을 활성화할 수 있습니다.

옵션

리드 작업 내보내기 만들기 엔드포인트는 사용자에게 내보낸 파일 내에 특정 필드를 포함할 수 있는 기능, 이러한 필드의 열 헤더 이름을 바꿀 수 있는 기능 및 내보낸 파일의 형식을 제공하는 몇 가지 서식 옵션을 제공합니다.

작업 생성

내보내기 리드 작업 만들기 끝점을 사용하여 내보내기를 시작하기 전에 작업에 대한 매개 변수를 정의합니다. 내보내기에 필요한 fields, 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"
      }
   }
}

이 요청은 해당 firstName, lastName, id 및 email 필드의 값을 포함하여 2017년 1월 1일부터 2017년 1월 31일 사이에 생성된 리드 집합 내보내기를 시작합니다.

{
   "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를 사용하여 큐 내보내기 리드 작업 끝점을 호출해야 합니다.

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 사용자가 만든 작업에 대해서만 Note: 상태를 검색할 수 있습니다.

비동기 끝점이므로 작업을 만든 후 상태를 폴링하여 진행률을 확인해야 합니다. 리드 내보내기 작업 상태 가져오기 끝점을 사용하여 폴링합니다. 상태는 60초마다 한 번만 업데이트되므로 이보다 낮은 폴링 빈도는 권장되지 않으며 거의 모든 경우에 여전히 과도합니다. 투표를 간단히 살펴봅시다.

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

상태 끝점은 작업이 아직 처리 중이므로 파일을 검색할 수 없다는 것을 나타냅니다. 작업 상태가 "완료됨"으로 변경되면 다운로드를 준비했습니다.

상태 필드는 다음 중 하나로 응답할 수 있습니다.

데이터 검색 중

완료된 잠재 고객 내보내기의 파일을 검색하려면 을(를) 사용하여잠재 고객 파일 가져오기exportId 끝점을 호출하면 됩니다.

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

응답에는 작업이 구성된 방식으로 포맷된 파일이 포함됩니다. 끝점이 파일의 내용에 응답합니다.

요청한 리드 필드가 비어 있으면(데이터 없음) null이(가) 내보내기 파일의 해당 필드에 배치됩니다. 아래 예에서는 반환된 리드에 대한 이메일 필드가 비어 있습니다.

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

추출된 데이터의 부분 검색 및 재시작 친화성을 지원하기 위해 파일 엔드포인트는 선택적으로 바이트 유형의 HTTP 헤더 범위를 지원합니다. 헤더가 설정되지 않은 경우 전체 콘텐츠가 반환됩니다. Marketo 일괄 추출에서 범위 헤더를 사용하는 방법에 대해 자세히 알아보십시오.

작업 취소

작업이 잘못 구성되었거나 불필요하게 된 경우 리드 작업 내보내기 취소 끝점을 사용하여 작업을 쉽게 취소할 수 있습니다.

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

작업이 취소되었음을 나타내는 상태로 응답합니다.