Feeds API v2021-06-30 用例指南

sfgoods 亚马逊SPAPI

# 什么是Feeds API?

通过Selling Partner API for Feeds (Feeds API)，您可以建立应用程序，使卖家能够向亚马逊上传信息，帮助他们管理销售业务.有各种使用案例的feeds，如创建列表、管理库存和价格、确认订单等.参见Feed Type Values (opens new window)，了解可用的feed类型列表.

# 提交feeds的工作流程

以下是提交feeds的高级步骤

1.调用createFeedDocument (opens new window)操作，指定你要提交的feed的内容类型.

亚马逊返回一个**feedDocumentId**值和一个用于上传feed内容的URL.

2.将你的feed文件内容上传到上一步的URL.

3.调用createFeed (opens new window)操作.使用inputFeedDocumentId参数来传入步骤1中的feedDocumentId值.指定你想要应用feed的市场和任何相关的feed选项.

亚马逊返回一个**feedId**值.

4.定期轮询亚马逊SQS队列中的FEED_PROCESSING_FINISHED通知事件，当Feed处理为CANCELLED、DONE或FATAL时提供信息.

当Feed进入DONE状态时，亚马逊在通知中返回resultFeedDocumentId值.

5.调用getFeedDocument (opens new window)操作.使用feedDocumentId参数来传入上一步的resultFeedDocumentId值.

亚马逊返回**feedDocumentId**值，一个用于下载feed处理报告的URL，以及压缩算法.

下载feeds处理报告.
检查feeds处理报告中在feeds处理过程中产生的错误. 如果有错误，纠正它们并提交更正后的feeds，从步骤1开始. 如果没有错误，你的feeds提交成功了.

有关提交feed的更多细节，请参阅TutorialSubmit a feed.

# Terminology

S3预签名的URL.一个AWS S3桶的URL，你可以在没有AWS安全凭证或权限的情况下将一个对象上传到该桶中.你在步骤1中得到一个**S3预签名的URL.创建一个feed document和Step 6. Get information for retrieving the feed processing report.

# Tutorial: 提交一个feeds

本教程告诉你如何提交feed，检查feed处理的状态，并验证你的feed提交是否成功. 本教程包含Java代码样本，演示了上传feed和下载feed处理总结报告的方法. 你可以使用样本代码中演示的原则来指导你用其他编程语言构建应用程序，使用其他HttpClient库或上传不同格式的feed.

先决条件

要完成本教程，你将需要

一个要提交的feed.参见feed类型值 (opens new window)，以获得可用的feed类型列表.

2.来自你为之打电话的卖家的授权.参见授权销售伙伴API应用程序 (opens new window)，以获得更多信息.

3.一个工作的Java开发工具包(JDK)安装.

# 步骤1.创建一个feed文档

调用createFeedDocument操作来创建一个feed文档.

Call the createFeedDocument (opens new window) operation, passing the following parameter:

主体参数

Name	Description	Required
contentType	feeds的内容类型.亚马逊推荐UTF-8字符编码. 重要的是.在Step 3. Upload the feed data.中使用这个contentType值，否则你的feed数据上传会失败. Type: string	是的

contentType

feeds的内容类型.亚马逊推荐UTF-8字符编码.

重要的是.在Step 3. Upload the feed data.中使用这个contentType值，否则你的feed数据上传会失败.

Type: string

是的

请求示例

