对接亚马逊 SP-API(Amazon Selling Partner API) 第五章：Reports 模块

官网介绍：https://github.com/amzn/selling-partner-api-docs/blob/main/guides/en-US/use-case-guides/reports-api-use-case-guide/reports-api-use-case-guide-2020-09-04.md#tutorial-request-and-retrieve-a-report

简单来说就是：

1. createReport() 获取 reportId

2. 通过 reportId 调用 getReport() 检查报告状态。DONE 的情况会返回 reportDocumentId

3. 通过 reportDocumentId 调用 getReportDocument() 获取下载 url 和文件解码

3. HTTP 对接

官方案例（Java & C #）

https://docs.aws.amazon.com/AmazonS3/latest/API/sig-v4-examples-using-sdks.html#sig-v4-examples-using-sdk-java

AWSS3SigV4JavaSamples

这个 demo 对拼接 http 请求非常好用。

Step 1. Request a report

3.1.1. Headers

Authorization: AWS4-HMAC-SHA256 Credential=ABCXXXXXXX/20210423/us-east-1/execute-api/aws4_request, SignedHeaders=host;user-agent;x-amz-access-token, Signature=5d672d79c15b13162d9279b0855cfba6789a8edb4c82c400e06b5924aEXAMPLE
user-agent: My Selling Tool/2.0 (Language=Java/1.8.0.221;Platform=Windows/10)
x-amz-access-token=Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSREXAMPLE
x-amz-date: 20210423T123400Z

Name	Description
x-amz-date	The date and time of your request.
user-agent	Your application name and version number, platform, and programming language. These help Amazon diagnose and fix problems you might encounter with the service. See Include a User-Agent header in all requests. 应用程序名称和版本号、平台和编程语言

Name

Description

x-amz-date

The date and time of your request.

user-agent

Your application name and version number, platform, and programming language. These help Amazon diagnose and fix problems you might encounter with the service. See Include a User-Agent header in all requests.

应用程序名称和版本号、平台和编程语言

3.1.1.1. x-amz-access-token

access token 有效期为一个小时。我们可以通过 refresh token 获取最新的 access token。

cURL

curl --location --request POST 'https://api.amazon.com/auth/o2/token' \
--header 'Content-Type: application/x-www-form-urlencoded;charset=UTF-8' \
--data-raw 'grant_type=refresh_token&refresh_token={refresh_token}&client_id={CLIENT_ID}&client_secret={CLIENT_SECRET}'

3.1.1.2. x-amz-security-token

使用 AWS Security Token Service (AWS STS) 提供的临时安全证书对请求进行签名。其过程与使用长期凭证相同，但在您添加签名信息到查询字符串时，您必须为安全令牌添加额外的查询参数。参数名称为 X-Amz-Security-Token，参数值为 URI 编码的会话令牌（在您获取临时安全凭证时从 AWS STS 收到的字符串）。

3.1.1.3. Authorization

对接亚马逊 SP-API(Selling Partner API) 第四章：签名

3.1.2. Body

Name	Description	Required
reportOptions	Additional information passed to reports. This varies by report type. Type: ReportOptions	No
reportType	The report type. For more information, see reportType values. Type: string	Yes
dataStartTime	The start of a date and time range, in ISO 8601 date time format, used for selecting the data to report. The default is now. The value must be prior to or equal to the current date and time. Not all report types make use of this. Type: string (date-time)	No
dataEndTime	The end of a date and time range, in ISO 8601 date time format, used for selecting the data to report. The default is now. The value must be prior to or equal to the current date and time. Not all report types make use of this. Type: string (date-time)	No
marketplaceIds	A list of marketplace identifiers. The report document's contents will contain data for all of the specified marketplaces, unless the report type indicates otherwise. Type: < string > array	Yes

{
"reportType": "GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL",
"dataStartTime": "2021-04-20T00:00:00.000Z",
"marketplaceIds": [
"A1PA6795UKMFR9",
"ATVPDKIKX0DER"
]
}

3.1.3. 完整请求 URL

cUrl

