开发人员指南概述

亚马逊广告 API 概览

创建 DSP 报告

本教程概述了如何通过异步方式请求并下载 DSP 广告活动的报告。

如何生成报告：

  1. 检索您的账户编号 (accountId)
  2. 请求报告
  3. 等待报告生成
  4. 下载报告

提示：请在 Postman 中进行尝试

使用亚马逊广告 API Postman 系列的报告 (Reporting) 文件夹来按本教程进行操作。有关设置说明，请参阅亚马逊广告的 Postman 教程。

标头

本教程中描述的每项请求都需要 4 个标头参数：

参数 描述
Amazon-Advertising-API-ClientId 与您的“Login with Amazon”应用程序关联的客户端编号。用于身份验证。
Authorization 您的访问令牌.用于身份验证。
Accept 指定期望的响应内容；取决于请求接口。

设置为 application/vnd.dspcreatereports.v3+json 来请求报告，设置为 application/vnd.dspgetreports.v3+json 来检查报告状态。
Content-Type 设置为 application/json。

有关 API 身份验证的简介，请参阅授权概述。

检索您的 accountId

无论您要生成报告还是检索报告，都需要使用您的accountId。accountId 用于 身份验证以及确定报告范围。

检索 accountId 的方式取决于您的账户是管理账户还是自助式账户。有关更多信息，请参阅不同账户类型的报告。

生成报告

请求报告

DSP 报告支持多种报告类型和指标。有关支持的配置的更多信息，请参阅报告类型。

所有报告请求都使用单独的接口： POST /accounts/{accountId}/dsp/reports。有关参数的详细信息，请参阅 API 参考。

timeUnit

timeUnit 可以设置为 DAILY 或 SUMMARY。DAILY 用于对该时间段内的每日数据进行聚合，而 SUMMARY 则对整个时间段内的数据进行聚合。AUDIENCE 报告类型不支持 DAILY timeUnit。开始日期 (startDate) 和结束日期 (endDate) 之间的最大日期范围为 31 天。endDate 最长为当前日期之前 90 天。

请求正文示例（timeUnit 设置为 SUMMARY）

{
    "dimensions" ["ORDER", "LINE_ITEM"],
    "timeUnit": "DAILY",
    "startDate": "2022-12-05",
    "endDate": "2022-12-19"
}

Sample request body (timeUnit set to SUMMARY)

{
    "dimensions" ["ORDER", "LINE_ITEM"],
    "timeUnit": "SUMMARY",
    "startDate": "2022-12-05",
    "endDate": "2022-12-19"
}

dimensions

维度决定了报告的聚合级别。添加维度会自动在报告中添加该维度的指标。如果您添加多个维度，DSP 报告 API 将使用最低级别的维度进行数据聚合，并在报告中包含每个已添加的维度的维度指标。有关更多信息，请参阅维度。

advertiserIds

自助式 DSP 实体所有者可以使用 advertiserIds 字段请求特定广告主提供的数据。有关更多信息，请参阅不同账户类型的报告。

注意

每份报告最多只能请求 100 位广告主的数据。如果您需要对 100 位以上广告主进行报告分析，需请求多个报告。

默认值

默认情况下，在 POST /accounts/{accountId}/dsp/reports 请求正文中：

您必须在请求中指定startDate 和 endDate。

请求示例

此示例显示了 accountId 为 ID123456789 的广告主请求提供 2022 年 12 月 5 日至 2022 年 12 月 19 日期间的 DSP 广告活动报告摘要。

注意

