报告 API


报告 API

开发者可以使用报告 API 下载销售报表和订阅报表。

要使用开发者控制台 API,您需要创建一个安全配置文件并将该安全配置文件映射到 API。安全配置文件是用于为 API 访问生成访问令牌的机制。

创建安全配置文件

要创建安全配置文件,请执行以下步骤:

  1. 登录您的亚马逊开发者控制台账户。如果您还没有账户,系统将提示您创建一个。
  2. 在主导航中,单击 Apps & Services(应用和服务)。
  3. 单击子菜单中的 API Access(API 访问)。
  4. 单击 API 的名称。

    “API 访问”页面

  5. 单击 Create a new security profile(创建新的安全配置文件)按钮。
  6. 输入新配置文件的安全配置文件名称和安全配置文件描述,然后单击 Save(保存)。
  7. 保存您的客户端 ID 和客户端密钥(从 Web Settings(Web 设置)选项卡),因为您需要此信息才能访问销售报告 API。
    客户端 ID 和客户端密钥

将安全配置文件映射到 API

要将安全配置文件映射到 API,请执行以下步骤:

  1. 返回到 API Access(API 访问)页。
  2. 单击 API 名称以选择 API。
  3. 从下拉列表中选择您的新安全配置文件。
  4. 选择 Attach(附加)以将安全配置文件与此 API 关联。API 名称和附加的安全配置文件将添加到 Security Profile(s) in use(安全配置文件正在使用中)面板。
    客户端 ID 和客户端密钥

您现在可以使用客户端 ID 和客户端密钥请求 Login With Amazon (LWA) 访问令牌。

请求 LWA 访问令牌

借助您的客户端 ID 和客户端密钥,按照以下步骤使用 Login With Amazon API 请求 Login with Amazon 访问令牌:

1.发送令牌请求

将 POST 请求发送到 https://api.amazon.com/auth/o2/token,其中包含以下标头和内容:

  • 标头Content-Type: application/x-www-form-urlencoded
  • 内容
    • client_id: 您在 Create a Security Profile(创建安全配置文件)的步骤 5 中保存的客户端 ID。
    • client_secret: 您在 Create a Security Profile(创建安全配置文件)的步骤 7 中保存的客户端密钥。
    • grant_type: 设置为 client_credentials
    • scope: 将值设置为 appstore::apps:readwrite(对于报告 API,则设置为 adx_reporting::appstore:marketer)。

示例 JSON 内容:

{
    "grant_type": "client_credentials",
    "client_id": "amzn1.application-oa2-client.ae941846cdd745e9a53319f7bb98d435",
    "client_secret": "41d135b2b02ce5f2fbf7643a66477c089fcc1d88d11f69d3e4a6285b917ca35d",    
    "scope": "appstore::apps:readwrite"
}

示例 cURL 请求:

curl -k -X POST -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials&client_id=amzn1.application-oa2-client.5c1462ee102c4a57a5224d0c72118741&client_secret=15d1829ddf4f12d1c5d425e57e5ca081d0f7a63bd94c9e142ff8b20d9de880a4&scope=appstore::apps:readwrite' https://api.amazon.com/auth/O2/token

2.保存响应

响应如下所示:

{"access_token":"Atc|MAEBIBav2tvCbJOA9Jv5sRpej6xY_qzHFuCpbWT-Z94nRqVWVcfmZVNPEhZiet-H3vdQcORqE5pO4fCKEi6kfvzzPtxHIoPIte-ZbKB1XgfjfJnciJHqnbV1UF4WJ_an1g9y7yvWKWJddQ2NLPO-C-Y71BPxJ0KDWOPonn_2qFLY5OJo3BhHKIwNHteQAwkCA9iko8d5tosS7fo3dvS-PFmiBk3OMUmr1AdYtuOnq1RVrX7-C14oWzfACudykTn5cDb48Qy2k6R70__GzHG3fC_-Rfzt7zwhfdBWpwoQk-GbV4Bes457oZwHz89Tj-AAf3DouYQ","scope":"appstore::apps:readwrite","token_type":"bearer","expires_in":3600}
  • access_token: 访问令牌。
  • expires_in: 访问令牌到期之前的秒数。
  • scope: 将为 appstore::apps:readwrite(对于报告 API,则为 adx_reporting::appstore:marketer)。
  • token_type: 将永远为 bearer

3.处理任何错误响应

如果令牌请求导致了错误,则响应消息正文包含以下错误消息之一:

