벌크 납 추출

벌크 리드 추출 끝점 참조

벌크 리드 추출 REST API는 Marketo에서 큰 리드/개인 레코드 세트를 검색합니다. 레코드 생성 날짜, 가장 최근 업데이트, 정적 목록 멤버십 또는 스마트 목록 멤버십에 따라 가망 고객을 점진적으로 검색할 수도 있습니다.

ETL, 데이터 웨어하우징 및 아카이빙 워크플로우를 포함한 외부 시스템과 Marketo 간에 데이터를 지속적으로 교환하려면 Bulk Lead Extract 를 사용합니다.

권한

작업을 소유하는 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"
      }
   }
}

이 요청은 2017년 1월 1일부터 2017년 1월 31일 사이에 생성된 리드에 대한 내보내기 작업을 생성합니다. 내보내기에 firstName, lastName, id 및 email 필드의 값이 포함됩니다.

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

리드 내보내기 작업은 비동기적으로 실행됩니다. 리드 내보내기 작업 상태 가져오기 끝점을 폴링하여 작업 진행 상황을 추적합니다.

상태는 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"
      }
   ]
}

이 응답은 작업이 아직 처리 중이므로 파일을 사용할 수 없음을 보여줍니다. 작업 상태가 "완료됨"으로 변경되면 파일을 다운로드할 수 있습니다.

status 필드는 다음 값 중 하나를 반환할 수 있습니다.

데이터 검색 중

완료된 리드 내보내기를 검색하려면 exportId을(를) 사용하여 리드 내보내기 파일 가져오기 끝점을 호출하십시오.

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

응답 본문에는 작업에 대해 구성된 형식의 파일이 포함됩니다.

요청한 리드 필드에 데이터가 없으면 내보내기 파일의 해당 필드에 null이(가) 포함됩니다. 다음 예에서는 반환된 리드에 빈 이메일 필드가 있습니다.

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

부분 검색 또는 다시 시작 가능한 검색의 경우 파일 끝점은 bytes 형식의 선택적 HTTP Range 헤더를 지원합니다. 헤더를 설정하지 않으면 끝점이 모든 콘텐츠를 반환합니다. Marketo 일괄 추출에서 Range 헤더를 사용하는 방법에 대해 자세히 알아보세요.

작업 취소

잘못 구성되었거나 불필요한 작업을 취소하려면 리드 내보내기 작업 취소 끝점을 호출하십시오.

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

응답에서 작업이 취소되었음을 확인합니다.