通过临时激活API将受众按需激活到批量目标

重要

在完成Beta阶段后, ad-hoc activation API 现已正式向所有Experience Platform客户提供(GA)。 在GA版本中,API已升级到版本2。 步骤4 (获取最新的受众导出作业ID)不再需要,因为API不再需要导出ID。

参见 运行临时激活作业 有关更多信息,请参阅本教程中的下文。

概述

临时激活API允许营销人员以编程方式快速高效地将受众受众激活到目标,以满足需要立即激活的需求。

使用临时激活API将完整文件导出到所需的文件接收系统。 仅支持临时受众激活 基于文件的批处理目标.

下图说明了通过临时激活API激活受众的端到端工作流,包括每24小时在Platform中执行一次的分段作业。

Ad Hoc-activation

用例

Flash销售或促销

一家在线零售商正准备进行限量闪购,希望在短时间内通知客户。 通过Experience Platform临时激活API,营销团队可根据需要导出受众,并快速向客户群发送促销电子邮件。

当前事件或突发新闻

一家酒店预计未来几天天气会很恶劣,团队希望尽快通知到来的客人,以便他们做出相应的计划。 营销团队可以使用Experience Platform临时激活API根据需要导出受众并通知来宾。

集成测试

IT经理可以使用Experience Platform临时激活API按需导出受众,以便测试他们与Adobe Experience Platform的自定义集成,并确保一切正常运行。

护栏

在使用临时激活API时,请牢记以下护栏。

  • 目前,每个临时激活作业最多可以激活80个受众。 尝试激活每个作业超过80个受众将导致作业失败。 此行为可能会在未来版本中发生更改。
  • 临时激活作业不能与计划的同时运行 受众导出作业. 在运行临时激活作业之前,请确保已完成计划的受众导出作业。 参见 目标数据流监测 有关如何监控激活流状态的信息。 例如,如果激活数据流显示 正在处理 状态,请等待它完成后再运行临时激活作业。
  • 不要为每个受众运行多个并发临时激活作业。

分段注意事项

Adobe Experience Platform每24小时运行一次计划的分段作业。 临时激活API基于最新的分段结果运行。

步骤1:先决条件

在调用Adobe Experience Platform API之前,请确保满足以下先决条件:

  • 您拥有有权访问Adobe Experience Platform的组织帐户。
  • 您的Experience Platform帐户具有 developeruser 为Adobe Experience Platform API产品配置文件启用的角色。 联系 Admin Console 管理员为您的帐户启用这些角色。
  • 你有Adobe ID。 如果您没有Adobe ID,请转到 Adobe Developer控制台 并创建一个新帐户。

步骤2:收集凭据

要调用Platform API,您必须先完成 身份验证教程. 完成身份验证教程将为所有Experience PlatformAPI调用中的每个所需标头提供值,如下所示:

  • 授权:持有者 {ACCESS_TOKEN}
  • x-api-key: {API_KEY}
  • x-gw-ims-org-id: {ORG_ID}

Experience Platform中的资源可以隔离到特定的虚拟沙箱。 在对Platform API的请求中,您可以指定将在其中执行操作的沙盒的名称和ID。 这些是可选参数。

  • x-sandbox-name: {SANDBOX_NAME}
注意

有关Experience Platform中沙箱的详细信息,请参阅 沙盒概述文档.

包含有效负载(POST、PUT、PATCH)的所有请求都需要额外的媒体类型标头:

  • Content-Type: application/json

步骤3:在Platform UI中创建激活流程

在通过临时激活API激活受众之前,您必须首先在平台UI中为所选目标配置激活流程。

这包括进入激活工作流,选择受众,配置计划并激活它们。 您可以使用UI或API创建激活流:

步骤4:获取最新的受众导出作业ID(在v2中不是必需的)

重要

在临时激活API v2中,您无需获取最新的受众导出作业ID。 您可以跳过此步骤并继续执行下一个步骤。

为批处理目标配置激活流后,计划的分段作业每24小时自动运行一次。

在运行临时激活作业之前,您必须获取最新受众导出作业的ID。 您必须在临时激活作业请求中传递此ID。

按照描述的说明操作 此处 以检索所有受众导出作业的列表。

在响应中,查找包含下面架构属性的第一个记录。

"schema":{
   "name":"_xdm.context.profile"
}

受众导出作业标识位于 id 属性,如下所示。

受众导出作业ID

步骤5:运行临时激活作业

Adobe Experience Platform每24小时运行一次计划的分段作业。 临时激活API基于最新的分段结果运行。

重要

请注意以下一次性限制:在运行临时激活作业之前,请确保从根据您在中设置的计划首次激活受众之时起已过去至少20分钟 步骤3 — 在Platform UI中创建激活流程.

