Amazon Selling Partner API - spapi.cyou

产品类型定义API v2020-09-01用例指南

亚马逊SPAPI

# 什么是产品类型定义API？

使用产品类型定义的销售伙伴API(产品类型定义API)，您可以搜索和检索亚马逊产品类型定义.亚马逊产品类型定义使用JSON Schema描述亚马逊目录中物品的属性和数据要求.

关于产品类型定义API提供的JSON Schema格式的更多细节，请参见附带的亚马逊产品类型定义Meta-Schema (v1) (opens new window) 文档.

参见产品类型定义API参考 (opens new window)，了解关于API操作和相关数据类型和模式的细节.

主要特点

JSON模式产品类型定义API提供了JSON模式，描述了给定的亚马逊产品类型的卖家要求.这包括数据格式、属性约束(i.e.要求、长度、最大等.)，以及有条件应用的属性约束(i.e.如果包括电池，什么类型的电池).

与Open-Source Libraries兼容所提供的JSON模式可以与广泛使用的开放-源和商业库、应用程序和服务一起使用，以了解数据需求，创建数据映射，生成用户界面，并在提交给亚马逊之前验证列表数据.

本地化的展示细节所提供的JSON模式包括任何市场的任何支持地区的属性的显示标签和描述.

术语

JSON Schema: JSON Schema是一个词汇表，允许你注释和验证JSON文档.详见json-schema.org (opens new window)

Meta schema: 元模式描述了JSON Schema文档所使用的词汇.例如，Amazon产品类型模式包括 "selectors "和 "editable "的词汇.这种词汇在元模式中被描述，使得库和应用程序能够根据这些对标准JSON Schema词汇的扩展来理解和验证JSON数据.

产品类型亚马逊产品类型是对亚马逊目录中的物品进行分层分类.物品数据要求与物品的相关产品类型挂钩.

# Tutorial: 搜索可用的产品类型定义

使用本教程来搜索和识别在产品类型定义API中可用的亚马逊产品类型，适用于特定的亚马逊市场和销售伙伴账户类型.

先决条件

要完成本教程，你需要

*来自你为之调用的销售伙伴的授权.更多信息请参见销售伙伴API开发者指南 (opens new window).

  • 在您的开发者档案中批准产品列表角色.

  • 在应用程序注册页面中为您的应用程序选择的产品列表角色.

# 步骤1.搜索产品类型定义

调用searchDefinitionsProductTypes (opens new window)操作来搜索产品类型定义API中的产品类型.

请求参数

Parameter Example Description Required
marketplaceIds ATVPDKIKX0DER Comma-delimited list of Amazon marketplace identifiers.

参见Selling Partner API Developer Guide获取亚马逊市场标识符的列表.		 是的
keywords LUGGAGE 逗号-分隔的关键词列表，用于按名称搜索可用的产品类型.

默认当没有提供关键字时，将提供可用产品类型的完整列表.		 没有

示例请求

GET https://sellingpartnerapi-na.amazon.com/definitions/2020-09-01/productTypes
	.marketplaceIds=ATVPDKIKX0DER
	&keywords=LUGGAGE
1
2
3

响应

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

Name Example Description
productTypes 见响应实例 符合搜索要求的产品类型列表.
name LUGGAGE 亚马逊产品类型名称.
marketplaceIds ATVPDKIKX0DER 产品类型可用的亚马逊市场标识符列表(在请求的市场标识符中).

示例响应

{
  "productTypes": [
    {
      "name": "LUGGAGE",
      "marketplaceIds": [
        "atvpdkikx0der"
      ]
    }
  ]
}
1
2
3
4
5
6
7
8
9
10

# Tutorial: 检索产品类型定义

使用本教程从产品类型定义API中为给定的销售伙伴、亚马逊产品类型和亚马逊市场返回亚马逊产品类型定义和相关模式.

先决条件

要完成本教程，你需要

*来自你为之调用的销售伙伴的授权.更多信息请参见销售伙伴API开发者指南 (opens new window).

  • 在你的开发者档案中批准产品列表角色.

  • 在应用程序注册页面中为您的应用程序选择的产品列表角色.

# 步骤1. 检索产品类型定义

调用getDefinitionsProductType (opens new window)操作，从产品类型定义API中检索亚马逊产品类型定义.

请求参数

路径参数

Parameter Example Description Required
productType LUGGAGE 亚马逊产品类型的名称.

