报告

使用 requestReport 操作来检索绩效报告。有多种方法可以检索广告活动数据，使用报告并不总是最高效的方式。如果您希望下载广告活动结构及其所有实体（例如 AdGroups、keywords、productAds）的记录，我们建议您运行实体的快照，而不是请求广告活动中所有元素的列表。如果您希望了解更多信息，请参阅快照。

**注意：**在生成报告（POST）时，商品推广和品牌推广这两种广告类型的报告对应不同的端点。这些端点在每段的开头进行指定。在检索报告编号并下载报告（GET）时，无需根据广告类型区分端点。

下表描述了有关 URL 空间和支持的 HTTP 方法的服务行为，这些行为由服务管理资源提供支持。

方法	URL	用例
POST	`/{recordType}/report`	请求为含有绩效数据的单个类型的所有实体创建绩效报告。
GET	`/reports/{reportId}`	检索先前请求的绩效报告的状态、元数据和位置。

操作

requestReport

POST /{recordType}/report       

 {                                
   "campaignType": {campaignType},
   "segment": {segment},           
   "reportDate": {reportDate},     
   "metrics": {metrics}             
 }

参数

参数名称	类型	指定位置	描述
`recordType`	string	URL	应为其生成报告的实体类型。必须是以下值之一：`campaigns`、`adGroups`、`keywords`、`productAds` 或 `asins`
`campaignType`	string	POST 体	应为其生成绩效数据的广告活动类型。必须为：`sponsoredProducts` 或 `headlineSearch`
`segment`	string	POST 体	可选。报告分段的维度。如果已指定，必须是关键词报告的 `query` 或广告活动报告的 `placement`。
`reportDate`	string	POST 体	以 YYYYMMDD 格式检索绩效报告的日期。时区由用于请求报告的配置文件指定。如果日期是今天，则效果报告可能包含部分信息。报告不可用于 60 天前的数据。有关数据延迟的详细信息，请参阅开发人员备注中的“服务保证（Service Guarantees）”。
`metrics`	string	POST 体	以逗号分隔的要包含在报告中的指标列表。

响应

状态码	响应对象
`202 - success`	`ReportResponse`
`401 - unauthorized`	`Error`
`406 – not acceptable`	`Error`（由于报告日期过早而产生故障）
`422 - unprocessable entity`	`Error`（由于参数不正确而产生故障）

getReport

GET /reports/{reportId}

检索先前请求的报告，通过 reportId 进行标识。

参数

参数名称	类型	指定位置	描述
`reportId`	number	URL 路径	请求的报告编号

响应

状态码	响应对象
`200 - success`	`ReportResponse`
`401 - unauthorized`	`Error`
`404 - report not found`	`Error`
`404 - not found server`	`Error`

ReportResponse 将包含报告状态。当报告完成时， location 字段将提供包含报告的 Gzip 格式压缩文件的重定向 URL。如果您希望了解更多信息，请参阅下载报告。

有效的报告请求

如果指定的参数无法识别或参数组合不受支持，报告请求将返回 422。特别是， recordType 的选择可能限制某些分段（segment）的使用。查询区段只能与关键词报告结合使用。

如果收到 “404 - Not Found Server” 错误，请检查是否正确输入了 entityType 端点。必须是以下值之一：campaigns、adGroups、keywords、asins 或 productAds

资源表现（resource representation）

ReportResponse

{
    "title": "ReportResponse",
    "type": "object",
    "properties": {   
      "reportId": {
           "description": "The ID of the report that was requested.",
           "type": "string"
       },
      "recordType": {
           "description": "The record type of the report.It can be campaigns, adGroups, productAds or keywords.",
           "type": "string"
       },
       "status": {
           "description": "The status of the generation of the report, it can be IN_PROGRESS, SUCCESS or FAILURE.",
           "type": "string"
       },
       "statusDetails": {
           "description": "Description of the status.",
           "type": "string"
       },
       "location": {
           "description": "The URI from the API service from which a redirect to the report can be found.It's only available if status is SUCCESS.",
           "type": "string"
       },
       "fileSize": {
           "description": "The size of the report file in bytes.It's only available if status is SUCCESS.",
           "type": "number"
       }
    }
}

错误

请参阅开发人员备注中的错误对象返回格式。

报告文件格式

报告文件中包含了每个绩效数据的实体的一行记录。这些记录以 JSON 格式表示，包含与 recordType 对应的 ID 属性、分段（如果指定）以及请求中的每个指标。

例如，使用以下调用请求的报告：

