商品タイプ定義API v2020-09-01ユースケースガイド
Amazonカタログの商品タイプの属性とデータ要件にプログラムでアクセスできます。
APIバージョン:2020-09-01
商品タイプ定義APIとは何ですか。
商品タイプ定義のためのSelling Partner API(商品タイプ定義API)を使用すると、Amazonの商品タイプ定義を検索して取得できます。Amazon商品タイプ定義は、JSONスキーマを使用してAmazonカタログ内の商品の属性とデータ要件を記述します。
商品タイプ定義APIが提供するJSONスキーマフォーマットの詳細については、付属のAmazon商品タイプ定義メタスキーマ(v1)ドキュメントを参照してください。
を参照してください プロダクトタイプ定義 API v2020-09-01 リファレンス API 操作および関連するデータ型とスキーマの詳細については、こちらを参照してください。
主な機能
-
JSONスキーマ:商品タイプ定義APIは、特定のAmazon商品タイプに関する出品者に依存しない要件を記述したJSONスキーマを提供します。これには、データ形式、属性制約(要件、長さ、最大数など)、条件付きで適用される属性制約(バッテリーが含まれるかどうか、バッテリーの種類など)が含まれます。
-
オープンソースライブラリーとの互換性:提供されているJSONスキーマは、広く利用されているオープンソースや商用ライブラリ、アプリケーション、サービスと併用して、データ要件の理解、データマッピングの作成、ユーザーインターフェイスの生成、Amazonへの送信前の出品データの検証を行うことができます。
-
ローカライズされたプレゼンテーションの詳細:提供されるJSONスキーマには、あらゆるマーケットプレイスでサポートされるロケールでの属性の表示ラベルと説明が含まれています。
-
推奨製品タイプ: 製品タイプ定義 API は、最も適切な製品タイプを選択するのに役立つ推奨事項を提供します。これらのレコメンデーションは、すべてのマーケットプレイスでサポートされているロケールの商品タイトルに基づいています(可能な場合)。
用語
-
JSONスキーマ:JSONスキーマはJSONドキュメントに注釈を付けたり検証したりすることができるボキャブラリーです。詳細については json-schema.orgを参照してください。
-
メタスキーマ:メタスキーマはJSONスキーマドキュメントで使用されるボキャブラリーを記述するものです。たとえば、Amazon商品タイプスキーマには
selectors
およびeditable
のボキャブラリーが含まれています。このボキャブラリはメタスキーマで記述され、ライブラリーやアプリケーションが標準のJSONスキーマのボキャブラリーに対するこれらの拡張に基づいてJSONデータを理解し、検証できるようになります。 -
商品タイプ:Amazon商品タイプは、Amazonカタログ内の商品を階層的に分類したものです。商品データ要件は、関連する商品タイプに関連付けられています。
チュートリアル:検索可能な商品タイプ定義
このチュートリアルを使用して、Amazonマーケットプレイスおよび出品パートナーアカウントの種類について、商品タイプ定義APIで利用できるAmazon商品タイプの検索、識別を行えます。
前提条件
このチュートリアルを完了するには、以下が必要です。
-
呼び出し先の出品パートナーからの承認。詳細については、Selling Partner APIアプリケーションの認証をご覧ください。
-
開発者プロフィールでの商品出品のロールの承認。
-
アプリケーションのアプリ登録ページで選択された商品出品ロール。
製品タイプ定義を検索
searchDefinitionsProductTypes
オペレーションを呼び出すことで、商品タイプ定義APIの中の利用可能な商品タイプを検索することができます。
リクエストパラメーター
パラメーター | 例 | 説明 | 必須 |
---|---|---|---|
marketplaceIds |
ATVPDKIKX0DER |
リクエストのAmazonマーケットプレイスIDをカンマで区切ったリスト。 AmazonマーケットプレイスIDのリストについては、マーケットプレイスIDを参照してください。 |
はい |
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 |
Amazonの商品タイプの名称。 |
displayName |
Luggage |
人間が読める形式でローカライズされた Amazon 商品タイプの説明。 |
marketplaceIds |
ATVPDKIKX0DER |
商品タイプが利用可能なAmazonマーケットプレイス識別子のリスト(要求されたマーケットプレイス識別子の範囲内)。 |
productTypeVersion |
UHqSqmb4FNUk= |
Amazon 製品タイプのバージョン詳細.. |
レスポンスの例
{
"productTypes": [
{
"name": "LUGGAGE",
"displayName": "Luggage",
"marketplaceIds": [
"ATVPDKIKX0DER"
]
}
],
"productTypeVersion": "UHqSqmb4FNUk="
}
チュートリアル:製品タイプ定義の推奨事項を取得
このチュートリアルを使用して、特定のAmazonマーケットプレイス、販売パートナーアカウントのタイプ、および商品名について、Product Type DefinitionsAPIからAmazonの推奨商品タイプを取得します。
前提条件
このチュートリアルを完了するには、以下が必要です。
-
呼び出し先の出品パートナーからの承認。詳細については、Selling Partner APIアプリケーションの認証をご覧ください。
-
開発者プロフィールでの商品出品のロールの承認。
-
アプリケーションのアプリ登録ページで選択された商品出品ロール。
製品タイプ定義を検索
に電話してください searchDefinitionsProductTypes
に基づいて推奨製品タイプを取得するオペレーション itemName
製品タイプ定義 API から。
リクエストパラメーター
パラメーター | 例 | 説明 | 必須 |
---|---|---|---|
marketplaceIds |
ATVPDKIKX0DER |
リクエストのAmazonマーケットプレイスIDをカンマで区切ったリスト。 AmazonマーケットプレイスIDのリストについては、マーケットプレイスIDを参照してください。 |
はい |
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 |
Amazonの商品タイプの名称。 |
displayName |
Luggage |
人間が読める形式でローカライズされた Amazon 商品タイプの説明。 |
marketplaceIds |
ATVPDKIKX0DER |
商品タイプが利用可能なAmazonマーケットプレイス識別子のリスト(要求されたマーケットプレイス識別子の範囲内)。 |
productTypeVersion |
UHqSqmb4FNUk= |
Amazon 製品タイプのバージョン詳細。 |
レスポンスの例
{
"productTypes": [
{
"name": "LUGGAGE",
"displayName": "Luggage",
"marketplaceIds": [
"ATVPDKIKX0DER"
]
}
],
"productTypeVersion": "UHqSqmb4FNUk="
}
チュートリアル:商品タイプ定義の取得
このチュートリアルを使用して、特定の出品パートナー、Amazon商品タイプ、およびAmazonマーケットプレイスの商品タイプ定義および関連スキーマを商品タイプ定義APIから返します。
前提条件
このチュートリアルを完了するには、以下が必要です。
-
呼び出し先の出品パートナーからの承認。詳細については、Selling Partner APIアプリケーションの認証をご覧ください。
-
開発者プロフィールでの商品出品のロールの承認。
-
アプリケーションのアプリ登録ページで選択された商品出品ロール。
製品タイプ定義を取得
getDefinitionsProductType
オペレーションを呼び出し、商品タイプ定義APIの中からAmazon商品タイプ定義を取得します。
リクエストパラメーター
パスパラメーター
パラメーター | 例 | 説明 | 必須 |
---|---|---|---|
productType |
LUGGAGE |
Amazonの商品タイプの名称。 タイプ:文字列 |
はい |
クエリーパラメーター
パラメーター | 例 | 説明 | 必須 |
---|---|---|---|
sellerId |
AXXXXXXXXXXXXX |
出品パートナー識別子。指定すると、出品パートナーに関連するブランド名など、出品者固有の要件と値が商品タイプ定義スキーマに入力されます。 タイプ:文字列 |
いいえ |
marketplaceIds |
ATVPDKIKX0DER |
Amazon マーケットプレイス ID のカンマ区切りリスト。 注:現時点では、このパラメーターは 1 つのマーケットプレイス ID に制限されています。 を参照してください マーケットプレイス ID Amazon マーケットプレイス ID のリスト用。 タイプ: <文字列>配列(CSV) |
はい |
productTypeVersion |
U1d1eorqMs3U= |
取得するAmazon商品タイプ定義のバージョン。商品タイプ定義のプレリリース版は、RELEASE_CANDIDATE で取得できます。プレリリース版が利用できない場合は、 LATEST ライブバージョンが提供されます。デフォルト: LATEST タイプ:文字列 |
いいえ |
requirements |
LISTING |
要件を取得する要件セットの名前。
LISTING タイプ:列挙( |
いいえ |
requirementsEnforced |
ENFORCED |
要件セットの必須属性が商品タイプ定義スキーマによって適用されているかどうかを識別します。非強制要件により、必要な属性がすべて存在しなくても(部分的な更新など)、個々の属性の構造的検証が可能になります。
ENFORCED タイプ:列挙( |
いいえ |
locale |
en_US |
プレゼンテーションの詳細(ラベルと説明)を取得するためのロケール。デフォルトはAmazonマーケットプレイスのプライマリロケールです。 デフォルト: タイプ:列挙( |
いいえ |
リクエストの例
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==" } |
Amazon商品タイプ定義メタスキーマドキュメントを取得するリンク(7日間有効)。 以前に取得したドキュメントとの比較用にチェックサムが提供されています。 タイプ: |
schema |
"schema": { "link": { "resource": "https://...", "verb": "GET" }, "checksum": "TBr8ubaxXrUyay9hmxUXUw==" } |
Amazon商品タイプ定義のJSONスキーマドキュメントを取得するためのリンク(7日間有効)。 以前に取得したドキュメントとの比較用にチェックサムが提供されています。 タイプ: |
requirements |
LISTING |
Amazon商品タイプ定義が適用される要件セットの名称。
LISTING
|
requirementsEnforced |
ENFORCED |
要件セットの必須属性が商品タイプ定義スキーマによって適用されているかどうかを識別します。非強制要件により、必要な属性がすべて存在しなくても(部分的な更新など)、個々の属性の構造的検証が可能になります。
ENFORCED タイプ:列挙( |
propertyGroups |
"propertyGroups": { "offer": { "title": "Offer", "description": "Product Offer", "propertyNames": [ "purchasable_offer" ] } } |
プロパティグループは、Amazon商品タイプ定義JSONスキーマドキュメントで説明されているプロパティの論理的セグメンテーションを定義します。このセグメンテーションは、ユーザーインターフェイス内のプロパティのグループ化、目的の特定などに使用できます。 プロパティグループは情報提供のみを目的としており、データの構造や形式には影響しません。 タイプ:< 文字列, |
locale |
en_US |
Amazon商品タイプ定義JSONスキーマドキュメントで提供されるプレゼンテーションの詳細(ラベルと説明)のロケール。 タイプ:列挙( |
marketplaceIds |
ATVPDKIKX0DER |
Amazon商品タイプ定義が適用されるAmazonマーケットプレイス識別子。 タイプ:<文字列>配列 |
productType |
LUGGAGE |
この商品タイプ定義が適用されるAmazon商品タイプの名称。 タイプ:文字列 |
productTypeVersion |
U8L4z4Ud95N16tZlR7rsmbQ== |
Amazon商品タイプ定義のバージョン。 タイプ:( |
displayName |
Luggage |
人間が読める形式でローカライズされた Amazon 商品タイプの説明。 |
レスポンスの例
{
"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
}
}
スキーマドキュメントを取得
前のステップで取得したAmazon商品タイプ定義には、Amazon商品タイプに関する詳細情報と、メタスキーマと商品タイプスキーマのドキュメントを取得するためのリンクが含まれています。提供されたリンクは7日間有効です。
スキーマドキュメントは、標準のHTTPクライアントを使用してプログラムで取得することも、ウェブブラウザーを使用して手動で取得することもできます。
メタスキーム名はウェブ経由で解決できない
重要な注意事項:Amazon商品タイプ定義JSONスキーマドキュメントは、メタスキーマを名前で参照します。JSONスキーマライブラリーの中には、ウェブ経由でメタスキーマ名をオンラインで解決しようとするものがあり、 Amazon商品タイプ定義メタスキーマ(v1)はサポートしていません。これらのライブラリーでは、ダウンロードしたメタスキーマのコピーを代わりに使用するように設定する必要があります。詳細は、Amazon商品タイプ定義メタスキーマ(v1)ドキュメントを参照してください。
よくあるご質問
このドキュメントでは、商品タイプ定義APIに関する一般的な質問と詳細情報について説明します。このドキュメントに記載されていない質問や懸念については、Selling Partner APIサポートに問い合わせるか、GitHubリポジトリーに問題を作成してください。
Amazonの商品タイプ定義はどのくらい頻繁に更新されていますか。
前回の productTypeVersion
を指定しない限り、Amazon商品タイプの定義には、常に最新のAmazonカタログ要件が記載されています。
商品タイプ定義APIでは、すべてのAmazonの商品タイプを利用できますか。
Amazonは、商品タイプ定義APIにおける、新規および既存のAmazon商品タイプのサポートを継続的に拡大しています。利用可能なAmazon商品タイプの最新リストについては、商品タイプ定義APIを使用してください。
どのバージョンのJSONスキーマが使用されていますか。
Amazon商品タイプ定義JSONスキーマは、JSONスキーマ2019-09を拡張しています。詳細は、Amazon商品タイプ定義メタスキーマ(v1) ドキュメントを参照してください。
JSONスキーマの将来のバージョンはどのように使用されますか。
JSONスキーマの将来のバージョンが商品タイプ定義APIに採用されるとき、商品タイプ定義APIおよびAmazon商品タイプ定義メタスキーマの新しいバージョンのリリースも同時に行われる予定です 。
JSONスキーマの将来のバージョンは、商品タイプ定義APIまたはAmazon商品タイプ定義メタスキーマの既存のバージョンでは採用されません。
商品タイプ定義JSONスキーマにはカスタムボキャブラリーが含まれていますか。
ほとんどのAmazonカタログ要件は、標準JSONスキーマ2019-09ボキャブラリーを使用して記述されています。ただし、JSONスキーマをカスタムボキャブラリーを使用して拡張する必要がある要件がいくつかあります。詳細は、Amazon商品タイプ定義メタスキーマ(v1)ドキュメントを参照してください。
カスタムボキャブラリーの検証を導入する必要がありますか。
Amazon商品タイプ定義メタスキーマ(v1)はカスタムボキャブラリーを使用してAmazonカタログの要件を詳しく説明します。カスタムデータを使用してデータを検証すると、Amazonに送信する前に、ほとんどの出品関連の問題の発生を防ぐことができます。こうした検証を行うかどうかは任意ですが、この検証を導入しない場合、Amazonに送信した後に出品関連の問題が発生する可能性があります。
JSONスキーマを使用するにはカスタムコードが必要ですか。
カスタムコードの量はアプリケーションによって異なります。シナリオ例:
-
カスタムボキャブラリーの検証を伴うオープンソースライブラリーの使用:オープンソースライブラリーを使用してほとんどのJSONスキーマ検証を処理するということは、商品タイプ定義APIからのスキーマの取得、カスタムボキャブラリーの検証、オープンソースライブラリとの統合のために、カスタムコードが必要になるということです。
-
カスタムボキャブラリーの検証なしでのオープンソースライブラリの使用:オープンソースライブラリを活用してほとんどのJSONスキーマの検証を処理するということは、Product Type Definition APIからのスキーマの取得、オープンソースライブラリーとの統合のために、カスタムコードが必要になるということです。
どのようなオープンソースライブラリーが利用可能ですか。
データの検証、ユーザーインターフェイスのレンダリング、およびコードの生成のために、多数のオープンソースライブラリーや機能が利用可能です。そのすべてのリストを参照するには、JSONスキーマの導入をご覧ください。
Amazonは、特定のオープンソースまたは商用ライブラリーやソフトウェアを直接サポートまたは推奨していません。このドキュメントに記載されている例はあくまで参照用です。
商品タイプスキーマによるデータの検証にはどのような例がありますか。
付随するAmazon商品タイプ定義メタスキーマ(v1)ドキュメントには、.NET(C#)、Java、JavaScript(Node.js)のカスタムボキャブラリーを使用してデータを検証するための、オープンソースライブラリーとの統合例が含まれています。
Amazon商品タイプ定義に関する問題を報告するにはどうすればよいですか。
商品タイプ定義APIまたはAmazon商品タイプ定義JSONスキーマの内容特有の問題については、Selling Partner APIサポートにお問い合わせください。
Updated 23 days ago