类型: string

 是的

查询参数

Parameter Example Description Required
sellerId AXXXXXXXXXXXXX 销售伙伴标识符.当提供时，销售商-特定的要求和值会在产品类型定义模式中被填充，例如与销售伙伴相关的品牌名称.

类型：字符串

 No
marketplaceIds ATVPDKIKX0DER Comma-delimited list of Amazon marketplace identifiers.
Note: This parameter is limited to one marketplaceId at this time

See the Selling Partner API Developer Guide for the list of Amazon marketplace identifiers.

Type: < string > array(csv)

 是的
productTypeVersion U1d1eorqMs3U= 要检索的亚马逊产品类型定义的版本.产品类型定义的预发布版本可以用RELEASE_CANDIDATE检索.如果目前没有预发布版本，将提供LATEST实时版本.

默认LATEST

Type: string

 No
requirements LISTING 检索需求集的名称.

  • LISTING -需求包括产品事实和销售条款.
  • LISTING_OFFER_ONLY -要求只包括销售条款.
  • LISTING_PRODUCT_ONLY -要求只包括产品事实.

默认情况下LISTING

Type: enum (Requirements)

 No
requirementsEnforced ENFORCED 确定一个需求集的所需属性是否被产品类型定义模式强制执行.非-强制的需求使个别属性的结构性验证，而不是所有的所需属性都存在(例如部分更新).

  • ENFORCED -要求的属性是由模式强制执行的.
  • NOT_ENFORCED -模式不强制执行所需的属性.

默认情况下ENFORCED

Type: enum (RequirementsEnforced)

 没有
locale en_US 检索演示细节的地区(标签和描述)为.默认为亚马逊市场的主要地区.

默认值DEFAULT

Type: enum (Locale)

 没有

示例请求

GET https://sellingpartnerapi-na.amazon.com/definitions/2020-09-01/productTypes/LUGGAGE
	.marketplaceIds=ATVPDKIKX0DER
	要求=LISTING
	&amp;locale=en_US
1
2
3
4

响应

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

Name Example Description
metaSchema 
"metaSchema"{
  "链接"{
    "资源": "https://...",
    "动词": "GET"
  },
  "checksum": "QFQDmPwMARO7vwMEyLhOtw=="
}
 链接检索亚马逊产品类型定义元-Schema文档(有效期为7天).

提供的校验和用于与以前检索的文档进行比较.

TypeSchemaLink

schema 
"schema"{
  "链接"{
    "资源": "https://...",
    "动词": "GET"
  },
  "checksum": "TBr8ubaxXrUyay9hmxUXUw=="
}
 链接检索亚马逊产品类型定义的JSON Schema文档(有效期为7天).

提供的校验和用于与之前检索的文档进行比较.

类型SchemaLink

requirements LISTING 亚马逊产品类型定义所适用的需求集的名称.

  • LISTING -包括产品事实和销售条款的要求.
  • LISTING_OFFER_ONLY -要求只包括销售条款.
  • LISTING_PRODUCT_ONLY -要求只包括产品事实.

默认情况下LISTING

类型enum (Requirements)

requirementsEnforced ENFORCED 确定一个需求集的所需属性是否被产品类型定义模式强制执行.非-强制的需求使个别属性的结构性验证，而不是所有的所需属性都存在(例如部分更新).

  • ENFORCED -要求的属性是由模式强制执行的.
  • NOT_ENFORCED -模式不强制执行所需的属性.

默认情况下ENFORCED

Type: enum (RequirementsEnforced)

propertyGroups 
"propertyGroups": {
  "报价": {
    "标题": "报价",
    "描述": "产品报价"
    "propertyNames": [
      "可购买的报价"
    ]
  }
}
 属性组定义了亚马逊产品类型定义JSON Schema文档中描述的属性的逻辑分割.这种分割可用于在用户界面中对属性进行分组，识别目的等.

属性组只提供信息，不影响数据的结构和格式.

Type< string, PropertyGroup > map

locale en_US 亚马逊产品类型定义JSON Schema文档中提供的演示细节(标签和描述)的地域性.

类型：枚举(Locale)

marketplaceIds ATVPDKIKX0DER 亚马逊产品类型定义所适用的亚马逊市场标识符.

类型< string > array

productType LUGGAGE 该产品类型定义所适用的亚马逊产品类型名称.

