商品类型定义 API v2020-09-01 用例指南
以编程方式获取亚马逊目录中的商品类型属性和数据要求。
API 版本:2020-09-01
什么是产品类型定义 API?
使用用于商品类型定义的销售伙伴 API(商品类型定义 API),您可以搜索和检索亚马逊商品类型定义。亚马逊商品类型定义使用 JSON 架构描述了亚马逊目录中商品的属性和数据要求。
有关商品类型定义 API 提供的 JSON 架构格式的详细信息,请参阅随附的亚马逊商品类型定义元架构 (v1) 文档。
请参阅 产品类型定义 API v2020-09-01 参考 了解有关 API 操作以及相关数据类型和架构的详细信息。
主要功能
-
JSON 架构:商品类型定义 API 提供了 JSON 架构,用于描述给定亚马逊商品类型与卖家无关的要求。其中包括数据格式、属性约束(即必填项、长度、最大值等)和有条件应用的属性约束(即如果包括电池,则包含哪种类型的电池)。
-
与开源库兼容:所提供的 JSON 架构可与广泛使用的开源和商业库、应用程序和服务配合使用,以了解数据需求、创建数据映射、生成用户界面,并在提交给亚马逊之前验证商品信息数据。
-
本地化展示详情:提供的 JSON 架构包括显示标签和任何商城支持的区域设置中的属性描述。
-
产品类型建议:商品类型定义 API 提供建议以帮助您选择最适用的商品类型。这些建议基于任何商城支持的任何地区(如果有)的产品标题。
术语
-
JSON 模式:JSON 架构是允许您注释和验证 JSON 文档的词汇表。有关详细信息,请参阅 json-schema.org。
-
元架构:元架构描述了 JSON 架构文档使用的词汇表。例如,亚马逊商品类型架构包括用于
selectors
和editable
的词汇表。此词汇表在元架构中进行了描述,使库和应用程序能够根据这些对标准 JSON 架构词汇表的扩展来理解和验证 JSON 数据。 -
产品类型:亚马逊商品类型是亚马逊目录中商品的分层分类。商品数据要求与商品的关联产品类型相关联。
教程:搜索可用的产品类型定义
使用本教程可搜索并识别亚马逊商品类型定义 API 中提供的特定亚马逊商城和销售伙伴账户类型的亚马逊商品类型。
先决条件
为了完成本教程,您需要:
-
您正在为其进行调用的销售伙伴的授权。请参阅为销售伙伴 API 应用程序授权了解更多信息。
-
批准您的开发者资料中的商品信息职权。
-
在应用程序注册页面为您的应用程序选择的商品信息职权。
搜索产品类型定义
调用 searchDefinitionsProductTypes
操作以搜索商品类型定义 API 中可用的商品类型。
请求参数
参数 | 示例 | 描述 | 必填项 |
---|---|---|---|
marketplaceIds |
ATVPDKIKX0DER |
以逗号分隔的用于请求的亚马逊商城标识符列表。 请参阅商城编号获取亚马逊商城标识符列表。 |
有帮助 |
keywords |
LUGGAGE |
以逗号分隔的关键字列表,用于搜索产品类型。 默认:当没有关键字或 itemName 提供了可用产品类型的完整列表。 |
没有帮助 |
locale |
en_US |
响应中显示名称的区域。 默认:商城的主要区域。 |
没有帮助 |
searchLocale |
en_US |
用于关键字的语言或 itemName 参数。默认:商城的主要区域。 |
没有帮助 |
请求示例
GET https://sellingpartnerapi-na.amazon.com/definitions/2020-09-01/productTypes
?marketplaceIds=ATVPDKIKX0DER
&keywords=LUGGAGE
&locale=en_US
&searchLocale=en_US
响应
成功的响应包括以下内容:
名称 | 示例 | 描述 |
---|---|---|
productTypes |
请参阅响应示例 | 与搜索请求相匹配的产品类型列表。 |
name |
LUGGAGE |
亚马逊商品类型的名称。 |
displayName |
Luggage |
亚马逊商品类型的易于理解的本地化描述。 |
marketplaceIds |
ATVPDKIKX0DER |
商品类型可用的亚马逊商城编号列表(在请求的商城编号内)。 |
productTypeVersion |
UHqSqmb4FNUk= |
亚马逊商品类型的版本详情... |
响应示例
{
"productTypes": [
{
"name": "LUGGAGE",
"displayName": "Luggage",
"marketplaceIds": [
"ATVPDKIKX0DER"
]
}
],
"productTypeVersion": "UHqSqmb4FNUk="
}
教程:获取产品类型定义建议
使用本教程从商品类型定义 API 中获取给定亚马逊商城、销售合作伙伴账户类型和商品名称的亚马逊产品类型推荐。
先决条件
为了完成本教程,您需要:
-
您正在为其进行调用的销售伙伴的授权。请参阅为销售伙伴 API 应用程序授权了解更多信息。
-
批准您的开发者资料中的商品信息职权。
-
在应用程序注册页面为您的应用程序选择的商品信息职权。
搜索产品类型定义
致电 searchDefinitionsProductTypes
操作以获取基于的产品类型推荐 itemName
来自商品类型定义 API。
请求参数
参数 | 示例 | 描述 | 必填项 |
---|---|---|---|
marketplaceIds |
ATVPDKIKX0DER |
以逗号分隔的用于请求的亚马逊商城标识符列表。 请参阅商城编号获取亚马逊商城标识符列表。 |
有帮助 |
itemName |
Softside Luggage with Spinner Wheels, Black |
获取商品类型推荐的 ASIN 的标题。 默认:当没有关键字或 itemName 提供了可用产品类型的完整列表。 |
没有帮助 |
locale |
en_US |
响应中显示名称的区域。 默认:商城的主要区域。 |
没有帮助 |
searchLocale |
en_US |
关键字使用的语言或 itemName 参数。默认:商城的主要区域。 |
没有帮助 |
请求示例
GET https://sellingpartnerapi-na.amazon.com/definitions/2020-09-01/productTypes
?marketplaceIds=ATVPDKIKX0DER
&itemName=Softside%20Luggage%20with%20Spinner%20Wheels%2C%20Black,
&locale=en_US
&searchLocale=en_US
响应
成功的响应包括以下内容:
名称 | 示例 | 描述 |
---|---|---|
productTypes |
请参阅示例回复 | 与搜索请求相匹配的产品类型列表。 |
name |
LUGGAGE |
亚马逊商品类型的名称。 |
displayName |
Luggage |
亚马逊商品类型的易于理解的本地化描述。 |
marketplaceIds |
ATVPDKIKX0DER |
商品类型可用的亚马逊商城编号列表(在请求的商城编号内)。 |
productTypeVersion |
UHqSqmb4FNUk= |
亚马逊商品类型的版本详情。 |
响应示例
{
"productTypes": [
{
"name": "LUGGAGE",
"displayName": "Luggage",
"marketplaceIds": [
"ATVPDKIKX0DER"
]
}
],
"productTypeVersion": "UHqSqmb4FNUk="
}
教程:检索产品类型定义
使用本教程可从商品类型定义 API 返回给定销售伙伴、亚马逊商品类型和亚马逊商城的亚马逊商品类型定义和相关架构。
先决条件
为了完成本教程,您需要:
-
您正在为其进行调用的销售伙伴的授权。请参阅授权销售伙伴 API 应用程序了解更多信息。
-
批准您的开发者资料中的商品信息职权。
-
在应用程序注册页面为您的应用程序选择的商品信息职权。
检索产品类型定义
调用 getDefinitionsProductType
操作以从商品类型定义 API 中检索亚马逊商品类型定义。
请求参数
路径参数
参数 | 示例 | 描述 | 必填项 |
---|---|---|---|
productType |
LUGGAGE |
亚马逊商品类型的名称。 类型:字符串 |
有帮助 |
查询参数
参数 | 示例 | 描述 | 必填项 |
---|---|---|---|
sellerId |
AXXXXXXXXXXXXX |
销售伙伴标识符。提供后,特定于卖家的要求和值将填充在商品类型定义架构中,如与销售伙伴关联的品牌名称。 类型:字符串 |
没有帮助 |
marketplaceIds |
ATVPDKIKX0DER |
以逗号分隔的亚马逊商城标识符列表。 注意:此时此参数仅限于一个 marketplaceID。 请参阅 商城 ID 获取亚马逊商城标识符列表。 类型:< string > array(csv) |
有帮助 |
productTypeVersion |
U1d1eorqMs3U= |
要检索的亚马逊商品类型定义的版本。可以使用 RELEASE_CANDIDATE 检索商品类型定义的预发行版本。如果目前没有预发行版本可用,将提供 LATEST 实时版本。默认: LATEST 类型:字符串 |
没有帮助 |
requirements |
LISTING |
为检索需求而设置的需求的名称。
LISTING 类型:enum( |
没有帮助 |
requirementsEnforced |
ENFORCED |
确定要求集的必需属性是否由产品类型定义架构强制执行。非强制性要求可对个别属性进行结构验证,而不需要所有必需属性(如进行部分更新)。
ENFORCED 类型:enum( |
没有帮助 |
locale |
en_US |
要检索其展示详情(标签和描述)的区域设置。默认为亚马逊商城的主要区域设置。 默认: 类型:enum( |
没有帮助 |
请求示例
GET https://sellingpartnerapi-na.amazon.com/definitions/2020-09-01/productTypes/LUGGAGE
?marketplaceIds=ATVPDKIKX0DER
&requirements=LISTING
&locale=en_US
响应
成功的响应包括以下内容:
名称 | 示例 | 描述 |
---|---|---|
metaSchema |
"metaSchema": { "link": { "resource": "https://...", "verb": "GET" }, "checksum": "QFQDmPwMARO7vwMEyLhOtw==" } |
用于检索亚马逊商品类型定义元架构文档的链接(有效期为 7 天)。 提供了校验和,以便与先前检索到的文档进行比较。 类型: |
schema |
"schema": { "link": { "resource": "https://...", "verb": "GET" }, "checksum": "TBr8ubaxXrUyay9hmxUXUw==" } |
用于检索亚马逊商品类型定义的 JSON 架构文档的链接(有效期为 7 天)。 提供了校验和,以便与先前检索到的文档进行比较。 类型: |
requirements |
LISTING |
亚马逊商品类型定义所适用的要求集的名称。
LISTING
|
requirementsEnforced |
ENFORCED |
确定要求集的必需属性是否由产品类型定义架构强制执行。非强制性要求可对个别属性进行结构验证,而不需要所有必需属性(如进行部分更新)。
ENFORCED 类型:enum( |
propertyGroups |
"propertyGroups": { "offer": { "title": "Offer", "description": "Product Offer", "propertyNames": [ "purchasable_offer" ] } } |
属性组定义亚马逊商品类型定义 JSON 架构文档中描述的属性的逻辑分段。这种分段可用于对用户界面中的属性进行分组、标识用途等。 属性组仅供参考,不会影响数据的结构或格式。 类型:< string, |
locale |
en_US |
亚马逊商品类型定义 JSON 架构文档中提供的展示详情(标签和描述)的区域设置。 类型:enum( |
marketplaceIds |
ATVPDKIKX0DER |
亚马逊商品类型定义适用的亚马逊商城编码。 类型:< 字符串 > 数组 |
productType |
LUGGAGE |
此商品类型定义所适用的亚马逊商品类型的名称。 类型:字符串 |
productTypeVersion |
U8L4z4Ud95N16tZlR7rsmbQ== |
亚马逊商品类型定义的版本。 类型:( |
displayName |
Luggage |
亚马逊商品类型的易于理解的本地化描述。 |
响应示例
{
"metaSchema": {
"link": {
"resource": "https://...",
"verb": "GET"
},
"checksum": "QFQDmPwMARO7vwMEyLhOtw=="
},
"schema": {
"link": {
"resource": "https://...",
"verb": "GET"
},
"checksum": "TBr8ubaxXrUyay9hmxUXUw=="
},
"requirements": "LISTING",
"requirementsEnforced": "ENFORCED",
"propertyGroups": {
"offer": {
"title": "Offer",
"description": "Product Offer",
"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",
"other_offer_image_locator_5"
]
},
"images": {
"title": "Images",
"description": "Physical images or URL's",
"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",
"swatch_product_image_locator"
]
},
"shipping": {
"title": "Shipping",
"description": "Information to determine shipping and storage of your product (e.g., package dimensions, weight, volume)",
"propertyNames": [
"item_dimensions",
"item_package_dimensions",
"item_package_weight"
]
},
"variations": {
"title": "Variations",
"description": "Variations that product will use",
"propertyNames": [
"parentage_level",
"child_parent_sku_relationship",
"variation_theme"
]
},
"safety_and_compliance": {
"title": "Safety & Compliance",
"description": "Information to indicate product compliance, hazardous materials, and legal and safety warnings (e.g., lithium batteries, choking hazards, Consumer Product Safety Information Act (CPSIA))",
"propertyNames": [
"country_of_origin",
"warranty_description",
"batteries_required",
"batteries_included",
"battery",
"num_batteries",
"number_of_lithium_metal_cells",
"number_of_lithium_ion_cells",
"lithium_battery",
"supplier_declared_dg_hz_regulation",
"hazmat",
"safety_data_sheet_url",
"item_weight",
"ghs",
"supplier_declared_material_regulation",
"california_proposition_65",
"pesticide_marking"
]
},
"product_identity": {
"title": "Product Identity",
"description": "Information to uniquely identify your product (e.g., UPC, EAN, GTIN, Product Type, Brand)",
"propertyNames": [
"item_name",
"brand",
"supplier_declared_has_product_identifier_exemption",
"externally_assigned_product_identifier",
"merchant_suggested_asin",
"item_type_keyword",
"item_type_name",
"model_number",
"manufacturer"
]
},
"product_details": {
"title": "Product Details",
"description": "Information and characteristics to describe the product to support search, browse and detail page content (e.g., bullets, product features, model, style name)",
"propertyNames": [
"product_description",
"bullet_point",
"generic_keyword",
"special_feature",
"style",
"department",
"target_gender",
"age_range_description",
"material",
"outer",
"fabric_type",
"lining_description",
"number_of_items",
"number_of_wheels",
"wheel",
"model_name",
"color",
"size",
"size_map",
"part_number",
"compliance_media"
]
}
},
"locale": "en_US",
"marketplaceIds": [
"ATVPDKIKX0DER"
],
"productType": "LUGGAGE",
"displayName": "Luggage",
"productTypeVersion": {
"version": "U8L4z4Ud95N16tZlR7rsmbQ==",
"latest": true,
"releaseCandidate": false
}
}
检索架构文档
在上一步中,检索到的亚马逊产品类型定义包括有关亚马逊产品类型的详细信息,以及用于检索元架构和商品类型架构文档的链接。提供的链接有效期为 7 天。
可以使用标准 HTTP 客户端以编程方式检索架构文档,也可以使用 Web 浏览器手动检索架构文档。
无法通过 Web 解析元架构名称
重要说明:亚马逊商品类型定义 JSON 架构文档通过名称引用元架构。某些 JSON 架构库尝试通过网络在线解析元架构名称,而亚马逊商品类型定义元架构 (v1) 不支持这种方法。这些库应配置为改用元架构的下载副本。有关详细信息,请参阅随附的亚马逊商品类型定义元架构 (v1) 文档。
常见问题
本文档介绍商品类型定义 API 的常见问题和详细信息。对于本文档未涵盖的问题或疑虑,请与销售伙伴 API 支持人员联系或在 GitHub 存储库上创建问题。
亚马逊商品类型定义有多新鲜?
除非指定之前的 productTypeVersion
,否则亚马逊商品类型定义始终描述最新的亚马逊目录要求。
是否所有亚马逊产品类型都可以使用产品类型定义 API?
亚马逊在商品类型定义 API 中不断扩大对新的和现有亚马逊商品类型的支持。有关可用亚马逊商品类型的最新列表,请使用商品类型定义 API。
使用的是哪个版本的 JSON 架构?
亚马逊商品类型定义 JSON 架构扩展了 JSON 架构 2019-09。有关详细信息,请参阅随附的亚马逊商品类型定义元架构 (v1) 文档。
如何利用 JSON 架构的未来版本?
随着商品类型定义 API 采用未来版本的 JSON 架构,商品类型定义 API 和亚马逊商品类型定义元架构也将随之发布新版本。
商品类型定义 API 或亚马逊商品类型定义元架构的现有版本不会采用 JSON 架构的未来版本。
商品类型定义 JSON 架构是否包含自定义词汇表?
大多数亚马逊目录要求都是使用标准 JSON 架构 2019-09词汇表来描述的。但是,有一些要求需要使用自定义词汇来扩展 JSON 架构。有关详细信息,请参阅随附的亚马逊商品类型定义元架构 (v1)。
我是否需要对自定义词汇实施验证?
亚马逊商品类型定义元架构 (v1) 使用自定义词汇来全面描述亚马逊目录要求。使用自定义数据验证数据可以防止在向亚马逊提交数据之前发生大多数与商品信息相关的问题。不过,是否实施这种验证取决于您。如果不实施这种验证,向亚马逊提交数据可能会在提交到亚马逊后产生与商品信息相关的问题。
是否需要自定义代码才能使用 JSON 架构?
自定义代码的数量取决于您的应用程序。示例场景:
-
使用带有自定义词汇验证功能的开源库:利用开源库来处理大多数 JSON 架构验证,意味着需要自定义代码才能从商品类型定义 API 中检索架构、实施自定义词汇表验证以及与开源库集成。
-
使用开源库而不验证自定义词汇表:利用开源库处理大多数 JSON 架构验证,意味着需要自定义代码才能从商品类型定义 API 中检索架构,并与开源库集成。
有哪些开源库可用?
有数十种开源库和实施可用于验证数据、呈现用户界面和生成代码。有关完整列表,请参阅 JSON 架构实施。
亚马逊不直接支持或认可任何特定的开源或商业库和实施。本文档中提供的示例仅供参考。
有哪些示例可用于使用商品类型架构验证数据?
随附的亚马逊商品类型定义元架构 (v1) 文档包括与开源库集成的示例,用于使用 .NET (C#)、Java 和 JavaScript (Node.js) 中的自定义词汇表来验证数据。
如何报告有关亚马逊商品类型定义的问题?
有关特定于商品类型定义 API 或亚马逊商品类型定义 JSON 架构内容的问题,请与销售伙伴 API 支持人员联系。
Updated 23 days ago