POST /keywords/report                

 {                                     

 "campaignType": "sponsoredProducts",
 "segment":"query",                   
 "reportDate":"20180310",             
 "metrics":"impressions,clicks"        

 }                                     |

将生成类似以下的报告：

[                                                                                           
 {"keywordId":123, "query": "red iphone case", "impressions": 584920, "clicks": 2989},        
 {"keywordId":123, "query": "blue iphone 6s case", "impressions": 8348230, "clicks": 16483},  
 {"keywordId":456, "query": "chuck taylor all star", "impressions": 83910, "clicks": 2483},   
 {"keywordId":456, "query": "converse chuck taylor", "impressions": 2349190, "clicks": 1238},
 {"keywordId":456, "query": "chuck taylor", "impressions": 291827, "clicks": 1289},           
 {"keywordId":789, "query": "rare earth magnets", "impressions": 99375092, "clicks": 912037},
 {"keywordId":789, "query": "magnets", "impressions": 93894023, "clicks": 238482},            
 {"keywordId":789, "query": "strong magnets", "impressions": 292, "clicks": 1}                 
]

报告下载中

报告完成后，location 字段将提供一个 URL，用于对生成的报告进行下载操作。请注意，针对此 URI 的请求需要身份验证，因此必须传递授权标头。对这些请求的响应将不包含体（body），并将返回一个带有位置标头的 307 重定向，其中包含了 S3 文件位置。生成的文件位置的有效期很短（30 秒过期）。如果在客户端开始下载文件之前经过此时间，客户端可以对下载操作 URI 发出另一个请求。

请注意，S3 中的报告文件采用 Gzip 压缩格式。

报告指标

下表汇总了可通过“报告”界面请求的报告指标。不同的报告类型可使用不同的指标。

广告活动报告

这些指标可用于请求以下类型的报告：campaigns

指标	详细信息
`bidPlus`	维度指标。请参阅开发人员备注中的高级竞价调整。
`campaignName`	广告活动的唯一名称
`campaignId`	广告活动的唯一数字编号
`campaignStatus`	广告活动状态
`campaignBudget`	分配给广告活动的总预算
`impressions`	广告总展示量。
`clicks`	广告总点击量。
`cost`	所有点击的总成本。可以除以点击量来得出平均每次点击成本（CPC）。
`attributedConversions1d`	点击广告后 1 天内发生的由此产生的转化事件的数量。
`attributedConversions7d`	点击广告后 7 天内发生的由此产生的转化事件的数量。
`attributedConversions14d`	点击广告后 14 天内发生的由此产生的转化事件的数量。
`attributedConversions30d`	点击广告后 30 天内发生的由此产生的转化事件的数量。
`attributedConversions1dSameSKU`	点击广告后 1 天内发生的归因转化事件数，其中购买的 SKU 与推广的 SKU 相同。
`attributedConversions7dSameSKU`	点击广告后 7 天内发生的归因转化事件数，其中购买的 SKU 与推广的 SKU 相同。
`attributedConversions14dSameSKU`	点击广告后 14 天内发生的归因转化事件数，其中购买的 SKU 与推广的 SKU 相同。
`attributedConversions30dSameSKU`	点击广告后 30 天内发生的归因转化事件数，其中购买的 SKU 与推广的 SKU 相同。
`attributedUnitsOrdered1d`	点击广告后 1 天内发生的归因于广告的已订购商品数量。
`attributedUnitsOrdered7d`	点击广告后 7 天内发生的归因于广告的已订购商品数量。
`attributedUnitsOrdered14d`	点击广告后 14 天内发生的归因于广告的已订购商品数量。
`attributedUnitsOrdered30d`	点击广告后 30 天内发生的归因于广告的已订购商品数量。
`attributedSales1d`	点击广告后 1 天内发生的归因于广告的销量。
`attributedSales7d`	点击广告后 7 天内发生的归因于广告的销量。
`attributedSales14d`	点击广告后 14 天内发生的归因于广告的销量。
`attributedSales30d`	点击广告后 30 天内发生的归因于广告的销量。
`attributedSales1dSameSKU`	点击广告后 1 天内发生的归因销售总价值，其中购买的 SKU 与推广的 SKU 相同。
`attributedSales7dSameSKU`	点击广告后 7 天内发生的归因销售总额，其中购买的 SKU 与推广的 SKU 相同。
`attributedSales14dSameSKU`	点击广告后 14 天内发生的归因销售总额，其中购买的 SKU 与推广的 SKU 相同。
`attributedSales30dSameSKU`	点击广告后 30 天内发生的归因销售总价值，其中购买的 SKU 与推广的 SKU 相同。

