Amazon Selling Partner API - spapi.cyou

Reports API v2020-09-04 用例指南

亚马逊SPAPI

# 什么是报告API?

通过报告的销售伙伴API(报告API)，你可以建立应用程序，使卖家能够从亚马逊获得报告，帮助他们管理他们的销售业务.有各种用例的报告，如监控库存，跟踪订单履行，获得税务信息，跟踪退货和卖家业绩，用亚马逊的Fulfillment管理销售业务，等等.见[报告API参考](https: //spapi.cyou/zh/references/reports-api-v2020-09-01-reference.html)了解关于Reports API操作以及相关数据类型和模式的详细信息.参见reportType values (opens new window)了解可用报告类型.

生成报表的两个主要工作流程是请求一个报表和安排一个报表.

请求报告

你可以使用createReport操作按需请求任何可用的报告类型.参见Tutorial请求和检索一个报告以获得指导.

安排一个报告

您可以使用createReportSchedule操作让亚马逊按计划自动提交报告请求.参见Tutorial安排和检索报告了解安排报告的说明.

# Terminology

  • 密码区块链.密码区块链是一种使用区块密码来提供保密性或真实性等信息安全的算法.该算法使用一个初始化向量和一个密钥来加密数据.

  • S3 pre-signed URL. 一个AWS S3桶的URL，你可以在没有AWS安全凭证或权限的情况下从该桶下载一个对象.

# Tutorial: 请求和检索一个报告

下面是请求报告的高-级步骤

1.调用createReport (opens new window)操作，指定你所请求的报告类型和市场，以及任何你想要的可选参数.

亚马逊收到报告请求.如果操作成功，响应包括一个reportId值.

1.定期调用getReport (opens new window)操作，传递上一步的reportId值，直到响应中的processingStatus值表明处理已经结束.当processingStatus等于CANCELLED、DONE或FATAL时，处理就已经结束.此时，如果有报告数据可用，响应中包括一个reportDocumentId值

1.调用getReportDocument (opens new window)操作，传递上一步的reportDocumentId值.

亚马逊会返回一个预先签名的URL，用于报告文件的位置，以及加密的细节.

1.下载并解密报告.

# Prerequisites

要完成本教程，你将需要

要使用本指南中的示例代码，需要安装一个有效的Java开发工具包(JDK)，包括javax.crypto库.

步骤

Step 1.请求报告

Step 2.确认报告处理已经完成

第3步.检索报告

# 步骤1.请求一份报告

通过指定你所要求的报告类型和市场，以及任何可选择的参数来要求一份报告.

-调用createReport (opens new window)操作，传递以下参数

请求主体

NameDescriptionRequired
reportOptionsAdditional information passed to reports. This varies by report type.

Type: ReportOptions

No
reportTypeThe report type. For more information, see reportType values.

Type: string

Yes
dataStartTime日期和时间范围的开始，采用ISO 8601日期时间格式，用于选择要报告的数据.默认为now.该值必须在当前日期和时间之前或相等.并非所有报告类型都使用这个.

类型string (date-time)

No
dataEndTime日期和时间范围的结束，采用ISO 8601日期时间格式，用于选择要报告的数据.默认为now.该值必须在当前日期和时间之前或相等.并非所有报告类型都使用这个.

类型string (date-time)

No
marketplaceIdsA list of marketplace identifiers.报告文档的内容将包含所有指定市场的数据，除非报告类型另有说明.

Type: < string > array

Yes

# Request example:

POST https://sellingpartnerapi-na.amazon.com/reports/2020-09-04/reports
{
  "报告类型": "get_merchant_listings_all_data",
  "dataStartTime": "2019-12-10T20:11:24.000Z",
  "marketplaceIds": [
    "a1pa6795ukmfr9",
    "atvpdkikx0der"
  ]
}
1
2
3
4
5
6
7
8
9

响应

一个成功的响应包括以下属性

NameDescription
reportId报告的识别码.这个识别码只有在与卖方ID.

Type相结合时才是唯一的string

# Response example:

{
  "payload":
  {
    "reportId": "ID323"
  }
}
1
2
3
4
5
6

# 第2步.确认报告处理已经完成

在你调用createReport操作后，亚马逊收到请求并开始处理报告.然后你必须确认处理已经完成，然后再继续.

-定期调用getReport (opens new window)操作，传递上一步的reportId值，直到响应中的processingStatus值表明处理已经结束.当processingStatus等于CANCELLED、DONE或FATAL时，处理就已经结束.此时，如果有可用的报告数据，响应包括一个reportDocumentId值.

下面是确认处理已经结束的处理状态值

  • CANCELLED - 报告被取消了. 有两种方法可以取消报告：在报告开始处理之前提出明确的取消请求，或者在没有数据返回时自动取消.

  • DONE - 该报告已完成处理，并且有一个报告的DocumentId可用.

  • FATAL - 报告由于致命的错误而被中止，并且可能有一个reportDocumentId. 如果存在，由reportDocumentId代表的报告可以解释为什么报告处理结束.

下面的处理状态值表示处理没有_结束，你应该继续调用getReport操作，直到该操作返回的处理状态为CANCELLED、DONE或FATAL.

  • IN_PROGRESS - 该报告正在处理中.

  • IN_QUEUE - 该报告还没有开始处理. 它可能在等待另一个IN_PROGRESS报告.

注意getReport操作只为过去90天内创建的按需或预定报告请求提供信息.

路径参数

NameDescriptionRequired
reportIdThe 报告的标识符.该标识符只有在与卖方ID.

类型相结合时才是唯一的string

Yes

# Request example:

GET https://sellingpartnerapi-na.amazon.com/reports/2020-09-04/reports/ID323
1

响应

一个成功的响应包括以下内容

NameDescriptionSchema
payloadThe getReport操作的有效载荷.Report

# Response example

{
  "payload": {
    "reportId": "ID323",
    "报告类型": "get_merchant_listings_all_data",
    "dataStartTime": "2019-12-11T13:47:20.677Z",
    "dataEndTime": "2019-12-12T13:47:20.677Z",
    "createdTime": "2019-12-10T13:47:20.677Z",
    "processingStatus": "DONE",
    "processingStartTime": "2019-12-10T13:47:20.677Z",
    "processingEndTime": "2019-12-12T13:47:20.677Z",
    "reportDocumentId": "DOC-b8b0-4226-b4b9-0ee058ea5760"
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13

# 步骤3. 检索报告

检索报告，请参见如何检索报告.

# Tutorial: 安排和检索报告

你可以使用createReportSchedule操作来安排报告的请求，以便定期提交. 使用period枚举来指定时间段. 要确定哪些报告可以被安排，请查看Selling Partner API文档中的reportType值.

下面是调度和检索报告的高-级步骤

1.调用createReportSchedule (opens new window)操作来创建一个定期提交报告请求的时间表.指定报告类型、marketplaceIds和period值以及任何可选的参数.对于报告类型值，请参见报告类型值 (opens new window).对于period值，请参见period枚举 (opens new window).

注意如果一个具有相同报告类型和市场ID的报告计划已经存在，它将被取消，并被这个计划取代.否则将创建一个新的报告计划.

1.定期调用getReports (opens new window)操作，其间隔时间与你在上一步配置的时间表相似.

如果对getReports操作的调用成功，响应包含一个报告信息的数组，包括reportDocumentId值，如果报告数据可用的话.

注意getReports操作只提供在过去90天内创建的按需或预定报告请求的信息.

  1. 对于每一个报告的文件名

    1. Call the getReportDocument (opens new window) operation, passing the reportDocumentId value.

      亚马逊会返回一个预先签名的URL，用于报告文件的位置，以及加密的细节.

    1.下载并解密报告.

# Prerequisites

要完成本教程，你需要

-要安排的报告类型.参见报告类型值 (opens new window)，了解可用的报告类型列表.

要使用本指南中的示例代码，需要安装一个有效的Java开发工具包(JDK)，包括javax.crypto库.

步骤

步骤1：为报告请求创建一个时间表

步骤2：定期检索有关预定报告的信息的信息

第3步：检索报告

# 第1步：为报告请求创建一个时间表

调用createReportSchedule操作来创建一个提交报告请求的时间表，指定reportType、markeplaceIds和period值以及任何可选的参数.参见reportType值 (opens new window)，了解可用报告类型的列表.

主体参数

NameDescriptionRequired
reportType

The report type.

Type: string

Yes
marketplaceIds

报告时间表的市场标识符的列表.

Type< string > array

Yes
reportOptions

传递给报告的额外信息.这因报告类型而异.

TypeReportOptions

No
period

一组预定义的ISO 8601周期之一，指定应多长时间创建一份报告.

Type: enum (Period)

Yes
nextReportCreationTime

The 日程表将创建下一份报告的日期和时间ISO 8601日期时间格式.

类型string (date-time)

No

# Request example:

POST https://sellingpartnerapi-na.amazon.com/reports/2020-09-04/schedules
{
  "报告类型": "get_xml_browse_tree_data",
  "周期": "P2D",
  "marketplaceIds":["ATVPDKIKX0DER"]
}
1
2
3
4
5
6

响应

一个成功的响应包括以下内容

NameDescriptionSchema
payload

The createReportSchedule操作的有效载荷.

CreateReportScheduleResult

# Response example:

{
  "payload":
  {
    "reportScheduleId": "ID323"
  }
}
1
2
3
4
5
6

# 步骤2：定期检索有关预定报告的信息

定期调用getReports操作，其间隔时间与你配置的时间表相似. 你要尽量安排这些调用的时间，使其发生在预定的报告可能已经完成之后.

  1. 定期调用getReports (opens new window)操作，以检索有关预定报告的信息，传递以下参数

查询参数

NameDescriptionRequired
reportTypes

A list of report types used to filter reports. 当提供reportTypes的时候其他过滤参数(processingStatuses, marketplaceIds, createdSince, createdUntil)和pageSize也可以提供.

报告类型或nextToken是必须的.

类型< string > array

No
processingStatuses

一个用于过滤报告的处理状态列表.

Type< enum (ProcessingStatuses) > array

No
marketplaceIds

A list of marketplace identifiers used to filter reports. 返回的报告将至少与你指定的一个市场相匹配.

Type: < string > array

No
pageSize

在一次调用中要返回的最大报告数.

TypeInteger

No
createdSince

响应中包含的最早的报告创建日期和时间，ISO 8601日期时间格式.默认为90天前.报告最多可保留90天.

Type: string (date-time)

No
createdUntil

报告的最新创建日期和时间，以ISO 8601日期时间格式，包含在响应中.默认是现在.

类型string (date-time)

No
nextToken

在对你上一个请求的响应中返回的一个字符串令牌.当结果的数量超过指定的pageSize值时返回nextToken.为了得到下一页的结果调用getReports操作，并将此令牌作为唯一的参数.指定nextToken与任何其他参数将导致请求失败.

类型string

No

# Request example:

GET https://sellingpartnerapi-na.amazon.com/reports/2020-09-04/reports?reportTypes=GET_XML_BROWSE_TREE_DATA
1

响应

一个成功的响应包括以下内容

名称 描述
payload

getReports操作的有效载荷.

 ReportList
nextToken

当结果的数量超过pageSize时返回.要获得下一页的结果，请调用getReports，将此标记作为唯一参数.

 字符串

响应中的有效载荷数组包含一个报告对象(see Report (opens new window)，用于每个被处理的报告，每个报告对象包含reportDocumentId.

注意关于按需报告和计划报告的信息都会被返回. 要识别计划报告，请在响应中的报告对象中查找是否存在报告日程表ID_ 该报告日程表ID表示哪个日程表提交了这个报告请求.

  1. 对于每一个报告文档Id，保存报告文档Id，并转到步骤3来检索报告.

# Response example:

{
  "nextToken": "VGhpcyB0b2tlbiBpcyBvcGFxdWUgYW5kIGludGVudGlvbmFsbHkgb2JmdXNjYXRlZA==" 
  "payload": [
    {
      "报告类型": "get_xml_browse_tree_data",
      "processingEndTime": "2020-09-23T22:52:59+00:00",
      "processingStatus": "DONE",
      "marketplaceIds": ["ATVPDKIKX0DER"],
      "reportDocumentId": "FOO_eae0a7b7-6c33-4191-ad1a-f31ac1ae0ce3",
      "reportId": "ID222",
      "dataEndTime": "2020-09-23T22:52:24+00:00",
      "createdTime": "2020-09-23T22:52:43+00:00",
      "processingStartTime": "2020-09-23T22:52:49+00:00",
      "reportScheduleId": "ID323"
      "dataStartTime": "2020-09-23T22:37:24+00:00"
    }
  ]
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 第3步：检索报告

检索报告，请参见如何检索报告.

# 如何取回一份报告

首先获得检索报告文件所需的信息，然后下载并解密报告，从而获得你的报告.

步骤

第1步.获取检索报告所需的信息

步骤2.下载并解密报告

# 步骤1.获取检索报告所需的信息

调用getReportDocument操作来获取检索报告文件内容所需的信息.这包括报告文件的预-签名URL以及解密文件内容所需的信息.

  1. Call the getReportDocument (opens new window) operation, passing the following parameter:

路径参数

NameDescriptionRequired
reportDocumentIdThe identifier for the report document.

Type: string

Yes

# Request example:

GET https://sellingpartnerapi-na.amazon.com/reports/2020-09-04/documents/DOC-b8b0-4226-b4b9-0ee058ea5760
1

响应

一个成功的响应包括以下元素

NameDescription
reportDocumentIdThe identifier for the report document. 这个标识符只有在与卖方ID结合时才是唯一的.
url

报告文件的预-签名URL.这个URL在5分钟后过期.

类型string

encryptionDetails报告文件内容解密所需的加密细节.

Type: ReportDocumentEncryptionDetails

compressionAlgorithmIf present, the report document contents have been compressed with the provided algorithm.

Type: enum (CompressionAlgorithm)

# Response example:

{
  "payload": {
    "reportDocumentId": "DOC-b8b0-4226-b4b9-0ee058ea5760",
    "url": "https://d34o8swod1owfl.cloudfront.net/SampleResult%2BKey%3DSample%2BINITVEC%3D58+fa+bf+a7+08+11+95+0f+c1+a8+c6+e0+d5+6f+ae+c8",
    "encryptionDetails": {
      "标准": "AES",
      "initializationVector": "58 fa bf a7 08 11 95 0f c1 a8 c6 e0 d5 6f ae c8",
      "key": "样本"
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11

2.保存key, initializationVector, url, and compressionAlgorithm (optional property)供步骤2.使用

# 步骤2.下载并解密报告

你将需要使用上一步返回的信息下载和解密报告.下面的示例代码以及销售伙伴API文档助手 (opens new window)中提供的类可以提供帮助.你也可以使用示例代码和SP-API文档助手代码中展示的原则来指导你用其他编程语言构建应用程序.

1.使用以下内容作为示例代码的输入

  • 上一步的key, initializationVector, url, 和可选的compressionAlgorithm值是DownloadExample类的key, initializationVector, url, 和compressionAlgorithm方法的参数.

注意始终保持静态加密是开发者的责任. 未加密的报告内容绝对不能存储在磁盘上，即使是暂时的，因为报告可能包含敏感信息. 我们提供的示例代码演示了这个原则.

# 示例代码(Java)

// DownloadExample.java
import java.io.BufferedReader;
import java.io.IOException;

import com.amazon.spapi.documents.CompressionAlgorithm;
import com.amazon.spapi.documents.DownloadBundle;
import com.amazon.spapi.documents.DownloadHelper;
import com.amazon.spapi.documents.DownloadSpecification;
import com.amazon.spapi.documents.exception.CryptoException;
import com.amazon.spapi.documents.exception.HttpResponseException;
import com.amazon.spapi.documents.exception.MissingCharsetException;
import com.amazon.spapi.documents.impl.AESCryptoStreamFactory;

public class DownloadExample {
  final DownloadHelper downloadHelper = new DownloadHelper.Builder().build();

  // 密钥、initializationVector、url和compressionAlgorithm都是从getReportDocument操作的响应中获得的
  // getReportDocument操作的响应中获得.
  public void downloadAndDecrypt(String key, String initializationVector, String url, String compressionAlgorithm) {
    AESCryptoStreamFactory aesCryptoStreamFactory =
      new AESCryptoStreamFactory.Builder(key, initializationVector).build();

    DownloadSpecification downloadSpec = new DownloadSpecification.Builder(aesCryptoStreamFactory, url)
      .withCompressionAlgorithm(CompressionAlgorithm.fromEquivalent(compressionAlgorithm))
      .build();
    
    try (DownloadBundle downloadBundle = downloadHelper.download(downloadSpec)) {
      // 这个例子假设下载的文件在内容类型上有一个charset，e.g.
      // text/plain; charset=UTF-8
      try (BufferedReader reader = downloadBundle.newBufferedReader()) {
        字符串行
        do {
          line = reader.readLine();
          // 处理已解密的行.
        } while (line != null);
      }
    }
    catch (CryptoException | HttpResponseException | IOException | MissingCharsetException e) {
        //在这里处理异常.
    }
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

# 最佳实践

# 期待报告的变化

亚马逊会定期向报告添加新的字段和字段值.要确保你在应用程序中构建的任何报告解析器能够优雅地处理这些类型的报告更新.

# 不要依赖文档ID结构

你不应该依赖文档标识符的格式和结构.格式和结构是可以改变的.

Reports API v2021-06-30