curl --location --request POST 'https://sellingpartnerapi-na.amazon.com/reports/2020-09-04/reports' \
--header 'Authorization: Authorization' \
--header 'user-agent: My Selling Tool/2.0 (Language=Java/1.8.0.221;Platform=Windows/10)' \
--header 'x-amz-access-token: Atza|XXX' \
--header 'x-amz-date: 20210423T123400' \
--header 'Content-Type: application/json' \
--data-raw '{
  "reportType": "GET_FLAT_FILE_ALL_ORDERS_DATA_BY_ORDER_DATE_GENERAL",
  "dataStartTime": "2021-04-20T00:00:00.000Z",
  "marketplaceIds": [
    "A1PA6795UKMFR9",
    "ATVPDKIKX0DER"
  ]
}'

Step 2. Confirm report processing has completed

Step 3. Retrieve the report

4. SDK 对接

前提概要：

使用 sellers-api 模块的 getMarketplaceParticipations()，获取帐号所启用的站点（因为reports-api 的 marketplace 是必填项）。否则会提示站点不可用。

4.1. 下载对应的 SDK

对接亚马逊 SP-API(Selling Partner API) 第三章：对接 SDK

4.1.1. model.json

暂时使用 2020-09-04 版本。

4.1.2. 引入 aa 库

4.1.3. 引入 documents-helper 库

官方提供了 Java 解压的 demo（DownloadExample.java）。不需要的可以不引入 documents-helper 库。

Bug 1. 打包的时候会发现 test 包下面报错。

解决方法

打包的时候把测试类跳过就好。（解决不了出问题，就把出问题的地方解决掉）

4.2. 创建 getReportsApi()

public static ReportsApi getReportsApi() {
        AWSAuthenticationCredentials awsAuthenticationCredentials;
        AWSAuthenticationCredentialsProvider awsAuthenticationCredentialsProvider;
        LWAAuthorizationCredentials lwaAuthorizationCredentials;

        awsAuthenticationCredentials = AWSAuthenticationCredentials.builder()
                .accessKeyId(USER_ACCESS_KEY_ID)
                .secretKey(USER_SECRET_ACCESS_KEY)
                .region(REGION)
                .build();

        awsAuthenticationCredentialsProvider = AWSAuthenticationCredentialsProvider.builder()
                .roleArn(ROLE_ARN)
                .roleSessionName(ROLE_SESSION_NAME)
                .build();

        lwaAuthorizationCredentials = LWAAuthorizationCredentials.builder()
                .clientId(APP_CLIENT_ID)
                .clientSecret(APP_CLIENT_SECRET)
                .refreshToken(REFRESH_TOKEN)
                .endpoint(LWA_ENDPOINT)
                .build();

        ReportsApi reportsApi = new ReportsApi.Builder()
                .awsAuthenticationCredentials(awsAuthenticationCredentials)
                .lwaAuthorizationCredentials(lwaAuthorizationCredentials)
                .awsAuthenticationCredentialsProvider(awsAuthenticationCredentialsProvider)
                .endpoint(REGION_ENDPOINT)
                .build();

        if (null == reportsApi) {
            throw new RuntimeException();
        }
        return reportsApi;
    }

4.3. 创建报告（获取 reportId）

请求限制：

最大请求为10个点数，以每秒 0.0222 个恢复，即 45 秒恢复一个请求点数。

对比 MWS 最大限额小了，恢复速度快了。

4.3. 1. Bad Request

错误提示不太友好。这个我查了半天才发现 Body 中 Marketplace ID 是个必填项。

Bug 1. One or more required parameters missing

{
  "errors": [
    {
      "code": "InvalidInput",
      "message": "One or more required parameters missing",
      "details": "marketplaceIds;"
    }
  ]
}

解决办法

参考文档把必填项补充进去就好了。

Bug 2. Report rejected for this client. Some of the marketplaces are not allowed for this Report

{
	"errors": [{
		"code": "InvalidInput",
		"message": "Report rejected for this client. Some of the marketplaces are not allowed for this Report",
		"details": ""
	}]
}

解决办法

1. 确定自己的 marketplaceId 没有填错。

2. 去文档找这个 report type 是否支持当前站点。

问题倒是找到了。但是其他北美的帐号可以正常申请这个类型.. 很迷 - -。

最后在 Github issues 发现答案。

https://github.com/amzn/selling-partner-api-docs/issues/911

4.3.2. io.swagger.client.ApiException: Forbidden