广告组报告

这些指标可用于请求以下类型的报告：adGroups

指标	详细信息
`campaignName`	广告活动的唯一名称
`campaignId`	广告活动的唯一数字编号
`adGroupName`	广告组的唯一名称
`adGroupId`	广告组的唯一数字编号
`impressions`	广告总展示量。
`clicks`	广告总点击量。
`cost`	所有点击的总成本。可以除以点击量来得出平均每次点击成本（CPC）。
`attributedConversions1d`	点击广告后 1 天内发生的由此产生的转化事件的数量。
`attributedConversions7d`	点击广告后 7 天内发生的由此产生的转化事件的数量。
`attributedConversions14d`	点击广告后 14 天内发生的由此产生的转化事件的数量。
`attributedConversions30d`	点击广告后 30 天内发生的由此产生的转化事件的数量。
`attributedConversions1dSameSKU`	点击广告后 1 天内发生的归因转化事件数，其中购买的 SKU 与推广的 SKU 相同。
`attributedConversions7dSameSKU`	点击广告后 7 天内发生的归因转化事件数，其中购买的 SKU 与推广的 SKU 相同。
`attributedConversions14dSameSKU`	点击广告后 14 天内发生的归因转化事件数，其中购买的 SKU 与推广的 SKU 相同。
`attributedConversions30dSameSKU`	点击广告后 30 天内发生的归因转化事件数，其中购买的 SKU 与推广的 SKU 相同。
`attributedUnitsOrdered1d`	点击广告后 1 天内发生的归因于广告的已订购商品数量。
`attributedUnitsOrdered7d`	点击广告后 7 天内发生的归因于广告的已订购商品数量。
`attributedUnitsOrdered14d`	点击广告后 14 天内发生的归因于广告的已订购商品数量。
`attributedUnitsOrdered30d`	点击广告后 30 天内发生的归因于广告的已订购商品数量。
`attributedSales1d`	点击广告后 1 天内发生的归因于广告的销量。
`attributedSales7d`	点击广告后 7 天内发生的归因于广告的销量。
`attributedSales14d`	点击广告后 14 天内发生的归因于广告的销量。
`attributedSales30d`	点击广告后 30 天内发生的归因于广告的销量。
`attributedSales1dSameSKU`	点击广告后 1 天内发生的归因销售总价值，其中购买的 SKU 与推广的 SKU 相同。
`attributedSales7dSameSKU`	点击广告后 7 天内发生的归因销售总额，其中购买的 SKU 与推广的 SKU 相同。
`attributedSales14dSameSKU`	点击广告后 14 天内发生的归因销售总额，其中购买的 SKU 与推广的 SKU 相同。
`attributedSales30dSameSKU`	点击广告后 30 天内发生的归因销售总价值，其中购买的 SKU 与推广的 SKU 相同。

关键词报告

这些指标可用于请求以下类型的报告：keywords

指标	详细信息
`campaignName`	广告活动的唯一名称
`campaignId`	广告活动的唯一数字编号
`keywordId`	竞价中使用的关键词编号
`keywordText`	竞价中使用的关键词或词组的文本
`matchType`	竞价中使用的关键词或词组的匹配类型。必须是以下类型之一：`broad`、`phrase` 或 `exact`
`impressions`	广告总展示量。
`clicks`	广告总点击量。
`cost`	所有点击的总成本。可以除以点击量来得出平均每次点击成本（CPC）。
`attributedConversions1d`	点击广告后 1 天内发生的由此产生的转化事件的数量。
`attributedConversions7d`	点击广告后 7 天内发生的由此产生的转化事件的数量。
`attributedConversions14d`	点击广告后 14 天内发生的由此产生的转化事件的数量。
`attributedConversions30d`	点击广告后 30 天内发生的由此产生的转化事件的数量。
`attributedConversions1dSameSKU`	点击广告后 1 天内发生的归因转化事件数，其中购买的 SKU 与推广的 SKU 相同。
`attributedConversions7dSameSKU`	点击广告后 7 天内发生的归因转化事件数，其中购买的 SKU 与推广的 SKU 相同。
`attributedConversions14dSameSKU`	点击广告后 14 天内发生的归因转化事件数，其中购买的 SKU 与推广的 SKU 相同。
`attributedConversions30dSameSKU`	点击广告后 30 天内发生的归因转化事件数，其中购买的 SKU 与推广的 SKU 相同。
`attributedUnitsOrdered1d`	点击广告后 1 天内发生的归因于广告的已订购商品数量。
`attributedUnitsOrdered7d`	点击广告后 7 天内发生的归因于广告的已订购商品数量。
`attributedUnitsOrdered14d`	点击广告后 14 天内发生的归因于广告的已订购商品数量。
`attributedUnitsOrdered30d`	点击广告后 30 天内发生的归因于广告的已订购商品数量。
`attributedSales1d`	点击广告后 1 天内发生的归因于广告的销量。
`attributedSales7d`	点击广告后 7 天内发生的归因于广告的销量。
`attributedSales14d`	点击广告后 14 天内发生的归因于广告的销量。
`attributedSales30d`	点击广告后 30 天内发生的归因于广告的销量。
`attributedSales1dSameSKU`	点击广告后 1 天内发生的归因销售总价值，其中购买的 SKU 与推广的 SKU 相同。
`attributedSales7dSameSKU`	点击广告后 7 天内发生的归因销售总额，其中购买的 SKU 与推广的 SKU 相同。
`attributedSales14dSameSKU`	点击广告后 14 天内发生的归因销售总额，其中购买的 SKU 与推广的 SKU 相同。
`attributedSales30dSameSKU`	点击广告后 30 天内发生的归因销售总价值，其中购买的 SKU 与推广的 SKU 相同。

