开发人员指南概述

亚马逊广告 API 概览

Amazon Marketing Stream 入门指南

按照本教程中的步骤将您的 AWS 应用程序关联到 Amazon Marketing Stream 数据集。在本教程结束时，您将能开始在 SQS 队列中接收效果和广告活动数据。

前提条件

要完成本教程，您需要：

提示

使用亚马逊提供的参考应用程序来加入 Stream。亚马逊提供的基于 Python 的参考应用程序使用 AWS CDK 来帮助您以程序化方式完成文档中列出的步骤。进一步了解。

第 1 步： 创建 SQS 队列

要使用 Amazon Marketing Stream 接收数据，您必须先使用 AWS Simple Queue Service (SQS) 设置队列。我们建议让熟悉 AWS 的人员完成 AWS 设置。

您可以通过登录您的 AWS 账户并使用 SQS 平台 或使用 AWS CloudFormation 模板来创建队列。

CloudFormation

提示

为避免在加入期间出错，我们建议使用 CloudFormation 模板，而不是在 SQS 平台中手动设置队列。

要使用 CloudFormation 模板，请按照CloudFormation 入门指南中的说明进行操作。

亚马逊提供的 CloudFront 模板会自动添加基于资源的有效 IAM 策略，因此，如果您使用的是 CloudFormation，则可以跳过本指南中的第 2 步，直接进入第 3 步。

SQS 平台

您也可以使用 SQS 平台手动创建 SQS 队列。按照AWS 文档中的说明进行操作。

使用下表确定要在哪个区域创建队列：

广告主所在区域 AWS 区域
北美 us-east-1
欧洲 eu-west-1
远东 us-west-2

有关支持的国家/地区的完整详细信息，请参阅地理位置适用情况。

注意

您必须创建 Standard 队列；当前不支持 FIFO 队列。

第 2 步： 添加基于资源的 IAM 策略

警告

您必须向队列添加有效的 IAM 策略才能接收 Amazon Marketing Stream 数据。

数据集和区域的每种组合采用不同的 IAM 策略。例如，sp-traffic 数据集针对北美、欧洲和远东采用不同的 IAM 策略。请确保根据您要订阅的数据集应用正确的 IAM 策略。要查看所有可用数据集和区域的基于资源的 IAM 策略，请参阅 Amazon Marketing Stream 数据指南。

您可以在创建队列时添加访问策略，也可以编辑现有队列。

注意

插入 IAM 策略时，请确保 Resource 指向您自己的队列的亚马逊资源名称 (ARN)。

第 3 步： 订阅亚 Amazon Marketing Stream 数据集

设置队列并添加 IAM 策略后，您可以使用 Amazon Marketing Stream 订阅 API 来订阅广告主数据。您需要为要订阅的每个数据集单独发出请求。

警告

在发送订阅请求之前，请确保您已将与数据集关联的 IAM 策略应用于您的 SQS 队列。

如果您要订阅多个企业资料的数据，则必须为每个企业资料单独进行调用。

提示

使用亚马逊的 Postman 集合 来测试 Amazon Marketing Stream API。集合和环境设置完成后，请查看 Amazon Marketing Stream 文件夹以调用 API。

请求

标头

参数 描述
Amazon-Advertising-API-ClientId 与您的“Login with Amazon”应用程序关联的客户端编号。
Amazon-Advertising-API-Scope 您的配置文件标识符。
Authorization 您的访问令牌。
Content-Type application/vnd.MarketingStreamSubscriptions.StreamSubscriptionResource.v1.0+json

参数

| 参数 | 必填 | 描述 | |-----------|-------------| | dataSetId | 是 | 要查看所有可用的数据集，请参阅数据指南。 | | destinationArn | 是 | 您要接收数据的 SQS 队列的 ARN。 | | clientRequestToken | 是 | 调用方提供的用于跟踪相同的 API 请求的唯一值。如果需要重新尝试请求，调用方应提供相同的值。我们建议使用 GUID。 | | notes | 否 | 可用于确定目标位置的其他详细信息。 |

示例

