External API external-api
说明 description
利用 External API 活动，可通过 HTTP API 调用，将来自 外部系统 的数据引入工作流。
举例而言，外部系统端点可以是公共 API 端点、客户管理系统或无服务器应用程序实例（例如 Adobe I/O Runtime）。
本活动的主要特点是：
- 能将 JSON 格式的数据传递到第三方 REST API 端点
- 能够接收发回的 JSON 响应，将其映射到输出表格，并向下游传递到其他工作流活动。
- 具有叫客特定过渡的失败管理
向后兼容性声明 from-beta-to-ga
在Campaign Standard20.4版本中，http响应数据大小限制和响应超时护栏已降低，以符合最佳实践 — 请参阅限制和护栏。 这些护栏修改将不会对现有外部 API 活动生效；因此，建议在所有工作流中将现有外部 API 活动替换为新版本。
替换 External API 活动时，将新的 External API 活动添加到工作流、手动复制配置详细信息，然后删除旧活动。
限制和防护 guardrails
以下护栏适用于此活动：
- 5MB HTTP 响应数据大小限制（注意：这与先前版本中的 50MB 限制相比有所变化）
- 请求超时为 1 分钟（注意：这与先前版本中的 10 分钟超时相比有所变化）
- 不允许 HTTP 重定向
- 拒绝非 HTTPS URL
- 允许使用“Accept: application/json”请求标头和“Content-Type: application/json”响应标头
已设定特定护栏：
- JSON Max Depth：将可处理自定义嵌套 JSON 的最大深度限制为 10 级。
- JSON Max Key Length：将生成内部键值的最大长度限制为 255。此键值与列 ID 关联。
- JSON Max Duplicate Keys Allowed：将用作列 ID 的 JSON 属性名称重复项总数上限设置为 150。
配置 configuration
将 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”选项卡中自定义数据映射。在其他情况下，会显示错误消息。
执行
通过此选项卡，可以定义连接端点。URL 字段允许您定义Campaign Standard将与之通信的 HTTPS终结点。
如果端点需要，则可以使用两种类型的身份验证方法：
-
基本身份验证：在 Request Header(s) 部分输入用户名/密码信息。
-
OAuth身份验证：通过单击外部帐户中的 Use connection parameters defined in an external account，可以选择定义了OAuth身份验证的外部帐户。 有关更多信息，请参阅外部帐户部分。
属性
利用此选项卡，您可以控制 External API 活动上的 常规属性，如 UI 中显示的标签。不可自定义内部 ID。
列定义
利用 Column definition 选项卡，可精确指定每列的数据结构，以便导入不包含任何错误的数据，并使其与 Adobe Campaign 数据库中已存在的类型匹配，以便将来进行操作。
例如，您可以更改列的标签，选择其类型（字符串、整数、日期等）甚至指定错误处理。
有关更多信息，请参阅加载文件。
过渡
利用此选项卡可激活 叫客过渡 及其标签。此特定过渡适合用于 超时 或有效载荷超过 数据大小限制 时。
执行选项
大多数工作流活动中都提供了此选项卡。有关更多信息，请参阅活动属性一节。
测试
要使用简单的测试端点测试外部API功能，您可以使用Postman Echo： https://docs.postman-echo.com.
疑难解答
此新工作流活动已添加了两种类型的日志消息：信息和错误。它们可以帮助您排除潜在的问题。
信息
这些日志消息用于在执行工作流活动期间，记录关于有用检查点的信息。
错误
这些日志消息用于记录有关意外错误情况的信息，这些错误情况最终会导致工作流活动失败。
无法解析 API URL（错误：'-2010'）。
注意：当 API URL 验证规则失败时，将记录此错误。
API URL 主机不能为“localhost”或 IP 地址文字（URL 主机：'localhost'）。
API URL 主机不能为“localhost”或 IP 地址文字（URL 主机：'192.168.0.5'）。
API URL 主机不能为“localhost”或 IP 地址文字（URL 主机：'[2001]'）。
无法创建请求主体 JSON。添加“params”时出错。
无法创建请求主体 JSON。添加“data”时出错。
HTTP header key is bad (header key: '%s').
注意：根据 RFC 验证自定义标头键值失败时，将记录此错误。
HTTP header value is bad (header value: '%s').
注意：根据 RFC 验证自定义标头值失败时，将记录此错误。
JSON 格式不正确或不可接受。
注意：此消息仅适用于从外部 API 解析响应主体，并在尝试验证响应主体是否符合本活动强制规定的 JSON 格式时记录。
因 HTTP 401 错误响应导致活动失败时 - 活动失败（原因：'HTTP - 401'）。
因内部调用失败导致活动失败时 - 活动失败（原因：'iRc - -Nn'）。
因 Content-Type 标头无效导致活动失败时- 活动失败（原因：'Content-Type - application/html'）。