产品广告报告

这些指标可用于请求以下类型的报告：productAds

指标	详细信息
`campaignName`	广告活动的唯一名称
`campaignId`	广告活动的唯一数字编号
`adGroupName`	广告组的唯一名称
`adGroupId`	广告组的唯一数字编号
`impressions`	广告总展示量。
`clicks`	广告总点击量。
`cost`	所有点击的总成本。可以除以点击量来得出平均每次点击成本（CPC）。
`currency`	维度指标
`asin`	正在进行推广的 ASIN。该指标可同时适用于卖家和供应商。
`sku`	正在进行推广的 SKU。不适用于供应商。
`attributedConversions1d`	点击广告后 1 天内发生的由此产生的转化事件的数量。
`attributedConversions7d`	点击广告后 7 天内发生的由此产生的转化事件的数量。
`attributedConversions14d`	点击广告后 14 天内发生的由此产生的转化事件的数量。
`attributedConversions30d`	点击广告后 30 天内发生的由此产生的转化事件的数量。
`attributedConversions1dSameSKU`	点击广告后 1 天内发生的归因转化事件数，其中购买的 SKU 与推广的 SKU 相同。
`attributedConversions7dSameSKU`	点击广告后 7 天内发生的归因转化事件数，其中购买的 SKU 与推广的 SKU 相同。
`attributedConversions14dSameSKU`	点击广告后 14 天内发生的归因转化事件数，其中购买的 SKU 与推广的 SKU 相同。
`attributedConversions30dSameSKU`	点击广告后 30 天内发生的归因转化事件数，其中购买的 SKU 与推广的 SKU 相同。
`attributedUnitsOrdered1d`	点击广告后 1 天内发生的归因于广告的已订购商品数量。
`attributedUnitsOrdered7d`	点击广告后 7 天内发生的归因于广告的已订购商品数量。
`attributedUnitsOrdered14d`	点击广告后 14 天内发生的归因于广告的已订购商品数量。
`attributedUnitsOrdered30d`	点击广告后 30 天内发生的归因于广告的已订购商品数量。
`attributedSales1d`	点击广告后 1 天内发生的归因于广告的销量。
`attributedSales7d`	点击广告后 7 天内发生的归因于广告的销量。
`attributedSales14d`	点击广告后 14 天内发生的归因于广告的销量。
`attributedSales30d`	点击广告后 30 天内发生的归因于广告的销量。
`attributedSales1dSameSKU`	点击广告后 1 天内发生的归因销售总价值，其中购买的 SKU 与推广的 SKU 相同。
`attributedSales7dSameSKU`	点击广告后 7 天内发生的归因销售总额，其中购买的 SKU 与推广的 SKU 相同。
`attributedSales14dSameSKU`	点击广告后 14 天内发生的归因销售总额，其中购买的 SKU 与推广的 SKU 相同。
`attributedSales30dSameSKU`	点击广告后 30 天内发生的归因销售总价值，其中购买的 SKU 与推广的 SKU 相同。

ASIN 报告

这些指标可用于请求以下类型的报告：asins

