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 响应,将其映射到输出表格,并向下游传递到其他工作流活动。
  • 具有叫客特定过渡的失败管理

向后兼容性声明

在Campaign Standard20.4版本中,已降低http响应数据大小限制和响应超时护栏,以符合最佳实践(请参阅“限制和护栏”部分)。 这些保护性修改不会对现有外部API活动生效;因此,建议在所有活动中将现有的外部API工作流替换为新版本。
如果您是从Campaign Standard20.2(或更早版本)升级,请注意,外部API功能将Campaign Standard20.3版本中的测试版测试版移动到常规可用性。
因此,如果您之前使用的是 Beta 版 External API 活动,则需要在所有工作流中用 GA 版 External API 活动进行替换。  从Campaign Standard20.3版本开始,使用外部API测试版的工作流将无法工作。
替换 External API 活动时,将新的 External API 活动添加到工作流、手动复制配置详细信息,然后删除旧活动。
您将无法复制活动特定的标题值,因为这些标题值在活动中被遮罩。
接下来,重新配置工作流的其他活动,将指向或使用 Beta 版 External API 活动的数据,替换为指向和/或使用新 External API 活动的数据。活动示例:电子邮件投放(个性化字段)、扩充活动等。

限制和防护

以下护栏适用于此活动:
  • 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。
外部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”选项卡中自定义数据映射。在其他情况下,会显示错误消息。

执行

此选项卡允许您定义连接端点。 该 URL 字段允许您定义将 向ACS发送数 据的HTTPS端点。
如果端点需要,可使用两种类型的身份验证方法:
  • 基本身份验证:在字段中输入您的用户名/密码 Request Header(s) 信息。
  • OAuth身份验证:通过单击, Use connection parameters defined in an external account ​您可以选择定义OAuth身份验证的外部帐户。 For more information, refer to the External accounts section.

属性

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

列定义

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

过渡

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

执行选项

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

疑难解答

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

信息

这些日志消息用于在执行工作流活动期间,记录关于有用检查点的信息。
消息格式 示例
正在调用 API URL '%s'。
正在调用 API URL 'https://example.com/api/v1/web-coupon?count=2'。
由于%s(在%d毫秒中),正在重试API URL“%s”,尝试%d。
由于HTTP - 401,在2364毫秒内重试API URL 'https://example.com/api/v1/web-coupon?count=0',尝试2。
正在从 '%s’ 传输内容 (%s / %s)。
正在从 'https://example.com/api/v1/web-coupon?count=2’ 传输内容 (1234 / 1234)。
对提供程序ID“%s”使用缓存访问令牌。
对提供程序ID“EXT25”使用缓存访问令牌。 注意: EXT25是外部帐户的ID(或名称)。
从服务器为提供程序ID“%s”获取访问令牌。
从服务器为提供程序ID“EXT25”获取访问令牌。 注意:EXT25是外部帐户的ID(或名称)。
正在刷新OAuth访问令牌,因为出现错误(HTTP:“%d”)。
正在刷新OAuth访问令牌,因为出现错误(HTTP:“401”)。
刷新OAuth访问令牌时出错(错误:“%d”)。
刷新OAuth访问令牌时出错(错误:“404”)。
在尝试%d时使用指定的访问令牌获取OAuth外部帐户失败,在%d毫秒内重试。
在尝试1时使用指定的访问令牌获取OAuth外部帐户失败,在1387毫秒后重试。

错误

这些日志消息用于记录有关意外错误情况的信息,这些错误情况最终会导致工作流活动失败。
“代码 - 消息”格式 示例
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')。
WKF-560278 - "初始化OAuth帮助程序时出错(错误:“%d”)”。
此错误表示活动无法初始化内部OAuth2.0帮助程序工具,因为使用外部帐户中配置的属性初始化帮助程序时出错。
WKF-560279 - "不允许HTTP头键(头键:“%s”)。”
此警告(非错误)消息表示OAuth 2.0外部帐户已配置为将凭据添加为HTTP头,但不允许使用头密钥,因为它是保留的头密钥。
WKF-560280 —— 找不到“%s”ID的外部帐户。
找不到“EXT25”ID的外部帐户。 注意:此错误表示活动已配置为使用外部帐户,但再也找不到。 当帐户从数据库中删除时,这种情况极有可能发生,而在正常操作环境中,这种情况不可能发生。
WKF-560281 —— 已禁用“%s”ID的外部帐户。
外部帐户为“EXT25”ID。 注意:此错误表示该活动已配置为使用外部帐户,但该帐户已被禁用(或标记为非活动)。
WKF-560282 —— 不支持协议。
此错误表示与外部帐户关联的活动不是OAuth2.0外部帐户。 因此,除非出现某些损坏或手动更改活动配置,否则不太可能发生此错误。
WKF-560283 —— 无法获取OAuth访问令牌。
此错误的最常见原因是外部帐户配置错误(例如, 使用外部帐户,但不测试连接是否成功)。 可能会更改外部帐户上的url/凭据。
CRL-290199 —— 无法访问以下网页:%s。
为OAuth设置外部帐户UI时,该错误消息会显示在该屏幕上。 这意味着外部授权服务器的URL不正确/更改/来自服务器的响应为“找不到页面”。
CRL-290200 —— 凭据不完整/不正确。
为OAuth设置外部帐户UI时,该错误消息会显示在该屏幕上。 这意味着凭据不正确或缺少连接到身份验证服务器所需的其他凭据。