在运行临时激活作业之前,请确保已完成受众的计划受众导出作业。 参见 目标数据流监测 有关如何监控激活流状态的信息。 例如,如果激活数据流显示 正在处理 状态,请等待它完成后再运行临时激活作业以导出完整文件。

受众导出作业完成后,您可以触发激活。

注意

目前,每个临时激活作业最多可以激活80个受众。 尝试激活每个作业超过80个受众将导致作业失败。 此行为可能会在未来版本中发生更改。

请求

重要

必须包含 Accept: application/vnd.adobe.adhoc.activation+json; version=2 标头,以便使用Ad Hoc Activation API v2。

curl --location --request POST 'https://platform.adobe.io/data/core/activation/disflowprovider/adhocrun' \
--header 'x-gw-ims-org-id: 5555467B5D8013E50A494220@AdobeOrg' \
--header 'Authorization: Bearer {{token}}' \
--header 'x-sandbox-id: 6ef74723-3ee7-46a4-b747-233ee7a6a41a' \
--header 'x-sandbox-name: {sandbox-id}' \
--header 'Accept: application/vnd.adobe.adhoc.activation+json; version=2' \
--header 'Content-Type: application/json' \
--data-raw '{
   "activationInfo":{
      "destinationId1":[
         "segmentId1",
         "segmentId2"
      ],
      "destinationId2":[
         "segmentId2",
         "segmentId3"
      ]
   }
}'
属性 描述
  • destinationId1
  • destinationId2
要将受众激活到的目标实例的ID。 您可以通过导航到,从Platform UI获取这些ID 目标 > 浏览 选项卡,然后单击所需的目标行以在右边栏中显示目标ID。 有关详细信息,请阅读 目标工作区文档.
  • segmentId1
  • segmentId2
  • segmentId3
要激活到选定目标的受众的ID。

具有导出ID的请求(将弃用)

重要

已弃用的请求类型. 此示例类型描述了API版本1的请求类型。 在临时激活API v2中,您无需包含最新的受众导出作业ID。

curl -X POST https://platform.adobe.io/data/core/activation/disflowprovider/adhocrun \
 -H 'Authorization: Bearer {ACCESS_TOKEN}' \
 -H 'Content-Type: application/json' \
 -H 'x-gw-ims-org-id: {ORG_ID}' \
 -H 'x-api-key: {API_KEY}' \
 -d '
{
   "activationInfo":{
      "destinationId1":[
         "segmentId1",
         "segmentId2"
      ],
      "destinationId2":[
         "segmentId2",
         "segmentId3"
      ]
   },
   "exportIds":[
      "exportId1"
   ]
}
属性 描述
  • destinationId1
  • destinationId2
要将受众激活到的目标实例的ID。 您可以通过导航到,从Platform UI获取这些ID 目标 > 浏览 选项卡,然后单击所需的目标行以在右边栏中显示目标ID。 有关详细信息,请阅读 目标工作区文档.
  • segmentId1
  • segmentId2
  • segmentId3
要激活到选定目标的受众的ID。
  • exportId1
响应中返回的ID 受众导出 作业。 参见 步骤4:获取最新的受众导出作业ID 以获取有关如何查找此ID的说明。

响应

成功的响应返回HTTP状态200。

{
   "order":[
      {
         "segment":"db8961e9-d52f-45bc-b3fb-76d0382a6851",
         "order":"ef2dcbd6-36fc-49a3-afed-d7b8e8f724eb",
         "statusURL":"https://platform.adobe.io/data/foundation/flowservice/runs/88d6da63-dc97-460e-b781-fc795a7386d9"
      }
   ]
}
属性 描述
segment 已激活受众的ID。
order 受众被激活到的目标的ID。
statusURL 激活流的状态URL。 您可以使用来跟踪流进度 流服务API.

API错误处理

Destination SDKAPI端点遵循常规Experience PlatformAPI错误消息原则。 请参阅 API状态代码请求标头错误 平台疑难解答指南中的。

特定于Ad Hoc Activation API的API错误代码和消息

使用临时激活API时,您可能会遇到特定于此API端点的错误消息。 请查看表以了解如何在它们出现时解决它们。

错误消息 解决方法
已针对受众运行 segment ID 订购 dataflow ID 具有运行id flow run ID 此错误消息表示受众当前正在进行临时激活流程。 等待作业完成,然后再触发激活作业。
区段 <segment name> 不是此数据流的一部分或超出计划范围! 此错误消息表示您选择要激活的受众未映射到数据流,或者为受众设置的激活计划已过期或尚未开始。 检查受众是否确实映射到数据流,并验证受众激活计划是否与当前日期重叠。

在此页面上