错误消息正文 详情
{"error_description":"Client authentication failed","error":"invalid_client"} 私有密钥无效
{"error_description":"The request has an invalid parameter : scope","error":"invalid_scope"} 范围值无效
{"error_description":"The authorization grant type is not supported by the authorization server","error":"unsupported_grant_type"} 授权类型不正确
{"error_description":"The Content-Type is not supported by the authorization server","error":"invalid_request"} content-type 不受支持

如何使用访问令牌

获得有效的访问令牌后,请向具有 Authorization 标头集的报告 API 发送请求。Authorization 标头的值为 Bearer <YOUR_ACCESS_TOKEN>,其中,<YOUR_ACCESS_TOKEN> 是来自请求 LWA 访问令牌的响应中的 access_token 字段的值。该访问令牌是一个以“Atc|”开头的长字符串。

示例 cURL 请求:

curl -v -k -X GET "<see below for URL format>"   -H  "Authorization: Bearer Atc|MAEBIKfsULrH7jSzvJTV8UmiHWr9M86O3JRmv4t1hqoCBriSMEP5Gsey_FiBxteZ8oxGd6abGuOFga8fwnMhmSD_Sg4MI4odXLPgB2IVs8M1uswjuWjnsMcvehpWvf9tzQT8HTWiBigInJLB8BrMg5J3O02hlTvcF441XxXDXthyj993COJ2u5swOTKjC_dcijiN8amuzrj32rh9Fr3CNgCpoZ0WqXnBhoHUVMYSOBV-owA5rI4-OfysXC71Zbtv1hb8igk"  

当该访问令牌到期时,请按照请求 LWA 访问令牌中的上述过程获取新访问令牌,并开始在您的请求中使用新访问令牌。如果您自上次请求访问令牌以来已超过一个小时,并且您开始收到 403 Forbidden HTTP 错误以及消息“请求未获得授权”,您就知道访问令牌到期了。

报告 API URL

使用以下内容作为发送报告 API 请求的基本 URL:

developer.amazon.com

请求销售/订阅报表 URL

您可以使用报告 API 下载单个销售或订阅报表文件。API 请求将返回一个 URL,您可以使用该 URL 从安全的 S3 存储位置下载文件。

语法

/api/appstore/download/report/sales/<year>/<month>

/api/appstore/download/report/subscription/<year>/<month>

参数

年​份 要下载的报表文件的四位数年份
月份 报表文件的两位数月份值

示例

以下示例显示了如何请求 2018 年 1 月的销售报表。

请求:

curl -v -k -X GET "https://developer.amazon.com/api/appstore/download/report/sales/2018/04" -H "Authorization: Bearer Atc|MQEBIDdrcC586BxhFBdS7FQVS454oUO-fo90H5gUYVMZB1UVsPFoOPLj_zrpkf9BuMrx-PksU_qDJHL-PJ5suEQTigL1tv7A6AKlyoJJaoyzyzKhd0dwWw3LWUGrlxXxW459nJJH66F89GSBolrmlfuNONly8Cbts2Fy_KHI9YwvzwSVcgf_nvefss_H1O8tsvoYpORVuL8IXBrzT7bHxU0Xj5VjiaxDtU6N4oOQafefT8AcdN0IOYnh3Us8uEeeur3_OH473JwO3SjA4NRaS61Aq37UyhvM9pK3ccGOO5JoMkw1V9kDQQVhKiGWfCoTUBlaVkU"

响应:

https://appstore-adx-reporting.s3.amazonaws.com/85923/sales/sales_2018_01.zip?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20180405T060912Z&X-Amz-SignedHeaders=host&X-Amz-Expires=299&X-Amz-Credential=AKIAJMFYXPVLQKTRRB7Q%2F20180405%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=adab43be54631565d330727383341d56989d129e4dea151411cf7a802b9e5e12

错误

如果令牌请求导致了错误,则响应消息正文包含以下错误消息之一:

错误 详情
{"Message":"Request is not authorized."} 访问密钥不正确,或请求的报表超出范围(例如,如果营销员请求付款/代理报表)。
{"Message":"Unable to fetch the request scope for uri = (URL Entered) and verb = GET"} URL 或方法无效。

使用 S3 URL 下载报表

报告 API 将返回一个 S3 URL,您可以用来下载报表。

错误消息:

您可能会从 API 收到以下错误消息之一:

Report Not Available(报表不可用): 您尝试复制一个文件,但具有指定名称的文件在 S3 文件夹中不存在:致命错误: 调用 HeadObject 操作时出错 (403): 禁止访问

User not authorized(用户未授权): 如果您尝试在没有有效访问令牌的情况下使用报告 API。

Server Unavailable(服务器不可用): 如果您发送请求时 API 服务器不可用,或者您尝试下载报表时 S3 存储桶不可用,您将收到 HTTP 404 错误代码。

有关其他信息,请参阅 S3 错误响应

报告 API 常见问题解答

问: 我可以使用 API 检索的最早报表是什么?

可用的最早报表是 2018 年 1 月的。目前尚未提供 2017 年及更早年份的报表。

问: 如何删除安全配置文件?

只有管理员级别的用户才能删除安全配置文件。导航到 Apps&Services(应用和服务)下的 Security Profiles(安全配置文件)选项卡,选择并删除所需的安全配置文件。

问: 为何 cURL 命令具有定义为营销员的范围?

范围是 API 访问的必填字段。营销员被定义为销售报告 API 的默认范围。

问: 访问令牌和预签名 S3 URL 是否能永久使用?

不能,访问令牌的有效期只有 1 小时。预签名 S3 URL 的有效期只有 5 分钟。这些超时时间是出于安全考虑。

问: 安全配置文件客户端 ID 和客户端密钥是否能永久使用?

需要。​在从开发者控制台中删除安全配置文件之日以前可以使用它们。但是,为了保证您的安全,我们强烈建议您至少每 6 个月更新一次与 API 相关的安全配置文件。

问: 我的团队中有 5 个管理员。他们是否都能创建安全配置文件? 如果是,那么如何管理这方面?

是的,所有 5 个管理员都能创建安全配置文件。每个管理员都能查看所有安全配置文件(即使是其他管理员创建的配置文件)

CSV 文件格式

CSV 文件是具有 .csv 文件扩展名的文本文件。CSV 文件必须使用 UTF-8 编码,以支持本地化字符串。

销售报表字段

CSV 文件是具有 .csv 文件扩展名的文本文件。CSV 文件必须使用 UTF-8 编码,以支持本地化字符串。

CSV 文件包含一个标题行(它显示列标题)。文件中的每个后续行包含一个报表项目的信息。“Invoice ID”(发票 ID)字段为报表中的每个行项目定义了一个唯一标识符。

下表介绍了 CSV 文件中的每个条目(行)的字段:

字段 类型 描述 示例
市场 字符串 亚马逊市场 Amazon.com
国家/地区代码 字符串 交易来源地的标准两位数 ISO 国家/地区代码。请参阅此列表 US
发票 ID 字符串 发票的唯一 ID。此字段对 2017 年及更早的汇总数据设置为 NA 8dd921637-b092f385a7ee4-62c6494b3ed702f113
交易 ID 整数 与此交易关联的唯一 ID。此字段对 2017 年及更早的汇总数据设置为 NA,因为销售信息包括给定日内的所有交易 21854260140446
交易时间 字符串 交易的日期和时间。格式为 MM/DD/YY HH:MM:SS XST,00-23 为小时的范围。XST 是与交易的市场关联的时区。对于 2017 年及更早的数据,此字段表示销售日期。 05/21/18 14:39 PST
交易类型 字符串 交易类型为 Charge(收费)或 Refund(退款) 收费
调整 是或否 如果交易是一个调整,此字段将设置为 Yes(是)。对于 2017 年及更早的数据,如果交易类型为 Refund(退款),此字段将显示 null 值。
供应商 SKU 字符串 由多达 150 个字符组成的字符串,其中可包含字符 a-z、A-Z、0-9、下划线、句点和短划线。该 SKU 区分大小写。 com.gamevendor.fungame
名称 字符串 应用或游戏的名称。 Smashemup Truck Game
项目名称 字符串 应用、游戏、订阅、应用内项目或游戏内项目的名称。 Smashemup Truck Game
项目类型 字符串 项目的类型。值包括 Subscription(订阅)、App(应用)、In-App(应用内)、Game(游戏)或 In-Game(游戏内) 应用程序
应用内订阅期限 字符串 订阅的期限。该期限可以是每周、每两周、每月、每两个月、每季度、每半年或每年。仅当项目类型为“Subscription”(订阅)时,此字段才适用。
此字段不适用于 Twitch。
每周
应用内订阅状态 字符串 状态可以是 Trial(试用)或 Paid(付费)。仅当项目类型为“Subscription”(订阅)时,此字段才适用。
此字段不适用于 Twitch。
试用
单位数 整数 此交易中包含的单位数。 1
使用时间 字符串 Underground 应用的使用时间(以秒为单位)。此字段仅适用于 Appstore Underground 产品。要计算单位数,请将使用时间除以 60。例如,1200 的使用时间是 20 个单位。
此字段不适用于 Twitch。
1200
市场货币 字符串 市场决定了交易的货币。请参阅市场时区表 美元
销售价格 市场货币 客户在任何折扣后看到的销售价格(不包括销售税)。对于 Underground 应用,销售价格表示基于应用使用分钟数的收入。销售额和收入对于 Underground 应用是相同的。对于调整和退款,将显示原始项目的销售价格。实际调整金额或退款金额可能与销售价格不同(如部分退款)。 4.99
估计收入 市场货币 从此交易中扣除亚马逊版税后的估算收入。对于调整和退款,收入将基于调整金额或退款金额来显示。 3.49

