데이터 수집 API

데이터 수집 API는 대량의 개인 및 개인 관련 데이터 수집을 효율적이고 최소한의 지연으로 처리하도록 설계된 대량의 짧은 지연 시간 고가용성 서비스입니다.

비동기적으로 실행되는 요청을 제출하면 데이터가 수집됩니다. Marketo Observability 데이터 스트림에서 이벤트를 구독하여 요청 상태를 검색할 수 있습니다.

인터페이스는 개인, 사용자 정의 객체, 회사 및 프로그램 멤버의 네 가지 객체 유형에 대해 제공됩니다. 레코드 작업은 삭제를 지원하는 프로그램 멤버를 제외하고 "삽입 또는 업데이트"만 가능합니다.

인증

데이터 수집 API는 Marketo REST API와 동일한 OAuth 2.0 인증 방법을 사용하여 액세스 토큰을 생성하지만, HTTP 헤더 X-Mkto-User-Token을(를) 통해 액세스 토큰을 전달해야 합니다. 쿼리 매개 변수를 통해 액세스 토큰을 전달할 수 없습니다.

헤더를 통한 액세스 토큰 예:

X-Mkto-User-Token: 11606815-aa7a-405a-80a1-f9683efa528b:ab

권한

데이터 수집은 Marketo REST API와 동일한 권한 모델을 사용하며, 각 끝점에 특정 권한이 필요하지만 사용할 추가적인 특수 권한이 필요하지 않습니다.

지원되는 오브젝트 유형

헤더

데이터 수집은 다음 사용자 지정 HTTP 헤더를 사용합니다.

요청

응답

요청

HTTP POST 메서드를 사용하여 데이터를 서버로 전송합니다.

데이터 표현은 요청 본문에 application/json으로 포함됩니다.

도메인 이름: mkto-ingestion-api.adobe.io

경로는 MunchkinId가 Marketo 인스턴스에만 해당되는 /subscriptions/MunchkinId(으)로 시작됩니다. Munchkin ID는 Marketo Engage UI의 관리자 > 내 계정 > 지원 정보​에서 찾을 수 있습니다. 경로의 나머지 부분은 관심 리소스를 지정하는 데 사용됩니다.

개인용 예제 URL:

https://mkto-ingestion-api.adobe.io/subscriptions/556-RJS-213/persons

사용자 지정 개체의 URL 예:

https://mkto-ingestion-api.adobe.io/subscriptions/556-RJS-213/customobjects/purchases

회사의 예제 URL:

https://mkto-ingestion-api.adobe.io/subscriptions/556-RJS-213/companies

프로그램 멤버의 URL 예:

https://mkto-ingestion-api.adobe.io/subscriptions/556-RJS-213/programmembers

응답

모든 응답은 X-Request-Id 헤더를 통해 고유한 요청 ID를 반환합니다.

헤더를 통한 요청 ID 예:

X-Request-Id: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

성공

호출이 성공하면 202 상태가 반환됩니다. 응답 본문이 반환되지 않습니다.

성공 응답의 예:

HTTP/1.1 202 Accepted
X-Request-Id: e3d92152-0fb1-444a-8f8f-29d5a2338598
Content-Length: 0
Date: Wed, 18 Oct 2023 18:56:49 GMT

오류

호출에서 오류가 발생하면 추가 오류 세부 정보가 있는 응답 본문과 함께 비202 상태가 반환됩니다. 응답 본문은 application/json이며 member error_code 및 message가 있는 단일 개체를 포함합니다.

다음은 Adobe Developer Gateway에서 재사용되는 오류 코드입니다.

다음은 데이터 수집 API에 고유하며 3개의 세그먼트로 구성된 오류 코드입니다. 처음 세 자리 수는 상태(Adobe Developer Gateway에서 반환됨), 그 뒤에는 0 "0"이 오고 세 자리 수가 옵니다.

재시도

일시적인 오류가 감지되면 서비스는 작업을 세 번 다시 시도합니다. 첫 번째 재시도는 5분의 대기 시간 후 발생하며, 두 번째는 30분 후 발생하며, 마지막으로 세 번째는 30분 후 발생합니다. 재시도는 주로 종속 서비스가 시간 초과되거나 일시적으로 사용할 수 없을 때 다양한 이유로 발생합니다.

엔드포인트

수집 엔드포인트는 사용자, 사용자 지정 개체, 회사 및 프로그램 멤버에 대해 사용할 수 있습니다.

개인

개인 레코드를 업데이트하는 데 사용되는 종단점입니다.

헤더

요청 본문

필요한 권한은 Read-Write Lead입니다.

개인 예

요청

POST /subscriptions/{munchkinId}/persons

헤더

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

본문

{
   "priority": "high",
   "partitionName": "EMEA",
   "dedupeFields": {
      "field1": "email",
      "field2": "firstName"
   },
   "persons":[
      {
         "email": "brooklyn.parker@karnv.com",
         "firstName": "Brooklyn",
         "lastName": "Parker",
         "company": "Karnv"
      },
      {
         "email": "johnny.neal@yvu30.com",
         "firstName": "Johnny",
         "lastName": "Neal",
         "company": "Acme Inc"
      }
   ]
}

응답

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

사용자 지정 개체