指标	详细信息
`campaignName`	广告活动的唯一名称
`campaignId`	广告活动的唯一数字编号
`adGroupName`	广告组的唯一名称
`adGroupId`	广告组的唯一数字编号
`keywordId`	关键词的唯一数字编号
`keywordText`	竞价中使用的关键词或词组
`asin`	推广的唯一 ASIN
`otherAsin`	未推广的 ASIN 的非维度指标
`sku`	推广的唯一 SKU
`currency`	维度指标
`matchType`	以下类型之一：`broad`、`phrase` 或 `exact`
`attributedUnitsOrdered1dOtherSKU`	其他已售商品 ASIN (SKU) 的数量。1 天。
`attributedUnitsOrdered7dOtherSKU`	其他已售商品 ASIN (SKU) 的数量。7 天。
`attributedUnitsOrdered14dOtherSKU`	其他已售商品 ASIN (SKU) 的数量。14 天。
`attributedUnitsOrdered30dOtherSKU`	其他已售商品 ASIN (SKU) 的数量。30 天。
`attributedSales1dOtherSKU`	其他 ASIN (SKU) 的销量。1 天。
`attributedSales7dOtherSKU`	其他 ASIN (SKU) 的销量。7 天。
`attributedSales14dOtherSKU`	其他 ASIN (SKU) 的销量。14 天。
`attributedSales30dOtherSKU`	其他 ASIN (SKU) 的销量。30 天。

品牌推广报告

品牌推广（前身为头条搜索广告）是一种具有不同特征和页面的广告产品广告位选项与商品推广的广告位选项相同。品牌推广报告功能旨在提供仅通过 API 发布的品牌推广活动的信息。创建或修改品牌推广广告和广告活动，请继续使用网页界面。商品推广与品牌推广之间的对象区别在于 campaignType 对象。

报告端点

品牌推广报告数据只能从以下端点获得：

/v1/campaigns/report
/v1/adGroups/report
/v1/keywords/report

品牌推广报告的限制

品牌推广报告数据不能与商品推广数据合并到一份报告。使用 headlineSearch 作为 campaignType 来检索品牌推广活动的报告数据。品牌推广只提供 14 天的数据。不提供 1 天、7 天和 30 天间隔的归因期。对于品牌推广，查询细分或搜索词报告不受支持。

**注意：**在提供的沙盒测试环境中使用了模拟数据，并且除了 14 天之外，可能只有在沙盒中才有其他的报告间隔可用。生产环境要求只提供 14 天的销售报告数据。

品牌推广新报告字段

适用于品牌推广的报告中新增了以下字段：

报告类型	新字段
广告活动	`campaignType`、`campaignBudget`、`campaignBudgetType` 和 `campaignStatus`
广告组	`campaignId`、`campaignName`、`campaignType`、`campaignBudget`、`campaignBudgetType`、`campaignStatus`、`adGroupName`、`adGroupId`
关键词	`campaignId`、`campaignName`、`adGroupId`、`adGroupName`、`campaignBudgetType`、`campaignStatus`、`keywordText` 和 `matchType`

品牌推广实体不包含在快照报告中。要获取有关您的品牌推广活动的报告，请使用下一分段中列出的品牌推广报告指标。这些指标可用于请求以下类型的报告：headlineSearch

*** **注意：**某些指标（如果包含在您的报告请求中）将返回所有品牌推广活动的数据，包括未产生展示量或点击量的广告活动的数据。

品牌推广报告指标

指标	详细信息
`campaignName`***	广告主创建的广告活动名称
`campaignId`	唯一广告活动编号
`campaignType`	必须为：`headlineSearch` 或 `sponsoredProducts`
`campaignStatus`***	广告活动的当前状态
`campaignBudget`***	广告活动预算
`campaignBudgetType`***	必须为 `daily` 或 `lifetime`
`adGroupName`***	唯一广告组名称
`adGroupId`	唯一广告组编号
`keywordText`	竞价中使用的关键词或词组
`matchType`	以下类型之一：`broad`、`phrase` 或 `exact`
`impressions`	广告总展示量。
`clicks`	广告总点击量。
`cost`	所有点击的总成本。可以除以点击量来得出平均每次点击成本（CPC）。
`attributedSales14d`	点击广告后 14 天内归因于广告的销量。
`attributedSales14dSameSKU`	点击广告后 14 天内发生的归因销售总额，其中购买的 SKU 与推广的 SKU 相同。
`attributedConversions14d`	点击广告后 14 天内发生的由此产生的转化事件的数量。
`attributedConversions14dSameSKU`	点击广告后 14 天内发生的归因转化事件数，其中购买的 SKU 与推广的 SKU 相同。

开发人员指南概述

亚马逊广告 API 概览

Developer guides

API reference

报告

操作