注释

  • 销售数据每 24 小时更新一次。如果要自动执行数据拉取,则建议每 24 小时运行一次脚本以获取最新信息。请注意,报告的信息可能有长达 48 小时的延迟。
  • API 每秒最多支持 3 个请求。更频繁地进行 API 调用可能导致性能下降。
  • 收入在此文件中估计。它可能与您的月底收入报表不完全相符,该报表可能包含此处未捕获的额外调整。
  • 所有调整都显示在进行调整的月份,而不显示在原始交易发生的月份。
  • 测试 ASIN 对“Title”(标题)和“Item Name”(项目名称)显示 null 值。这个已知问题将在未来的版本中得到修复。

订阅报表字段

CSV 文件是具有 .csv 文件扩展名的文本文件。CSV 文件必须使用 UTF-8 编码,以支持本地化字符串。

CSV 文件包含一个标题行(它显示列标题)。文件中的每个后续行包含一个报表项目的信息。

下表介绍了文件中的每个条目(行)的字段。请注意,亚马逊市场、供应商 SKU、订阅名称和订阅持续时间是您在开发者控制台中配置此订阅时输入的值:

字段 描述 示例
日期 此记录的订阅数据是在此日期收集的。 12/29/18
市场 与此记录中的数据关联的亚马逊市场。 Amazon.com
应用名称 订阅针对具有此名称的应用。 My Test App
ASIN 订阅的亚马逊标准识别码 (ASIN)。 C00006M4PF
供应商 SKU 订阅的 SKU。 com.test.monthly
订阅名称 订阅的名称。 测试月度订阅
订阅持续时间 订阅的持续时间。 每月
订阅类型 订阅类型具有值 trial(试用)或 paid(付费)。 付费
活跃 指定日结束时 (11:59 PM UTC) 的活跃订阅总数。 7261
已开始 在指定日发起的订阅数 163
已结束 在指定日取消或结束而未续订的订阅数。 163
已退款 在指定日退款的订阅数。 163

市场信息

下表显示了每个市场的国家/地区缩写和货币类型。

国家/地区
缩写
​币种
缩写
​币种 市场
AU AUD 澳元 Amazon.com.au
BR BRL 巴西雷亚尔 Amazon.com.br
CA CAN 加拿大元 Amazon.ca
CN CHY 人民币 Amazon.cn
DE EUR 欧元 Amazon.de
ES EUR 欧元 Amazon.es
FR EUR 欧元 Amazon.fr
GB GBP 英镑 Amazon.co.uk
IN INR 印度卢比 Amazon.in
IT EUR 欧元 Amazon.it
JP JPY 日元 Amazon.co.jp
US 美元 美元 Amazon.com

API 数据安全

您可以通过报告 API 访问的所有数据均为亚马逊机密,且仅供开发者使用。

如果您向受信任的第三方授予 API 访问权限(以支持您的日常运营),则表示您同意共享这些信息且风险自担。亚马逊对共享此信息造成的任何损失或损害不承担任何责任。

如果您决定与第三方共享您的 API 访问权限,请遵循以下准则:

  1. 为第三方创建一个专用安全配置文件。
  2. 在安全配置文件名称中包含第三方企业名称(如 ReportingAPI_<您的公司名称>_<第三方名称>)。
  3. 在安全配置文件说明字段中,清楚地说明将使用安全配置文件的人员。

为了保护您自己,我们强烈建议您每六个月更新一次安全配置文件(与销售报告 API 关联的所有安全配置文件)。