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

响应

所有响应都通过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"
      },
      {
         "email": "johnny.neal@yvu30.com",
         "firstName": "Johnny",
         "lastName": "Neal"
      }
   ]
}

响应

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

限制

以下是使用护栏的列表：

数据摄取API与REST API

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