连接到销售伙伴API

sfgoods 亚马逊SPAPI

在您的应用程序可以连接到销售伙伴API之前，您必须注册它，并且它必须得到销售伙伴的授权.参见注册您的应用程序和授权销售伙伴API应用程序.

这些说明向您展示了调用Selling Partner API的步骤.关于构建Selling Partner API URI和向其添加头信息的帮助，请参见[生成Java客户端库](doc 生成-a-java-client-library). 关于一个更完整的解决方案，包括交换LWA令牌和认证的代码，请参阅[生成一个带有LWA令牌交换的Java SDK](doc generating-a-java-sdk-with-lwa-token-exchange-and-authentication) [and authentication](doc: generating-a-java-sdk-with-lwa-token-exchange-and-authentication).

# 步骤1.请求使用亚马逊访问令牌登录

登录亚马逊(LWA)访问令牌授权您的应用程序代表销售伙伴采取某些行动. LWA访问令牌在签发后一小时内失效.

关于受限操作的说明. 在调用所有操作时必须包括LWA访问令牌，除了受限操作，这些操作会返回个人身份信息(PII). 当调用受限操作时，你不是包括LWA访问令牌，而是包括受限访问令牌(RDT). 关于获取RDT和调用受限操作的信息，请参见[Tokens API使用案例指南](doc tokens-api-use-case-guide).

