Show Menu
主题×

External API

说明

利用 External API 活动,可通过 HTTP API 调用,将来自​ 外部系统 ​的数据引入工作流。
举例而言,外部系统端点可以是公共 API 端点、客户管理系统或无服务器应用程序实例(例如 Adobe I/O Runtime )。
出于安全原因,Campaign Standard 中不支持使用 JSSP。如果需要执行代码,可以通过 External API 活动调用 Adobe I/O Runtime 实例。
本活动的主要特点是:
  • 能将 JSON 格式的数据传递到第三方 REST API 端点
  • 能够接收发回的 JSON 响应,将其映射到输出表格,并向下游传递到其他工作流活动。
  • 具有叫客特定过渡的失败管理

从 Beta 版过渡到 GA 版

在Campaign Standard 20.3 版中,External API 功能已将从 Beta 版过渡到正式发布版 (GA)。
因此,如果您之前使用的是 Beta 版 External API 活动,则需要在所有工作流中用 GA 版 External API 活动进行替换。  从 20.3 版开始,使用 Beta 版 External API 的工作流将被废除。
替换 External API 活动时,将新的 External API 活动添加到工作流、手动复制配置详细信息,然后删除旧活动。
您将无法复制标头值,因为活动中的这些值会被掩盖。
接下来,重新配置工作流的其他活动,将指向或使用 Beta 版 External API 活动的数据,替换为指向和/或使用新 External API 活动的数据。活动示例:电子邮件投放(个性化字段)、扩充活动等。

限制和防护

以下护栏适用于此活动:
  • 50MB HTTP响应数据大小限制(建议使用5MB)
  • 10 分钟请求超时
  • 不允许 HTTP 重定向
  • 拒绝非 HTTPS URL
  • 允许使用“Accept: application/json”请求标头和“Content-Type: application/json”响应标头
从活动20.4版本开始,http响应数据大小限制和响应超时护栏将分别降低到5MB和1分钟。 虽然此更改只会影响新的外部API活动,但强烈建议当前的外部API活动实现与这些新的保证保持一致,以遵循最佳实践。
为 JSON 设置了特定的防护:
  • JSON Max Depth :将可处理自定义嵌套 JSON 的最大深度限制为 10 级。
  • JSON Max Key Length :将生成内部键值的最大长度限制为 255。此键值与列 ID 关联。
  • JSON Max Duplicate Keys Allowed :将用作列 ID 的 JSON 属性名称重复项总数上限设置为 150。
该活动不支持以下 JSON 结构:
  • 将数组对象与其他非数组元素组合
  • JSON 数组对象嵌套在一个或多个中间数组对象中。
外部API活动用于获取活动范围的数据(最新优惠集、最新得分等),而不是用于检索每个用户档案的特定信息,因为这会导致传输大量数据。 如果使用案例要求进行检索,建议使用 传输文件 活动。

配置

External API 活动拖放到工作流中,然后打开活动以开始配置。

集客映射

集客映射是由以前的集客活动生成的临时表格,将在 UI 中以 JSON 形式显示和发送。 用户可以根据此临时表格对集客数据进行修改。
利用 Inbound resource 下拉列表,可选择将要创建临时表格的查询活动。
勾选 Add count parameter 复选框,可为来自临时表格的每个行添加一个计数值。请注意,只有集客活动生成临时表格时,此复选框才可用。
利用 Inbound Columns 部分,用户可添加来自集客过渡表格的任何字段。所选列将成为数据对象中的键值。JSON 格式的列表对象将是一个数组列表,其中包含来自集客过渡表格各行的选定列数据。
使用​ 自定义参数 ​文本框,您可以添加 External API 所需的有效 JSON 和附加数据。该附加数据将添加到所生成 JSON 中的参数对象。

叫客映射

利用此选项卡,可定义 API 调用返回的示例 JSON 结构
JSON 解析器设计为适应标准 JSON 结构模式类型,但也存在一些例外。标准模式的示例有: {“data”:[{“key”:“value”}, {“key”:“value”},...]}
示例 JSON 定义必须具有​ 以下特征
  • 数组元素 ​必须包含第一级属性(不支持更深层级别)。 属性名称 ​最终将成为输出临时表之输出架构的列名称。
  • 要捕获的 JSON 元素 在 JSON 响应中的嵌套级别不得大于 10。
  • 列名称 ​定义基于“data”数组的第一个元素。 列定义(添加/删除)和属性的类型值,可以在 Column definition 选项卡中进行编辑。
扁平化复选框 ​行为:
提供了扁平化复选框(默认:未选中)用于指示是否将 JSON 扁平化为键值/值映射。
  • 禁用此复选框 (取消选中)后,将解析示例 JSON 以查找数组对象。用户需要提供 API 响应示例 JSON 格式的精简版本,以便 Adobe Campaign 精确定位用户希望使用的数组。创作工作流时,会确定并记录嵌套数组对象的路径,以便在执行时使用该路径访问接收自 API 调用的 JSON 响应体数组对象。
  • 启用此复选框 (选中)后,会将示例 JSON 扁平化,将所提供示例 JSON 中指定的所有属性用于创建输出临时表格的列,并显示在 Column Definitions 选项卡中。请注意,如果示例 JSON 中存在任何数组对象,则这些数组对象的所有元素也将被扁平化。