사용자 지정 개체 레코드를 업데이트하는 데 사용되는 끝점입니다.

헤더

요청 본문

필요한 권한은 Read-Write Custom Object입니다.

개인에 대한 링크 필드가 요청에 지정되어 있고 해당 개인이 존재하지 않는 경우 몇 번의 재시도가 발생합니다. 재시도 기간(65분) 동안 해당 개인이 추가되면 성공적으로 갱신됩니다. 예를 들어 링크 필드가 사용자에 대한 이메일이고 개인이 존재하지 않는 경우 재시도가 발생합니다.

사용자 지정 개체 예

요청

POST /subscriptions/{munchkinId}/customobjects/{customObjectAPIName}

헤더

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

본문

{
   "dedupeBy": "dedupeFields",
   "priority": "high",
   "customObjects": [
      {
         "email": "brooklyn.parker@karnv.com",
         "vin": "20UYA31581L000000",
         "make": "BMW",
         "model": "3-Series 330i",
         "year": 2003
      },
      {
         "email": "johnny.neal@yvu30.com",
         "vin": "19UYA31581L000000",
         "make": "BMW",
         "model": "3-Series 325i",
         "year": 1989
      }
   ]
}

응답

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

회사

회사 레코드를 동기화하는 데 사용되는 끝점입니다. 외부 회사 ID 또는 Marketo 내부 ID별 중복 제거를 사용하여 만들기, 업데이트 및 업데이트 작업을 지원합니다.

헤더

요청 본문

input 배열의 각 회사 개체는 다음 필드를 지원합니다.

필요한 권한은 Read-Write Company입니다.

회사 예

요청

POST /subscriptions/{munchkinId}/companies

헤더

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

본문

{
   "action": "createOrUpdate",
   "dedupeBy": "dedupeFields",
   "input": [
      {
         "externalCompanyId": "ext-company-001",
         "company": "Acme Corporation",
         "industry": "Technology",
         "numberOfEmployees": 5000,
         "annualRevenue": 100000000
      },
      {
         "externalCompanyId": "ext-company-002",
         "company": "Globex Industries",
         "industry": "Manufacturing",
         "numberOfEmployees": 1200
      }
   ]
}

응답

HTTP/1.1 202
X-Request-ID: WOUBf3fHJNU6sTmJqLL281lOmAEpMZFw

회사 업데이트-ID 예

{
   "action": "updateOnly",
   "dedupeBy": "idField",
   "input": [
      {
         "id": 12345,
         "company": "Acme Corporation (Renamed)",
         "numberOfEmployees": 5500
      }
   ]
}

회사 유효성 검사 규칙

프로그램 구성원(동기화)

프로그램 구성원 상태를 동기화하는 데 사용되는 끝점으로, 프로그램에 잠재 고객을 추가하거나 프로그램 상태를 업데이트합니다.

헤더

요청 본문

programs 배열의 각 개체는 다음을 포함합니다.

members 배열의 각 개체는 다음을 포함합니다.

필요한 권한은 Read-Write Lead입니다.

프로그램 구성원 동기화 예

요청

POST /subscriptions/{munchkinId}/programmembers

헤더

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

본문

{
   "programs": [
      {
         "programId": 1001,
         "status": "Member",
         "members": [
            {
               "leadId": 10001
            },
            {
               "leadId": 10002
            }
         ]
      },
      {
         "programId": 1002,
         "status": "Influenced",
         "members": [
            {
               "leadId": 10003
            }
         ]
      }
   ]
}

응답

HTTP/1.1 202
X-Request-ID: e3d92152-0fb1-444a-8f8f-29d5a2338598

프로그램 구성원 동기화 유효성 검사 규칙

프로그램 구성원(삭제)

프로그램에서 리드를 제거하는 데 사용되는 끝점입니다. 잠재 고객의 멤버십 상태를 "Not in Program"(으)로 설정하고 해당 프로그램에서 구성원을 제거합니다.

헤더

요청 본문

programs 배열의 각 개체는 다음을 포함합니다.

members 배열의 각 개체는 다음을 포함합니다.

필요한 권한은 Read-Write Lead입니다.

프로그램 멤버 삭제 예

요청

POST /subscriptions/{munchkinId}/programmembers/delete

헤더

Content-Type: application/json
X-Mkto-User-Token: {accessToken}

본문

{
   "programs": [
      {
         "programId": 1001,
         "members": [
            {
               "leadId": 10001
            },
            {
               "leadId": 10002
            }
         ]
      },
      {
         "programId": 1002,
         "members": [
            {
               "leadId": 10003
            }
         ]
      }
   ]
}

응답

HTTP/1.1 202
X-Request-ID: a1b2c3d4-e5f6-7890-abcd-ef1234567890

프로그램 구성원이 유효성 검사 규칙을 삭제합니다.

제한

다음은 보호 기능의 업데이트된 목록입니다.

이러한 제한은 개인, 사용자 정의 객체, 회사 및 프로그램 멤버에 걸쳐 균일하게 적용됩니다. Program Members의 경우 "요청 당 개체"는 단일 요청의 모든 프로그램에 대한 총 잠재 고객 참조 수입니다.

데이터 수집 API와 REST API

다음은 데이터 수집 API와 기타 Marketo REST API의 차이점 목록입니다.