要请求一个LWA访问令牌，请向LWA认证服务器(https://api.amazon.com/auth/o2/token)发出一个安全的HTTP POST，参数如下

Name	Description	Required
grant_type	请求的访问授权类型.值： refresh_token.在调用需要销售伙伴授权的操作时使用此值.所有不是无授权操作的操作都需要销售伙伴的授权.指定此值时，包括refresh_token参数. client_credentials.在调用grantless operations.时使用此值，包括`scope`参数.	是的
refresh_token	LWA刷新令牌.当销售伙伴授权你的应用程序时，获得这个值.更多信息，请参见授权销售伙伴API应用程序.	No.在调用需要销售伙伴授权的操作时，包括refresh_token.如果你包括refresh_token，不要包括范围.
scope	LWA授权许可的范围.值： sellingpartnerapi::notifications.用于通知API. sellingpartnerapi::migration. 用于授权API.	No.包括调用无损操作的范围.如果你包括范围，不要包括refresh_token.
client_id	当你注册你的应用程序时得到这个值.见查看你的开发者信息.	是的
client_secret	当你注册你的应用程序时得到这个值.参见查看你的开发者信息.	是的

调用一个需要销售伙伴授权的操作的例子

POST /auth/o2/token HTTP/l.l
主机: api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
grant_type=refresh_token
&amp;refresh_token=Aztr|...
&amp;client_id=foodev
&amp;client_secret=Y76SDl2F

1
2
3
4
5
6
7

调用无授权操作的例子

POST /auth/o2/token HTTP/l.l
主机：api.amazon.com
Content-Type: application/x-www-form-urlencoded;charset=UTF-8
grant_type=client_credentials
&amp;scope=sellingpartnerapi::notifications
&amp;client_id=foodev
&amp;client_secret=Y76SDl2F

1
2
3
4
5
6
7

**提示：**为了避免在调用LWA授权服务器时得到一个不受信任的证书授权(CA)错误，请确保更新你的信任存储，使你的应用程序信任LWA授权服务器.

响应

一个成功的响应包括以下值.

| 名称 | 描述 | **说明 | ------------------ | --- | | 访问令牌 | LWA的访问令牌. 最大尺寸：2048字节. | | token_type | 返回的token的类型. 必须是bearer. | | expires_in | LWA访问令牌失效前的秒数. | | refresh_token | 您在请求中提交的LWA刷新令牌. 最大尺寸：2048字节. |

HTTP/l.l 200 OK
Content-Type: application/json;charset UTF-8
Cache-Control: no-store
Pragma:no-cache
{
  "access_token": "Atza|IQEBLjAsAhRmHjNgHpi0U-Dme37rR6CuUpSREXAMPLE" 
  "token_type": "bearer",
  "expires_in":3600
  "refresh_token": "Atzr|IQEBLzAtAhRPpMJxdwVz2Nn6f2y-tpJX2DeXEXAMPLE"
}

1
2
3
4
5
6
7
8
9
10

更多信息，请访问登录亚马逊文档中的授权码授权 (opens new window)页面.

# 步骤2.构建一个销售伙伴API URI

以下是销售伙伴API URI的组成部分.

名称	描述	示例
HTTP方法	HTTP方法.	`GET`
端点	A 销售伙伴API端点.	`https://sellingpartnerapi-na.amazon.com`
路径	Selling Partner API section/version. number of the section/resource.	`fba/inbound/v0/shipments/{shipmentId}/preorder/confirm`
查询字符串	查询参数.	`?marketplace=ATVPDKIKX0DER`
路径参数	路径参数.	`shipmentId1`

比如说

PUT https://sellingpartnerapi-na.amazon.com/fba/inbound/v0/shipments/shipmentId1/preorder/confirm?MarketplaceId=ATVPDKIKX0DER&amp;NeedByDate=2020-10-10

# 步骤3.向URI添加头信息

向你在[步骤2.构建销售伙伴API URI](doc中构建的URI添加头信息 connecting-to-the-selling-partner-api#step-2-construct-a-selling-partner-api-uri). 以下是你在向Selling Partner API发出请求时包含的HTTP头信息

Request headers

| 名称 | 描述 | **说明 | ---------- | ---------------- | |主机|市场端点.见销售伙伴API端点.| | x-amz-access-token | LWA access token. 见 [Step 1. Request a Login with Amazon access token](doc connecting-to-the-selling-partner-api#step-1-request-a-login-with-amazon-access-token).
**关于受限操作的注意事项.**如果你在调用一个受限操作这里传递一个受限数据令牌(RDT)，而不是LWA访问令牌.关于获取RDT和调用受限操作的信息，请参见[Tokens API Use Case Guide](doc tokens-api-use-case-guide)中的Tokens API用例指南. | | x-amz-date | 您请求的日期和时间. | | user-agent | 你的应用程序名称和版本号、平台和编程语言. 这些有助于亚马逊诊断和解决你在服务中可能遇到的问题. 见[在所有](doc中包括一个User-Agent头 include-a-user-agent-header-in-all-requests) requests. |

下面是一个向销售伙伴API请求的例子，其中有URI和头信息，但没有签名信息

PUT /fba/inbound/v0/shipments/shipmentId1/preorder/confirm?MarketplaceId=ATVPDKIKX0DER&amp;NeedByDate=2020-10-10 HTTP/1.1
host: sellingpartnerapi-na.amazon.com
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: 20190430T123600Z

1
2
3
4
5
6

要签署对销售伙伴API的请求，请参阅步骤4.创建并签署你的请求.

# 第4步.创建并签署你的请求

销售伙伴API使用AWS Signature Version 4 Signing Process (opens new window)来验证请求.当你向销售伙伴API发送HTTP请求时，你要对请求进行签名，这样亚马逊就可以识别谁发送了请求.你使用你的AWS访问密钥来签署请求，它由一个访问密钥ID和一个秘密访问密钥组成.亚马逊建议使用[AWS Security Token Service (AWS STS)](https //docs.aws.amazon.com/STS/latest/APIReference/welcome.html)来请求临时的AWS访问密钥来签署你的请求.见[创建和配置IAM策略和实体](doc 创建-and-configuring-iam-policies-and-entities)以创建一个IAM用户(并附加一个AWS STS策略)，承担一个IAM角色.然后你使用IAM角色注册你的应用程序.关于使用AWS STS和AWS SDK的更多信息，可以帮助你实现参见[Requesting temporary security credentials](https: //docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_temp_request.html)在AWS文档.中

**注意：**只有当你手动创建HTTP请求时，你才需要学习如何签名.当你使用AWS SDK之一为你计算签名时，SDK会自动用你配置时指定的AWS访问密钥对请求进行签名.当你使用SDK时，你不需要自己学习如何签名请求.例如，Java开发人员可以使用[AWS4Signer.java](https //github.com/aws/aws-sdk-java/blob/master/aws-java-core/src/main/java/com/amazonaws/auth/AWS4Signer.java)从你可以在[AWS的GitHub存储库中找到其他语言的SDK](https //github.com/aws).

要创建和签署你的请求，请完成以下工作

创建一个规范的请求

按照[Task 1中的说明按照AWS文档中的Task 1: Create a Canonical Request for Signature Version 4 (opens new window)中的说明，使用该指南
- 参见步骤3.向URI添加头信息，了解一个无签名请求的例子，在创建规范请求时，可以从这个例子开始.
- 使用SHA-256作为哈希算法.
- 不要把认证信息放在查询参数中.把它放在授权'头参数中.关于使用授权'头参数的认证信息，见授权头.

2.创建一个字符串来签名按照AWS文档中Task 2: Create a String to Sign for Signature Version 4 (opens new window)中的说明，使用此指导 - 算法指定值为AWS4-HMAC-SHA256 - 要确定凭证范围，见凭证范围.

3.计算签名

按照AWS文档中[任务3：计算AWS签名版本4的签名](https://docs.aws.amazon.com/general/latest/gr/sigv4-calculate-signature.html)中的说明进行计算.

**重要的是** 参见[Credential scope](doc:connecting-to-the_selling-partner-api#credential-scope)来帮助你完成这个步骤.

4.添加签署信息

按照AWS文档中[Task 4: Add the Signature to the HTTP Request](https://docs.aws.amazon.com/general/latest/gr/sigv4-add-signature-to-request.html)中的说明，使用此指导

  - 不要将签名信息添加到查询字符串中. 添加到 "授权 "标题参数中.

  - 参见[Authorization header](doc:connecting-to-the-selling-partner-api#authorization-header)了解关于创建`Authorization`header参数的详细信息.

下面的例子显示了在你使用授权头向其添加签名信息后的请求的样子.

PUT /fba/inbound/v0/shipments/shipmentId1/preorder/confirm?MarketplaceId=ATVPDKIKX0DER&amp;NeedByDate=2020-10-10HTTP/1.1
授权AWS4-HMAC-SHA256 Credential=AKIAIHV6HIXXXXXXX/20201022/us-east-1/execute-api/aws4_request, SignedHeaders=host;user-agent;x-amz-access-token,
Signature=5d672d79c15b13162d9279b0855cfba6789a8edb4c82c400e06b5924aEXAMPLE
host: sellingpartnerapi-na.amazon.com
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: 20190430T123600Z

1
2
3
4
5
6
7
8

# Credential scope

凭证范围是你在向销售伙伴API签署请求时创建的 "签署字符串 "的一个组成部分.参见创建并签署你的请求.

凭证范围由一个斜线-分隔的维度字符串表示，如下表所示

维度	描述	示例
日期	一个八位数的字符串，代表请求的年(YYYY)、月(MM)和日(DD)	`20190430`
AWS地区	您发送请求的地区. 见销售伙伴API端点.	`us-east-1`
服务	您请求的服务. 您可以在端点中找到这个值. 见销售伙伴API端点.	`execute-api`
终止字符串	一个特殊的终止字符串. 对于AWS签名版本4，该值是aws4_request	`aws4_request`

比如说

20190430/us-east-1/execute-api/aws4_request

**重要的是：**您作为凭证范围的一部分使用的日期必须与您的请求日期相匹配，如x-amz-date头中指定的日期. 欲了解更多信息，请参阅AWS文档中的Handling Dates in Signature Version 4 (opens new window)

更多信息，请参见步骤4.创建并签署你的请求.

# Authorization header

授权头包含了一个请求的签名信息.尽管这个头被命名为 "授权"，但签名信息是用来认证的.

以下是授权标头的组成部分

组件	描述	说明
用于签名的算法	整个签名过程中使用的哈希算法.销售伙伴API需要SHA-256.你在[步骤4.创建和签名你的请求](doc中指定这个 connecting-to-the-selling-partner-api#step-4-create-and-sign-your-request).
凭证	你的AWS访问密钥ID加上凭证范围.你在[步骤2.创建一个IAM用户](doc中得到你的AWS访问密钥ID creating-and-configuring-iam-policies-and-entities#step-2-create-an-iam-user).
SignedHeaders	你在签名请求中包含的所有HTTP头信息的列表. 对于一个例子，见[步骤3.向URI添加头信息](doc connecting-to-the-selling-partner-api#step-3-add-headers-to-the-uri).
签名	在步骤4.创建并签署你的请求.	计算的签名

比如说

授权AWS4-HMAC-SHA256 Credential=AKIAIHV6HIXXXXXXX/20201022/us-east-1/execute-api/aws4_request, SignedHeaders=host; user-agent;x-amz-access-token;x-amz-date, Signature=5d672d79c15b13162d9279b0855cfba6789a8edb4c82c400e06b5924aEXAMPLE

更多信息，请参阅步骤4.创建并签署你的请求.

Connecting to the Selling Partner API using a generated Java SDK Determine app type

Amazon Selling Partner API - spapi.vip

Choose mode