如果​ 已验证解析 ,则会显示一条消息,邀请您在“Column definition”选项卡中自定义数据映射。在其他情况下,会显示错误消息。

执行

利用此选项卡,可定义将向 ACS 发送数据的 HTTPS 端点 。如果需要,您可以在以下字段中输入身份验证信息。

属性

利用此选项卡,您可以控制 External API 活动上的​ 常规属性 ,如 UI 中显示的标签。不可自定义内部 ID。

列定义

填写并验证 Outbound Mapping 选项卡中的​ 响应数据格式 后,将显示此选项卡。
利用 Column definition 选项卡,可精确指定每列的数据结构,以便导入不包含任何错误的数据,并使其与 Adobe Campaign 数据库中已存在的类型匹配,以便将来进行操作。
例如,您可以更改列的标签,选择其类型(字符串、整数、日期等)甚至指定错误处理。
有关更多信息,请参阅 加载文件

过渡

利用此选项卡可激活​ 叫客过渡 ​及其标签。此特定过渡适合用于​ 超时 ​或有效载荷超过​ 数据大小限制 ​时。

执行选项

大多数工作流活动中都提供了此选项卡。有关更多信息,请参阅 活动属性 一节。

疑难解答

此新工作流活动已添加了两种类型的日志消息:信息和错误。它们可以帮助您排除潜在的问题。

信息

这些日志消息用于在执行工作流活动期间,记录关于有用检查点的信息。具体而言,以下日志消息用于记录访问 API 的首次尝试以及重试尝试(以及首次尝试失败的原因)。
消息格式 示例
正在调用 API URL '%s'。
正在调用 API URL 'https://example.com/api/v1/web-coupon?count=2'。
正在重试 API URL '%s',上次尝试失败 ('%s')。
正在重试 API URL 'https://example.com/api/v1/web-coupon?count=2',上次尝试失败 ('HTTP - 401')。
正在从 '%s’ 传输内容 (%s / %s)。
正在从 'https://example.com/api/v1/web-coupon?count=2’ 传输内容 (1234 / 1234)。

错误

这些日志消息用于记录有关意外错误情况的信息,这些错误情况最终会导致工作流活动失败。
“代码 - 消息”格式 示例
WKF-560250 - API 请求正文超出限制(限制:'%d')。
API 请求正文超出限制(限制:'5242880')。
WKF-560239 - API 响应超出限制(限制:'%d')。
API 响应超出限制(限制:'5242880')。
WKF-560245 - 无法解析 API URL(错误:'%d')。
无法解析 API URL(错误:'-2010')。
注意:当 API URL 验证规则失败时,将记录此错误。
WKF-560244 - API URL 主机不能为“localhost”或 IP 地址文字(URL 主机:'%s')。
API URL 主机不能为“localhost”或 IP 地址文字(URL 主机:'localhost')。
API URL 主机不能为“localhost”或 IP 地址文字(URL 主机:'192.168.0.5')。
API URL 主机不能为“localhost”或 IP 地址文字(URL 主机:'[2001]')。
WKF-560238 - API URL 必须是安全 URL (https)(请求的 URL:'%s')。
API URL 必须是安全 URL (https)(请求的 URL:'https://example.com/api/v1/web-coupon?count=2')。
WKF-560249 - 无法创建请求主体 JSON。添加“%s”时出错。
无法创建请求主体 JSON。添加“params”时出错。
无法创建请求主体 JSON。添加“data”时出错。
WKF-560246 - HTTP 标头键值错误(标头键值:'%s')。
HTTP 标头键值错误(标头键值:'%s')。
注意:根据 RFC 验证自定义标头键值失败时,将记录此错误。
WKF-560248 - 不允许的 HTTP 标头键值(标头键值:'%s')。
不允许的 HTTP 标头键值(标头键值:'%s')。
WKF-560247 - HTTP 标头值错误(标头值:'%s')。
HTTP 标头值损坏(标头值:'%s')。
注意:根据 RFC 验证自定义标头值失败时,将记录此错误。
WKF-560240 - JSON 有效载荷的属性“%s”不正确。
JSON 有效载荷的属性“blah”不正确。
WKF-560241 - JSON 格式不正确或不可接受。
JSON 格式不正确或不可接受。
注意:此消息仅适用于从外部 API 解析响应主体,并在尝试验证响应主体是否符合本活动强制规定的 JSON 格式时记录。
WKF-560246 - 活动失败(原因:'%s')。
因 HTTP 401 错误响应导致活动失败时 - 活动失败(原因:'HTTP - 401')。
因内部调用失败导致活动失败时 - 活动失败(原因:'iRc - -Nn')。
因 Content-Type 标头无效导致活动失败时 - 活动失败(原因:'Content-Type - application/html')。