类型: string

productTypeVersion U8L4z4Ud95N16tZlR7rsmbQ== 亚马逊产品类型定义的版本.

类型(ProductTypeVersion)

示例响应

{
  "metaSchema": {
    "链接"{
      "资源": "https://...",
      "动词": "GET"
    },
    "checksum": "QFQDmPwMARO7vwMEyLhOtw=="
  },
  "schema": {
    "链接": {
      "资源": "https://...",
      "动词": "GET"
    },
    "checksum": "TBr8ubaxXrUyay9hmxUXUw=="
  },
  "要求": "LISTING",
  "requirementsEnforced": "ENFORCED",
  "propertyGroups": {
    "报价": {
      "标题": "报价",
      "描述": "产品报价"
      "propertyNames": [
        "fulfillment_channel_availability",
        "purchasable_offer",
        "condition_type",
        "condition_note",
        "list_price",
        "product_tax_code",
        " merchant_release_date",
        " merchant_shipping_group",
        "max_order_quantity",
        "gift_options",
        "main_offer_image_locator",
        "other_offer_image_locator_1",
        "other_offer_image_locator_2"
        "other_offer_image_locator_3"
        "other_offer_image_locator_4"
        "其他提供的图像定位器_5"
      ]
    },
    "图像"{
      "标题": "图像",
      "描述": "物理图像或URL的"
      "propertyNames": [
        "main_product_image_locator",
        "other_product_image_locator_1",
        "other_product_image_locator_2",
        "other_product_image_locator_3"
        "other_product_image_locator_4",
        "other_product_image_locator_5",
        "other_product_image_locator_6",
        "other_product_image_locator_7",
        "other_product_image_locator_8",
        "产品形象定位器"
      ]
    },
    "运输"{
      "标题": "航运",
      "描述": "确定你的产品运输和储存的信息(e.g.，包装尺寸、重量、体积)"
      "propertyNames": [
        "item_dimensions",
        "item_package_dimensions", "item_package_dimensions",
        "项目_包装_重量"
      ]
    },
    "变化"{
      "标题": "变种"
      "描述": "产品将使用的变体"
      "propertyNames": [
        "parentage_level",
        "child_parent_sku_relationship",
        "变体_主题"
      ]
    },
    "安全和合规性"{
      "标题": "安全与合规"
      "描述": "表明产品合规性、危险材料以及法律和安全警告的信息(e.g.，锂电池、窒息危险、消费者产品安全信息法(CPSIA))"
      "propertyNames": [
        "原产地国",
        "保修_描述",
        "batteries_required",
        "电池_包括",
        "电池",
        "num_batteries",
        "number_of_lithium_metal_cells",
        "number_of_lithium_ion_cells",
        "lithium_battery",
        "supplier_declared_dg_hz_regulation",
        "危险品"
        "safety_data_sheet_url",
        " item_weight",
        "ghs",
        "supplier_declared_material_regulation",
        "California_proposition_65",
        "杀虫剂标记"
      ]
    },
    "Product_identity": {
      "标题": "产品身份"
      "描述": "用于唯一识别你的产品的信息(e.g.，UPC、EAN、GTIN、产品类型、品牌)"
      "propertyNames": [
        "item_name",
        "品牌",
        "supplier_declared_has_product_identifier_exemption",
        "externally_assigned_product_identifier",
        "Merchant_suggested_asin",
        " item_type_keyword",
        " item_type_name",
        "model_number",
        "制造商"
      ]
    },
    "product_details": {
      "标题": "产品详情"
      "描述": "描述产品的信息和特征，以支持搜索、浏览和详细页内容(e.g.，子弹、产品特征、模型、样式名称)"
      "propertyNames": [
        "product_description",
        "bullet_point",
        "general_keyword",
        "special_feature",
        "风格",
        "部门",
        "target_gender",
        "年龄范围_描述"
        "材料",
        "外部"
        "面料_类型",
        "里料_描述",
        "数量",
        "number_of_wheels",
        "轮子",
        "model_name",
        "颜色",
        "size",
        "size_map",
        "part_number",
        "合规性_媒体"
      ]
    }
  },
  "locale": "en_US",
  "marketplaceIds": [
    "atvpdkikx0der"
  ],
  "productType": "LUGGAGE",
  "productTypeVersion": {
    "版本": "U8L4z4Ud95N16tZlR7rsmbQ==",
    "最新": true,
    "releaseCandidate": false
  }
}
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
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152