POST https://sellingpartnerapi-na.amazon.com/feeds/2021-06-30/documents
{
  "contentType": "text/xml; charset=UTF-8"

1
2
3
4

响应

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

feeds的标识符.

类型: string

Name	Description	Required
feedDocumentId	馈送文件的标识符. Type: string	Yes
url	用于上传feeds内容的预设URL.此URL在5分钟后过期. Type: string	是的

feedDocumentId

馈送文件的标识符.

Type: string

Yes

url

用于上传feeds内容的预设URL.此URL在5分钟后过期.

Type: string

是的

响应示例

{
  "feedDocumentId": "amzn1.tortuga.3.920614b0-fc4c-4393-b0d9-fff175300000.T29XK4YL08B2VM",
  "url": "https://tortuga-prod-na.s3.amazonaws.com/%2FNinetyDays/amzn1.tortuga.3.920614b0-fc4c-4393-b0d9-fff175300000.T29XK4YL08B2VM?X-Amz-Algorithm=AWS4-HMAC-SHA256&amp;X-Amz-Date=20200919T035824Z&amp;X-Amz-SignedHeaders=<headers>&amp;X-Amz-Expires=300&amp;X-Amz-Credential=<credential>&amp;X-Amz-Signature=<signature>"
}

1
2
3
4

保存以下值
- url. 在步骤3.上传feed数据时使用此值.
- feedDocumentId.在步骤4中使用这个值.创建一个feed.这个feedDocumentId值在两天后过期.如果你在createFeed操作中传递一个过期的feedDocumentId值，调用将失败._

# 第2步.构建一个feed

构建一个feed，你可以在步骤3.上传feed数据上传

# XML feeds

要构建一个XML feed，你需要包括三个核心XSD(Base, Envelope, and Header)加上你的类别-特定的feed.

核心XSD

**Base (opens new window).**用于促进feeds之间的一致性.所有其他的XSD都引用Base XSD中的元素和数据类型.
**Envelope (opens new window).**用于用消息-级别的协议数据来包装所有其他数据.由一个头和一个或多个消息组成.
**Header (opens new window).**被信封XSD用来指定与feeds或feeds中某一消息有关的通用数据.

对于类别-特定feeds的XSD链接，请到卖方中心帮助中的XSDs (opens new window)，并在类别XSDs部分寻找.

下面是一个健康-相关产品的XML提要的例子

<? xml version="1.0" encoding="iso-8859-1"?
<AmazonEnvelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="amzn-envelope.xsd">
  <标题></p><p><p>
    <DocumentVersion>1.01</DocumentVersion>
    <MerchantIdentifier>M_EXAMPLE_123456</MerchantIdentifier>
  </标题></Header>
  <MessageType>产品</MessageType></MessageType
  <PurgeAndReplace>false</PurgeAndReplace>
  <消息></Message></Message></Message></Message
    <MessageID>1</MessageID>
    <操作类型>Update</OperationType>
    <产品>
      <sku>56789</sku
      <StandardProductID> <类型>ASIN</Type
        <类型>ASIN</类型
        <值>B0EXAMPLEG</值
      </StandardProductID></StandardProductID>
      <ProductTaxCode>A_GEN_NOTAX</ProductTaxCode>
      <描述数据> <标题>示例产品
        <标题>示例产品名称</标题></Title
        <Brand>示例产品品牌</Brand>
        <Description>这是一个产品描述的例子.</Description>
        <BulletPoint>示例子弹点1</BulletPoint>
        <BulletPoint>示例BulletPoint 2</BulletPoint>
        <MSRP currency="USD">25.19</MSRP>
        <Manufacturer>示例产品制造商</Manufacturer>
        <ItemType>example-item-type</ItemType>
      </DescriptionData> </DescriptionData>
      <产品数据>
        <保健>
          <产品类型>
            <健康百科> <健康百科
              <成分>示例成分</Ingredients>
              <指令>示例说明</指令></Directions
            </HealthMisc>
          </产品类型> </产品类型> </产品类型>
        </健康>
      </产品数据></ProductData>
    </产品></Message>
  </Message></Message>
</AmazonEnvelope>

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

# 第3步.上传feeds数据

你可以上传你在Step 2.Construct a feed中构建的feed，使用Step 1.Create a feed document.返回的信息下面的示例代码演示了上传feed内容的一种方法.你也可以使用示例代码中演示的原则来指导你用其他编程语言或使用其他HttpClient库来构建应用程序.

在UploadExample类中显示的样本upload方法接受你的feed内容作为第一个参数，并接受你在步骤1中保存的url值作为第二个参数.

# Upload示例代码(Java)

// UploadExample.java
// 这个例子是用于销售伙伴的feedsAPI，版本：2021-06-30
import java.io.IOException;
import java.nio.charset.StandardCharsets;

import com.squareup.okhttp.MediaType;
import com.squareup.okhttp.OkHttpClient;
import com.squareup.okhttp.Request;
import com.squareup.okhttp.RequestBody;
import com.squareup.okhttp.Response;

/**
 *上传内容的例子.
 */
public class UploadExample {

  public static void main(String args[]) {
    String url = "<来自createFeedDocument操作的URL>"
    String content = "<your feed content>";

    UploadExample obj = new UploadExample();
    obj.upload(content.getBytes(StandardCharsets.UTF_8), url);
  }

  /**
   *上传内容到给定的URL.
   *
   * @param source 要上传的内容
   * @param url 上传内容的URL
   
  public void upload(byte[] source, String url) {
    OkHttpClient client = new OkHttpClient();

    // 内容类型必须与提供给createFeedDocument操作的输入相匹配. 本例使用text/xml，但你的内容类型可能不同，这取决于你选择的feedType (text/plain, text/csv, 等等).
    String contentType = String.format("text/xml; charset=%s", StandardCharsets.UTF_8);
    try {
      Request request = new Request.Builder()
        .url(url)
        .put(RequestBody.create(MediaType.parse(contentType), source))
        .build();

      响应 = client.newCall(request).execute()
      if (!response.isSuccessful()) {
        System.out.println(
          String.format("调用上传文档失败，响应代码%d and message: %s",
            response.code(), response.message()));
      }
    } catch (IOException e) {
      System.out.println(e.getMessage());
    }

  }
}

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
43
44
45
46
47
48
49
50
51
52
53

# 步骤4.创建一个feeds

调用createFeed操作，指定feed文档标识符、feed类型、你希望feed应用到的市场，以及任何你想要的可选参数.

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

主体参数

Name	描述	Required
feedType	您要提交的feed类型.更多信息，请参见Feed Type Values. Type: string	是的
marketplaceIds	您希望feeds被应用到的市场的标识符列表. 类型: < string > array	是的
inputFeedDocumentId	在Step 1. Create a feed document. 中由createFeedDocument操作返回的文档标识 Type: string	是的
feedOptions	控制喂食的额外选项.这些因喂食类型而异. Type: string	没有

请求示例

POST https://sellingpartnerapi-na.amazon.com/feeds/2021-06-30/feeds
{
  "feedType": "POST_PRODUCT_DATA",
  "marketplaceIds":[
    "atvpdkikx0der",
    "a2euq1wtgctbg2"
  ],
  "inputFeedDocumentId":"amzn1.tortuga.3.920614b0-fc4c-4393-b0d9-fff175300000.T29XK4YL08B2VM"
}

1
2
3
4
5
6
7
8
9

易发货订单的请求示例

POST https://sellingpartnerapi-na.amazon.com/feeds/2021-06-30/feeds
{
  "feedType": "POST_EASYSHIP_DOCUMENTS",
  "marketplaceIds":["A21TJRUUN4KGV"],
  "feedOptions":
  {
    "AmazonOrderId":"902-3159896-1390916",
    "DocumentType": "航运标签"
  },
  "inputFeedDocumentId":"amzn1.tortuga.3.06438a22-2b6f-4138-a120-362c096d5e04.TKXDFQFUMYD86"
}

1
2
3
4
5
6
7
8
9
10
11

响应

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

Name	Description	Required
feedId	feed的标识符.这个标识符只有在与卖家ID. 结合时才是唯一的 Type: string	是的

feedId

feed的标识符.这个标识符只有在与卖家ID.

结合时才是唯一的

Type: string

是的

响应示例

{
  "feedId": "23492394"
}

1
2
3

2.保存feedId值.在步骤5.确认feed处理中的getFeed操作中传递此值.

# 第5步.确认feeds处理

在你调用createFeed操作后，亚马逊收到请求并开始处理feed.你必须在继续之前确认处理已经完成.

我们建议你使用Notifications API (opens new window)来订阅事件FEED_PROCESSING_FINISHED，以便在feed处理状态发生变化时得到通知.这可以减少你调用getFeed (opens new window)操作进行处理状态检查的次数.

每当使用Selling Partner API for Feeds提交的任何feed达到DONE、CANCELLED或FATAL的feed处理状态时，就会发送FEED_PROCESSING_FINISHED通知.

要订阅FEED_PROCESSING_FINISHED通知类型，请参阅Notifications API Use Case Guide (opens new window). 更多信息请参阅FEED_PROCESSING_FINISHED通知事件. (opens new window)

以下处理状态值确认处理已经完成

DONE -feeds处理已经完成.转到步骤6.获取检索feeds处理报告的信息.
CANCELLED - feeds在开始处理之前就被取消了. 如果你想重新提交feeds，去步骤1.创建一个feeds文件.
FATAL -由于一个致命的错误，该feeds被放弃了.feeds中的一些、没有或所有的操作可能已经成功完成.在一些(但不是所有)情况下，亚马逊生成了一个feeds处理报告.如果亚马逊生成了一个报告它的格式可能与成功完成的feeds处理报告不同.进入步骤6.获取检索feeds处理报告的信息以检索feeds处理报告.在罕见的情况亚马逊可能会因为与feeds无关的原因而放弃一个feeds.如果你在feeds中找不到需要纠正的错误，请尝试再次提交该feeds.

# 步骤6.获取检索feed处理报告的信息

feeds处理报告指出你提交的feeds中哪些记录是成功的，哪些记录产生了错误.在这一步，你得到一个预设的URL，用于下载feeds处理报告.

Call the getFeedDocument (opens new window) operation, passing the following parameter:

路径参数

Name	Description	Required
feedDocumentId	feeds文件的标识符.使用resultFeedDocumentId中返回的Step 5.确认feeds处理. 的值 Type: string	是的

feedDocumentId

feeds文件的标识符.使用resultFeedDocumentId中返回的Step 5.确认feeds处理.

的值

Type: string

是的

请求示例

GET https://sellingpartnerapi-na.amazon.com/feeds/2021-06-30/documents/amzn1.tortuga.3.ed4cd0d8-447b-4c22-96b5-52da8ace1207.T3YUVYPGKE9BMY

响应

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


feedDocumentId	进货文件的标识符.该标识符只有在与卖方ID. 结合时才是唯一的 Type: string	是的
url	一个预设的feeds文件的URL.这个URL在5分钟后过期. Type: string	是的
compressionAlgorithm	如果存在，则使用指定的算法对进给文件内容进行压缩. 类型compressionAlgorithm	No

feedDocumentId

进货文件的标识符.该标识符只有在与卖方ID.

结合时才是唯一的

Type: string

是的

url

一个预设的feeds文件的URL.这个URL在5分钟后过期.

Type: string

是的

compressionAlgorithm

如果存在，则使用指定的算法对进给文件内容进行压缩.

类型compressionAlgorithm

响应示例

{
  "feedDocumentId": "amzn1.tortuga.3.ed4cd0d8-447b-4c22-96b5-52da8ace1207.T3YUVYPGKE9BMY",
  "url": "https://tortuga-prod-na.s3.amazonaws.com/%2FNinetyDays/amzn1.tortuga.3.920614b0-fc4c-4393-b0d9-fff175300000.T29XK4YL08B2VM?X-Amz-Algorithm=AWS4-HMAC-SHA256&amp;X-Amz-Date=20200919T035824Z&amp;X-Amz-SignedHeaders=<headers>&amp;X-Amz-Expires=300&amp;X-Amz-Credential=<credential>&amp;X-Amz-Signature=<signature>"
}

1
2
3
4

2.保存url和可选的compressionAlgorithm值，以便在步骤7.下载feeds处理报告.时传递

# 第7步.下载feeds加工报告

你可以使用上一步返回的信息下载feeds处理报告.下面的Java示例代码可以提供帮助.你也可以使用Java示例代码中演示的原则来指导你在其他编程语言中构建应用程序.

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

- 上一步的**url**和可选的**compressionAlgorithm**值是``url``和``compressionAlgorithm``参数，这些参数是``DownloadExample``类的```download``方法的参数.

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

# 下载示例代码(Java)

// DownloadExample.java
// 本示例用于报告的销售伙伴API，版本：2021-06-30
// 和销售伙伴 API for Feeds, 版本: 2021-06-30
import java.io.BufferedReader;
import java.io.Closeable;
import java.io.IOException;
import java.io.InputStream;
import java.io.InputStreamReader;
import java.nio.charset.Charset;
import java.util.zip.GZIPInputStream;

import com.squareup.okhttp.MediaType;
import com.squareup.okhttp.OkHttpClient;
import com.squareup.okhttp.Request;
import com.squareup.okhttp.Response;
import com.squareup.okhttp.ResponseBody;

/**
 *下载一个文档的例子.
 */
public class DownloadExample {

  public static void main(String args[]) {
    String url = "<来自getFeedDocument/getReportDocument响应的URL>"
    String compressionAlgorithm = "<来自getFeedDocument/getReportDocument响应的压缩算法>"

    DownloadExample obj = new DownloadExample();
    尝试 {
      obj.download(url, compressionAlgorithm);
    } catch (IOException e) {
      //在这里处理异常.
    } catch (IllegalArgumentException e) { //处理这里的异常.
      //处理这里的异常.
    }
  }

  /**
   *下载并可选择解压从给定的url.中获取的文件
   *
   * @param url 指向文档的url
   * @param compressionAlgorithm 指用于文档的压缩算法
   * @抛出IOException，当有一个错误读取响应时
   * @当字符集丢失时，抛出IllegalArgumentException
   */
  public void download(String url, String compressionAlgorithm) throws IOException, IllegalArgumentException {
    OkHttpClient httpclient = new OkHttpClient();
    请求 request = 新的 Request.Builder()
      .url(url)
      .get()
      .build();

    响应 = httpclient.newCall(request).execute()
    如果(!Response.isSuccessful()) {
      System.out.println(
        String.format("Call to download content was unsuccessful with response code: %d and message: %s",
          response.code(), response.message()));
      返回
    }

    try (ResponseBody responseBody = response.body()) {
      MediaType mediaType = MediaType.parse(response.header("Content-Type"));
      Charset charset = MediaType.charset()
      如果(charset == null) {
        抛出新的IllegalArgumentException(String.format(
          "无法解析来自'%s'的字符集", mediaType.toString())
      }

      Closeable closeThis = null;
      试试 {
        InputStream inputStream = responseBody.byteStream();
        closeThis = inputStream;

        if ("GZIP".equals(compressionAlgorithm)) {
          inputStream = new GZIPInputStream(inputStream);
          closeThis = inputStream;
        }

        // 这个例子假设下载内容在content-type头中有一个charset，e.g.
        // text/plain; charset=UTF-8
        if ("text".equals(mediaType.type()) &amp;&amp; "plain".equals(mediaType.subtype())) {
          InputStreamReader inputStreamReader = new InputStreamReader(inputStream, charset);
          closeThis = inputStreamReader;

          BufferedReader reader = new BufferedReader(inputStreamReader);
          closeThis = reader;

          字符串行
          do {
            line = reader.readLine();
            //逐行处理.
          } while (line != null);
        } else {
          //在此处理带有二进制数据/其他媒体类型的内容.
        }
      } finally {
        if (closeThis != null) {
          closeThis.close();
        }
      }
    }
  }
}

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
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102

# 步骤8.检查feeds处理报告中的错误

检查feeds处理报告中在处理过程中产生的错误.如果没有错误，你的feeds提交就完成了.如果有错误，纠正它们并提交更正后的feeds，从步骤1.创建一个feeds文件.重复该过程，直到feeds处理报告中没有错误.

# 最佳实践

关于使用Feeds API的最佳做法，请参阅Feeds API最佳做法 (opens new window).

Feeds API v2020-09-04 Listings Items API v2020-09-01

Amazon Selling Partner API - spapi.cyou

Choose mode