通过临时激活API按需激活受众

最近更新： 2026年8月19日

创建对象：

{"id":"b69b2659-1057-424e-8fc5-ed9e016dc554"},{"id":"c66ffd68-0f65-42bb-aa23-b4020f12e0bd"}

IMPORTANT

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

有关详细信息，请参阅本教程中下面的进一步运行临时激活作业。

概述 overview

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

使用临时激活API将受众按需激活到基于文件的批处理目标，并从v4开始将受众激活到流式和基于API的目标。请参阅本教程下面的触发临时激活运行。

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

临时激活

用例 use-cases

Flash销售或促销 flash-sales

一家在线retailer正准备进行限时限价促销，希望能在短时间内通知客户。通过Experience Platform临时激活API，营销团队可以按需导出受众，并快速向客户群发送促销电子邮件。

当前事件或突发新闻 current-events

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

集成测试 integration-testing

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

流目标的受众刷新 audience-refresh-streaming

流或基于API的目标将生存时间(TTL)应用于它从Adobe Experience Platform收到的受众成员资格。当该TTL在目标端过期时，以前符合条件的用户档案将被视为不活动，即使这些用户档案在Experience Platform中仍符合条件。营销团队可以使用v4的临时激活API ，按需重新发送受众的当前完整成员资格，而无需等待下一个计划的刷新。请参阅本教程下面的触发临时激活运行。

护栏 guardrails

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

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

分段注意事项 segmentation-considerations

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

步骤1：先决条件 prerequisites

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

您拥有可访问Adobe Experience Platform的组织帐户。
您的Experience Platform帐户已为Adobe Experience Platform API产品配置文件启用developer和user角色。请与您的Admin Console管理员联系，为您的帐户启用这些角色。
你有Adobe ID。如果您没有Adobe ID，请转到Adobe Developer Console并创建新帐户。

步骤2：收集身份证明 credentials

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

授权：持有人{ACCESS_TOKEN}
x-api-key： {API_KEY}
x-gw-ims-org-id： {ORG_ID}

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

x-sandbox-name： {SANDBOX_NAME}

NOTE

有关Experience Platform中沙盒的更多信息，请参阅沙盒概述文档。

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

内容类型： application/json

API参考文档 api-reference-documentation

您可以在本教程中找到所有API操作的随附参考文档。请参阅Ad Hoc Activation API引用。

步骤3：在Experience Platform UI中创建激活流程 activation-flow

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

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

步骤4：获取最新的受众导出作业ID（v2中不需要） segment-export-id

IMPORTANT

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

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

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

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

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

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

受众导出作业ID位于id属性中，如下所示。

受众导出作业ID

步骤5：运行临时激活作业 activation-job

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

IMPORTANT

请注意以下一次性限制：在运行临时激活作业之前，请确保根据您在步骤3 — 在Experience Platform UI中创建激活流中设置的计划首次激活受众时起已过去至少一个小时。

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

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

NOTE

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

请求 request

IMPORTANT

必须在使用v2的临时激活API的请求中包含Accept: application/vnd.adobe.adhoc.activation+json; version=2标头。

对于非分段服务受众（例如，外部或自定义上传受众），您必须指定Experience Platform在请求中生成的受众ID，而不是外部受众ID。在受众UI中打开受众详细信息页面时，您可以在受众摘要面板的顶部找到系统生成的ID，该ID显示为ID#，后跟UUID。

显示系统生成的ID字段的受众摘要面板在面板顶部突出显示。

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。您可以导航到目标 > 浏览选项卡，然后单击所需的目标行在右边栏中显示目标ID，从而从Experience Platform UI获取这些ID。有关详细信息，请阅读目标工作区文档。

segmentId1
segmentId2
segmentId3

要激活到所选目标的受众的ID。您可以使用临时API导出Experience Platform生成的受众以及外部（自定义上传）受众。激活外部受众时，请使用系统生成的ID而不是受众ID。您可以在受众UI的受众摘要视图中找到系统生成的ID。

{width="100" modal="regular"}

{width="100" modal="regular"}

使用导出ID的请求 request-export-ids

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

segmentId1
segmentId2
segmentId3

要激活到所选目标的受众的ID。

exportId1

受众导出作业的响应中返回的ID。有关如何查找此ID的说明，请参阅步骤4：获取最新的受众导出作业ID。

响应 response

成功的响应返回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错误处理 api-error-handling

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