本教程中调用的示例采用北美 API 接口 (https://advertising-api.amazon.com)。请参阅 API 概述，了解根据您所在的站点应使用的区域接口。

curl --location --request POST 'https://advertising-api.amazon.com/accounts/ID123456789/dsp/reports' \
     --header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxxxxx' \
     --header 'Content-Type: application/json' \
     --header 'Authorization: Bearer Atza|xxxxxxxxxxx' \
     --header 'Accept: application/vnd.dspcreatereports.v3+json' \
     --data-raw '{
         "metrics": ["totalFee", "totalCost", "clickThroughs", "purchasesClicks14d", "eCPM", "impressions", "ROAS14d"],
         "dimensions": ["ORDER", "LINE_ITEM"],
         "startDate": "2022-12-05",
         "endDate": "2022-12-19"
     }'

响应示例

成功的请求响应包括 reportId 和 status 字段。

{
    "reportId": "b2230738-5b81-2423-a3a6-380d5522ba78",
    "type": "CAMPAIGN",
    "format": "JSON",
    "status": "IN_PROGRESS",
    "statusDetails": "In progress",
    "location": "",
    "expiration": "2023-02-01T20:25:13.356Z"
}

等待报告生成

成功进行 POST 调用后，报告生成最多可能需要 3 小时。

您可以通过使用初始请求中返回的 reportId 来调用 GET 报告接口，检查报告生成状态： GET /accounts/{accountId}/dsp/reports/{report-id}.

请求示例

curl --location --request GET /accounts/{accountId}/dsp/reports/{report-id} \
     --header 'Content-Type: application/vnd.dspgetreports.v3+json' \
     --header 'Amazon-Advertising-API-ClientId: amzn1.application-oa2-client.xxxxxxxxxx' \
     --header 'Authorization: Bearer Atza|xxxxxxxxxxx'  \

所有针对 GET 状态接口的成功调用都会返回 200 状态代码。要检查报告生成是否已完成，请检查响应正文中的 status 参数。如果报告仍在生成中，则 status 设置为 PENDING 或 PROCESSING。

当您的报告可供下载时，status 将返回 SUCCESS，并且 location 字段中将显示一个地址。

响应示例（报告正在生成）

{
    "reportId": "TEST123",
    "type": "CAMPAIGN",
    "format": "JSON",
    "status": "IN_PROGRESS",
    "statusDetails": "In progress",
    "location": "",
    "expiration": "2022-12-28T19:30:25.632Z"
}

Sample response (report generation completed)

{
    "reportId": "TEST123",
    "type": "INVENTORY",
    "format": "JSON",
    "status": "SUCCESS",
    "statusDetails": "Success",
    "location": "https://corvo-reports.s3.amazonaws.com/DSP_API/2023-02-13/TEST123/inventory-report-TEST123.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20230213T231410Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=TEST123%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=TEST123",
    "expiration": "2023-02-14T00:14:10.562Z"
}

下载报告

报告准备就绪后，GET /accounts/{accountId}/dsp/reports/{report-id}的位置字段会包含一个指向 S3 存储桶的链接，您可以通过该链接下载报告。您可以使用 cURL 或在浏览器中输入 URL 来进行 GET 调用。

阅读报告

查看报告的原始 JSON 文件。在报表中，数据的聚合级别取决于您指定的维度。JSON 示例中，ORDER 级别的报告可能如下所示：

[
  {
    "orderExternalId": "6677889900",
    "orderEndDate": 1690862340000,
    "orderId": 123042566401569500,
    "orderStartDate": 1633562280000,
    "orderCurrency": "USD",
    "intervalEnd": 1674432000000,
    "orderBudget": 10000,
    "entityId": "TEST123",
    "intervalStart": 1674345600000,
    "advertiserName": "Test Account One",
    "advertiserId": 123123123,
    "orderName": "One Test Order"
  },
  {
    "orderExternalId": null,
    "orderEndDate": 1702627140000,
    "orderId": 123582641277101200,
    "orderStartDate": 1650265200000,
    "orderCurrency": "USD",
    "intervalEnd": 1674432000000,
    "orderBudget": 50000,
    "entityId": "TEST123",
    "intervalStart": 1674345600000,
    "advertiserName": "Test - Audio",
    "advertiserId": 123456789,
    "orderName": "Audio test order"
  }
]

进一步了解

Amazon Advertising logo