请确保将 Amazon-Advertising-API-ClientId、Amazon-Advertising-API-Scope、Authorization 和 destinationArn 替换为特定于您的账户的值。clientRequestToken 可以是任何幂等性令牌，可以在需要时用于标识请求。

    curl --location --request POST 'https://advertising-api.amazon.com/streams/subscriptions' \
    --header 'Amazon-Advertising-API-ClientId: xxxxxx' \
    --header 'Amazon-Advertising-API-Scope: xxxxxxx' \
    --header 'Content-Type: application/vnd.MarketingStreamSubscriptions.StreamSubscriptionResource.v1.0+json' \
    --header 'Authorization: Bearer xxxxxxxxx' \
    --data-raw '{
    "clientRequestToken": "123456789xyz1234567",
    "dataSetId": "sp-conversion",
    "notes": "Advertiser 1 sp-conversion subscription",
    "destinationArn": "QUEUE_ARN"
    }‘

响应

A successful request results in a response that includes a subscriptionId.

{
    "subscriptionId": "xxxxxxxxxxxxxx",
    "clientRequestToken": "123456789xyz1234567",
}

第 4 步： 在 SQS 中确认您的订阅

使用 API 成功订阅 Amazon Marketing Stream 后，您需要在 SQS 中确认订阅才能开始接收数据。

您应该会在 SQS 队列中看到一条类似于下面的消息：

{
    "Type" : "SubscriptionConfirmation",
    "MessageId" : "165545c9-2a5c-472c-8df2-7ff2be2b3b1b",
    "Token" : "2336412f37...",
    "TopicArn" : "arn:aws:sns:us-west-2:123456789012:MyTopic",
    "Message" : "You have chosen to subscribe to the topic arn:aws:sns:us-west-2:123456789012:MyTopic.To confirm the subscription, visit the SubscribeURL included in this message.",
    "SubscribeURL" : "https://sns.us-west-2.amazonaws.com/?Action=ConfirmSubscription&TopicArn=arn:aws:sns:us-west-2:123456789012:MyTopic&Token=2336412f37...",
    "Timestamp" : "2012-04-26T20:45:04.751Z",
    "SignatureVersion" : "1",
    "Signature" : "EXAMPLEpH+DcEwjAPg8O9mY8dReBSwksfg2S7WKQcikcNKWLQjwu6A4VbeS0QHVCkhRS7fUQvi2egU3N858fiTDN6bkkOxYDVrY0Ad8L10Hs3zH81mtnPk5uvvolIC1CXGu43obcgFxeL3khZl8IKvO61GWB6jI9b5+gLPoBc1Q=",
    "SigningCertURL" : "https://sns.us-west-2.amazonaws.com/SimpleNotificationService-f3ecfb7224c7233fe7bb5f59f96de52f.pem"
}

要开始接收队列中的数据，您必须通过以下方式之一确认订阅：

  1. 对 SQS 队列确认消息中返回的 SubscribeURL 值发出 GET 请求。此调用应该会返回一条消息，表示订阅已确认，队列应该开始接收消息。

    确认消息示例

    <ConfirmSubscriptionResponse>
    <ConfirmSubscriptionResult>
        <SubscriptionArn>arn:aws:sns:us-east-2:123456789012:MyTopic:1234a567-bc89-012d-3e45-6fg7h890123i</SubscriptionArn>
    </ConfirmSubscriptionResult>
    <ResponseMetadata>
        <RequestId>abcd1efg-23hi-jkl4-m5no-p67q8rstuvw9</RequestId>
    </ResponseMetadata>
</ConfirmSubscriptionResponse>

  2. 借助 AWS SDK，使用 SQS 队列确认消息中返回的 Token 和 TopicArn 值调用 ConfirmSubscription。

注意

您必须确认您要订阅的每个广告主和数据集的订阅。

如果您要接收同一队列中的多个广告主或数据集的数据，则应考虑使用上面的选项 2 来创建一个以程序化方式确认订阅的应用程序。该应用程序应该侦听队列并将确认消息与数据事件区分开。

您可以使用类似于下面的逻辑来标识订阅消息与数据事件：

    if "Type" in content and content['Type'] == 'SubscriptionConfirmation':

    def confirm_subscription(content):
        token = content['Token']
        topicArn = content['TopicArn']
        print(f"Confirming subscription for {topicArn}")
        sns.confirm_subscription(TopicArn=topicArn, Token=token)

订阅状态流程

您可以在下图中查看 Stream 订阅的状态流程。

Stream 状态流程图