特定于ad hoc activation API的API错误代码和消息 specific-error-messages

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

错误消息

解决方法

已为运行ID为flow run ID的订单dataflow ID运行受众segment ID

此错误消息表示受众当前正在进行临时激活流程。等待作业完成，然后再触发激活作业。

区段<segment name>不是此数据流的一部分或超出计划范围！

此错误消息表示您选择要激活的受众未映射到数据流，或者为受众设置的激活计划已过期或尚未开始。检查受众是否确实映射到数据流，并验证受众激活计划是否与当前日期重叠。

(Beta)触发临时激活运行 streaming-destinations

IMPORTANT

流和基于API的目标的临时激活功能目前处于测试阶段。此功能将分阶段推出，并带有功能标记闸门。

使用Ad Hoc Activation API的v4触发Activate now，即按需将受众完全成员资格刷新到流或基于API的目标。

许多流式传输和基于API的目标将生存时间(TTL)应用于他们从Adobe Experience Platform收到的受众成员资格。当该TTL在目标端过期时，以前符合条件的用户档案将被视为不活动，即使这些用户档案在Experience Platform中仍符合条件。触发v4临时激活运行，通过现有的流激活管道重新发送每个当前符合条件的配置文件，而无需等待下一个计划的刷新。

您还可以从Experience Platform UI触发此刷新。阅读立即激活流目标。

流式护栏 streaming-guardrails

对流目标的临时激活会强制实施以下限制：

在滚动的24小时窗口内，每个受众每个数据流可按需运行一次（不是日历日重置）。

流请求 streaming-request

IMPORTANT

必须在使用v4的临时激活API的请求中包含Accept: application/vnd.adobe.adhoc.streaming.activation+json; version=1标头。

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}' \
 -H 'x-sandbox-name: {SANDBOX_NAME}' \
 -H 'Accept: application/vnd.adobe.adhoc.streaming.activation+json; version=1' \
 -d '
{
   "activationInfo":{
      "destinationId1":[
         "segmentId1",
         "segmentId2"
      ]
   }
}'

属性

描述

destinationId1

要向其交付受众的流或基于API的目标实例的ID。您可以导航到目标 > 浏览选项卡，然后选择所需的目标行以在右边栏中显示目标ID，从而从Experience Platform UI获取此ID。有关详细信息，请阅读目标工作区文档。

segmentId1
segmentId2

要交付到所选目标的受众的ID。

流响应 streaming-response

成功的响应返回HTTP状态202（已接受），并为每个请求的受众创建一个流作业。

{
   "jobs":[
      {
         "jobId":"88d6da63-dc97-460e-b781-fc795a7386d9",
         "flowId":"ef2dcbd6-36fc-49a3-afed-d7b8e8f724eb",
         "audienceId":"db8961e9-d52f-45bc-b3fb-76d0382a6851",
         "imsOrgId":"{ORG_ID}",
         "status":"QUEUED",
         "createdAt":"2026-08-17T14:00:00Z"
      }
   ]
}

属性

描述

jobId

此流作业的唯一标识符。

flowId

触发作业的数据流的ID。

audienceId

正在投放的受众ID。

status

在此版本中始终为QUEUED。当前没有跟踪此状态之后的进度的机制。请参阅已知限制。

createdAt

创建作业的时间戳。

如果过去24小时内已经为此数据流触发了相同受众，则请求会通过HTTP 409和一个Retry-After标头被拒绝，标头指示您可以重试的秒数。

recommendation-more-help

experience-platform-help-destinations

通过临时激活API按需激活受众

概述 overview

用例 use-cases

Flash销售或促销 flash-sales

当前事件或突发新闻 current-events

集成测试 integration-testing

流目标的受众刷新 audience-refresh-streaming

护栏 guardrails

分段注意事项 segmentation-considerations

步骤1：先决条件 prerequisites

步骤2：收集身份证明 credentials

API参考文档 api-reference-documentation

步骤3：在Experience Platform UI中创建激活流程 activation-flow

步骤4：获取最新的受众导出作业ID（v2中不需要） segment-export-id

步骤5：运行临时激活作业 activation-job

请求 request

使用导出ID的请求 request-export-ids

响应 response

API错误处理 api-error-handling

特定于ad hoc activation API的API错误代码和消息 specific-error-messages

(Beta)触发临时激活运行 streaming-destinations

流式护栏 streaming-guardrails

流请求 streaming-request

流响应 streaming-response

相关信息 related-information