# 步骤2. 检索模式文件

在上一步中，检索到的亚马逊产品类型定义包括关于亚马逊产品类型的详细信息以及检索元模式和产品类型模式文档的链接.所提供的链接有效期为7天.

模式文件可以通过标准的HTTP客户端进行编程检索，也可以通过网络浏览器手动检索.

重要提示亚马逊产品类型定义JSON模式文件通过名称引用元模式. 一些JSON模式库试图通过网络在线解决元模式名称，这[亚马逊产品类型定义元-模式(v1)](https //spapi.cyou/zh/references/product-type-definition-meta-schema.html)不支持.这些库应该被配置为使用下载的元模式副本来代替.参见附带的Amazon Product Type Definition Meta-Schema (v1) (opens new window) 文档了解更多细节.

# 常问问题

本文档涵盖了产品类型定义API的常见问题和细节.对于本文档未涵盖的问题或疑虑，请联系销售伙伴API支持，或在GitHub仓库创建一个问题.

# 亚马逊产品类型定义的新鲜度如何？

除非指定以前的 "productTypeVersion"，否则亚马逊产品类型定义总是描述最新的up-to-date亚马逊目录要求._

# 是否所有的亚马逊产品类型都可以使用产品类型定义API？

不是.

亚马逊正在不断扩大对产品类型定义API中新的和现有的亚马逊产品类型的支持.对于可用的亚马逊产品类型的最新列表，请使用产品类型定义API.

# 使用什么版本的JSON Schema？

亚马逊产品类型定义的JSON Schemas扩展了JSON Schema 2019-09 (opens new window). 更多细节请参见附带的亚马逊产品类型定义Meta-Schema (v1) (opens new window) 文档.

# 未来版本的JSON Schema将如何被利用？

随着JSON Schema的未来版本被产品类型定义API采用，它们将伴随着产品类型定义API和Amazon产品类型定义元-Schema (opens new window).的新版本发布

未来版本的JSON Schema不会被现有版本的产品类型定义API或Amazon产品类型定义Meta-Schema (opens new window).采用

# 产品类型定义的JSON模式是否包括自定义词汇？

大多数亚马逊目录要求都是利用标准的JSON Schema 2019-09 (opens new window) 词汇来描述的.然而，有一些要求需要用自定义词汇来扩展JSON Schema.请看附带的亚马逊产品类型定义Meta-Schema (v1) (opens new window) 文档来了解更多细节.

# 我是否需要为自定义词汇实施验证？

不需要.

亚马逊产品类型定义Meta-Schema (v1)](https: //spapi.cyou/zh/references/product-type-definition-meta-schema.html)使用自定义词汇来全面描述亚马逊的目录要求.用自定义数据验证数据，可以使你在提交给亚马逊之前防止大多数列表-相关问题发生.然而如果不实施这种验证，提交给亚马逊的数据在提交给亚马逊后可能会产生与列表-相关的问题.，这取决于-你是否实施这种验证

# 我需要自定义代码来使用JSON模式吗？

是的.

自定义代码的数量取决于你的应用.示例场景

使用带有验证自定义词汇的Open-Source库利用open-source库来处理大多数JSON模式的验证，意味着需要自定义代码来从产品类型定义API检索模式，实现自定义词汇的验证，并与open-source库集成.

使用Open-Source库而不对自定义词汇进行验证利用open-source库来处理大多数JSON模式的验证，意味着需要定制代码来从产品类型定义API中检索模式，并与open-source库整合.

# 有哪些Open-Source库可用？

有几十个开放-源码库和实现可用于验证数据、渲染用户界面和生成代码.参见JSON Schema Implementations (opens new window)，以获得完整的列表.

亚马逊并不直接支持或认可任何特定的开放-源码或商业库和实现.本文档中提供的例子仅供参考.

# 用产品类型模式验证数据有哪些例子？

随附的Amazon产品类型定义元-模式(v1) (opens new window) 文档包括与开放-源库的集成实例，以验证在.NET (C#)、Java和JavaScript (Node.js).中的定制词汇的数据

# 如何报告亚马逊产品类型定义的问题？

对于产品类型定义API或亚马逊产品类型定义JSON Schemas内容的具体问题，请联系销售伙伴API支持 (opens new window).

Reports API v2020-09-04