在管理订阅中进一步了解可能的订阅状态。

后续步骤

确认订阅并开始接收数据后，您可以继续前往以下内容：

常见问题解答

为何我在前一两天的数据中看到负值？

负值是根据亚马逊的点击和转化验证流程进行的追溯性更正。在我们启用连接后的前一两天，您可能会收到负的汇总值，因为您没有收到这些天的原始流量，只收到了更正值。建议在前一两天忽略负值。

前两天过后，您应该开始收到正值；如果两天后仍未看到正的汇总值，请联系支持人员。

由于点击无效而出现更正时，您将继续看到负增量，但它们通常会与正值进行聚合。

为何我会收到空值记录？

您可以忽略这些行。这是正常现象，这些行没有什么影响，不会导致数据出现问题，因为它们的总和为 0。

我已经创建了队列，当我尝试使用 POST /streams/subscriptions 进行订阅时，收到错误代码 400，表示不支持我所在的区域。

在当前状态下，Amazon Marketing Stream 仅支持三个区域：us-east-1 (NA), eu-west-1 (EU) 和 us-west-2 (FE)。创建 SQS 队列时，请确保仅使用支持的区域。为避免此类错误，我们建议使用亚马逊提供的CloudFormation 模板 来创建队列。

我的订阅状态是 PENDING_CONFIRMATION，但我从未在 SQS 中收到确认消息。

您可能对队列应用了错误的 IAM 策略。请确保您在队列中使用的 IAM 策略与广告主企业资料所在的区域以及您尝试订阅的数据集相匹配。

如果您对队列应用了错误的 IAM 策略，则应创建一个新队列并应用正确的策略，然后使用新的队列 ARN 再次订阅数据集。

提示

我们建议使用亚马逊提供的 CloudFormation 模板来创建队列，以降低出现手动错误的风险。

如果您确定自己应用了正确的 IAM 策略，但一直停留在 PENDING_CONFIRMATION 状态，请提交工单 ，我们的支持团队可以手动重新发送确认消息。

我的订阅状态停留在 PENDING_CONFIRMATION，无法更改为 FAILED_CONFIRMATION。

如果您未在三天内确认订阅，则状态应能自动更改为 FAILED_CONFIRMATION。状态更改为 FAILED_CONFIRMATION 后，您可以再次发送数据集订阅请求。在极少数情况下，状态可能不会自动切换为 FAILED_CONFIRMATION，此时您应向我们的支持团队提交工单。

或者，您可以创建一个新队列，应用相关的 IAM 策略，然后尝试使用新的队列 ARN 再次订阅数据集。

我已成功确认在 SQS 中的订阅，但我的 SQS 目标队列中没有收到任何消息。

由于 Amazon Marketing Stream 可以近乎实时地提供数据，因此在订阅的数据集和站点中必须发生与广告主及其广告活动相关的事件才能发送相应的内容。如果没有发生这些事件，则不会产生数据。换句话说，只有当该广告活动在一小时内有获得一定的效果时，才会发送数据。

我似乎收到了重复的数据。

如果您似乎收到了重复的记录，请确保先检查您的数据。在某些情况下，您收到的数据可能与重复数据相似，但实际上是有效数据。

首先，两个不同小时的数据可能非常相似。例如，假设一个关键词在指定日期的第一小时内获得 10 次展示量和 3 次点击量。在第二小时内，再次获得 10 次展示量和 3 次点击量。Amazon Marketing Stream 将在两个小时内发送该关键词的相似记录，仅按与数据相关的小时进行区分。对于没有太多展示量的关键词，可能只能显示 1 次展示量，且全天数个小时都未产生点击量。

其次，Amazon Marketing Stream 每小时发送一次您的广告活动的增量数据，因此重新陈述可能导致记录看起来几乎相同。这可能导致同一个关键词和同一个小时的点击量和展示量数据出现两条记录，其中一条是原始增量，而第二条是重新陈述。这不是重复记录，并且可以通过检查这两条记录的idempotency_id 进行验证。如果幂等性编号不同，则表示不是重复记录，而是该关键词和小时的两个不同记录。

如何取消订阅？

目前无法删除或取消订阅。要停止接收订阅数据，应将 subscriptionStatus 设置为 ARCHIVED。有关更多信息，请参阅管理订阅。

Amazon Advertising logo