数据摄取API

数据摄取API是一种高容量、低延迟、高度可用的服务，旨在以最小的延迟有效处理大量与人员和人员相关的数据摄取。

通过提交异步执行的请求来摄取数据。 通过订阅Marketo可观察性数据流中的事件，可以检索请求状态。

界面提供四种对象类型：人员、自定义对象、公司和程序成员。 该记录操作仅限“插入或更新”，但同时支持删除的程序成员除外。

身份验证

数据摄取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

路径以/subscriptions/MunchkinId开头，其中MunchkinId特定于您的Marketo实例。 您可以在Marketo Engage UI中的​管理员 > 我的帐户 > 支持信息​下找到您的Munchkin ID。 路径的其余部分用于指定感兴趣的资源。

人员示例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，并包含一个包含成员error_code和message的对象。

以下是Adobe Developer Gateway中可重复使用的错误代码。

以下是数据摄取API特有的错误代码，由3个区段组成。 前三位是状态（由Adobe Developer Gateway返回），后跟零“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分钟）期间添加该人员，则更新成功。 例如，如果链接字段为Email on Person，而Person不存在，则会发生重试。

自定义对象示例

请求

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

项目群成员删除验证规则

限制

以下是护栏的更新列表：

这些限制统一适用于人员、自定义对象、公司和程序成员。 对于项目群成员，“每个请求的对象”是单个请求中所有项目的潜在客户引用总数。

数据摄取API与REST API

以下是数据摄取API与其他Marketo REST API之间的差异列表：