备注：2021-06-30 之前，SP-API 麻烦使用 2020-09-04 这个版本。

Bug 1. 无效帐号

我们首先确定一点，这个帐号是有效的。登录亚马逊后台，你会发现首页就显示这个帐号挂掉了。

备注：当这个帐号被冻结了，我们依然是可以正常进入后台且可以拿到 refresh_token 的，也可以通过 refresh_token 拿到 access_token。只是无法再进行下一步的 Api 操作了。

Bug 2. 传参错误

解决办法

找到你报错的地方，打上断点。在异常的 Message 有写明是因为什么报错。

Bug 3. 枚举不对或者不支持的区域。

{
  "errors": [
    {
      "code": "Unauthorized",
      "message": "Access to the resource is forbidden",
      "details": ""
    }
  ]
}

由于我请求的报告是 Amazon Fulfilled Shipments。并且确信授权了这个模块。所以权限是没问题的。

枚举类：因为我发现 MWS 和 SP-API 的枚举类都是一样的，只是前后的 _ 取消了。所以我理所当然的使用了：~~GET_AMAZON_FULFILLED_SHIPMENTS_DATA~~

然后跑去官网查看。你就会发现，正确的枚举类长这样：GET_AMAZON_FULFILLED_SHIPMENTS_DATA_GENERAL

官方解释

4.4. 检查报告申请状态（获取 reportDocumentId）

Processing Statuses

Bug 1. CANCELLED

请求了大量的报告你会发现，很多报告会出现 Cancelled 状态。以我多年的 MWS 经验，我断定是我发送请求太频繁了导致的。然后我就不断的重新发起请求.. 不断的 Cancelled。

最后我跑去后台查，发现没数据也会显示 Cancelled。这就很尴尬了。

去官方文档查询，你会发现

大概的意思是：有两种可能会出现 Cancelled 状态，1. 自己取消。2. 没数据。

我还是怀念 MWS 的 _DONE_NO_DATA_，简单明了。而且从 MWS 升级过来，有好多坑都是经验式 Bug..

（猜想）状态变更：SP-API 请求数据太频繁的报告状态是 FATAL。

4.5. 获取下载链接

4.6. 使用 DownloadExample.java 下载 report

Bug 1. java.lang.NoClassDefFoundError: com/google/common/base/Preconditions

解决方法

        <!-- https://mvnrepository.com/artifact/com.google.guava/guava -->
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>30.1.1-jre</version>
        </dependency>

Bug 2. java.lang.NoClassDefFoundError: org/apache/commons/io/IOUtils

解决方法

        <!-- https://mvnrepository.com/artifact/commons-io/commons-io -->
        <dependency>
            <groupId>commons-io</groupId>
            <artifactId>commons-io</artifactId>
            <version>2.6</version>
        </dependency>

Bug 3. java.lang.IllegalArgumentException: No enum constant com.amazon.spapi.documents.CompressionAlgorithm.AES

CompressionAlgorithm.java 还真没有.. 就很尴尬了..

解决办法
构建 DownloadSpecification 的时候，不加这个算法。

Bug 3.1. 乱码（峰兄提供）

情景：

某些报告下载下来是正常的，某些报告是乱码。

原因：

1）、正常报告 Response：

2）、乱码报告 Response：

导致乱码的原因是我们在 BUG 3 中把算法去掉了。而数据量如果比较大的情况，亚马逊会返回一个 GZIP 文件，而我们又没解析。

解决办法

Bug 4. com.amazon.spapi.documents.exception.CryptoException: java.security.InvalidKeyException: Illegal key size

原因：JAVA默认支持AES 128 Bit 的key, 如果你计划使用 192 Bit 或者 256 Bit key, java complier 会抛出 Illegal key size Exception

解决办法

Plan A
替换 Policy 文件（选择对应 Java 版本下载）（需要注册个 Oracle 帐号）

https://www.oracle.com/java/technologies/javase-jce-all-downloads.html

替换 JDK 与 JRE 下两个 jar 包：local_policy.jar 和 US_export_policy.jar
JDK 对应 jar 包路径：%JAVA_HOME%\jre\lib\security
JRE 对应 jar 包路径：%JAVA_JRE%\lib\security
Plan B
升级 Java 版本