REST リクエストの構造

Product Advertising API のRESTリクエストは、次の例に示すようにURLです。

http://ecs.amazonaws.com/onca/xml?Service=AWSECommerceService&Operation=ItemSearch&
AWSAccessKeyId=[アクセスキー ID]&AssociateTag=[ID]&SearchIndex=Apparel&
Keywords=Shirt

このリクエストのIDを実際のIDで置き換え、ブラウザにURL全体を入力すると、Product Advertising API にリクエストが送信されます。

上の例は、リクエストをブラウザに入力するフォームですが、読むのは困難です。そのため、このガイドでは、同じリクエストを次のように表記します。

http://ecs.amazonaws.com/onca/xml?
Service=AWSECommerceService&
Operation=ItemSearch&
AWSAccessKeyId=[アクセスキー ID]&
AssociateTag=[ID]&
SearchIndex=Apparel&
Keywords=Shirt

リクエストの一般的な形式

Product Advertising API のどのリクエストにも共通部分がありますが、それ以外は、リクエストで使用するパラメータによって変更されます (次の例を参照) 。

リクエスト内の変更されない項目

前の例の最初の2行には、エンドポイント http://ecs.amazonaws.com/onca/xml と、サービス名 AWSECommerceService が含まれています。

Amazon は、Product Advertising API 以外にも、Mechanical Turk や S3 など、多くの Web サービスをホストとして処理しています。リクエスト内のサービス名は、リクエストを Product Advertising API に送ることを Web サーバに指示します。この行は、どの国のリクエストであっても、Product Advertising API のあらゆるリクエストで共通です。

Service=AWSECommerceService&

エンドポイントの値は各国のサイトごとに異なりますが、エンドポイントはサイトあたり2つしかありません。そのうちの1つは、もう1つのエンドポイントのセキュアバージョンです。次の表に、Product Advertising API のリクエストで使われるエンドポイントの一覧を示します。

エンドポイント
CA (カナダ)

http://ecs.amazonaws.ca/onca/xml

https://aws.amazonaws.ca/onca/xml

DE (ドイツ)

http://ecs.amazonaws.de/onca/xml

https://aws.amazonaws.de/onca/xml

FR (フランス)

http://ecs.amazonaws.fr/onca/xml

https://aws.amazonaws.fr/onca/xml

JP (日本)

http://ecs.amazonaws.jp/onca/xml

https://aws.amazonaws.jp/onca/xml

UK (イギリス)

http://ecs.amazonaws.co.uk/onca/xml

https://aws.amazonaws.co.uk/onca/xml

US (アメリカ)

http://ecs.amazonaws.com/onca/xml

https://aws.amazonaws.com/onca/xml

次の例に示すように、エンドポイントは Product Advertising API の全てのリクエストで共通です。

http://ecs.amazonaws.com/onca/xml

3行目と4行目は、リクエストの送信者を表します。AWSAccessKey Id は必須で、リクエストの送信者を識別するのに使われます。AWS Access Key ID は、Product Advertising API に申し込んだときに付与されます。

他のIDである AssociateTag はオプションです。これはアソシエイトのIDです。アソシエイト・プログラムのメンバーとして、カスタマーの購入に対する紹介料を受け取るには、アソシエイトタグを各リクエストで指定する必要があります。

リクエスト内の変更される項目

リクエストのその他の項目は、実行するオペレーションによって大きく異なります。しかし、次の図に示すようにあるパターンに従います。

Operation パラメータは必須です。値は、Product Advertising API のいずれかのオペレーションです。これらのオペレーションについては、このガイド全体で説明されています。

最後の数行のオペレーションパラメータは、オペレーションで必要なパラメータの代表的なものと、オペレーションが使用できるオプションのパラメータです。リクエストには0個以上(最大10個)のパラメータを含めることができます。これらのパラメータについては、Product Advertising API API Reference Guide の各オペレーションの説明をご参照ください。

レスポンスグループ

Product Advertising API の全てのオペレーションでオプションで指定する特別なパラメータが ResponseGroup です。レスポンスグループは、リクエストによって返される情報の種類を制御します。例えば、Large レスポンスグループを指定すると、レスポンスに含まれる商品の詳細にわたる情報が返されますが、レスポンスグループ Medium と Small で返される情報はそこまで詳しいものではありません。

これらの一般的なレスポンスグループに加えて、さらに詳細なレスポンスグループがあります。例えば、レスポンスに含まれる商品の画像を取得したい場合は、Image レスポンスグループをリクエストで指定します。価格情報が必要な場合は、Offer レスポンスグループをリクエストで指定します。ブラウズノード情報を取得するには、BrowseNode レスポンスグループを指定します。レスポンスグループで限定することで、必要な情報だけを取得できます。

Product Advertising API の各オペレーションは、Product Advertising API の全レスポンスグループのサブセットだけを扱うことができます。Product Advertising API の各オペレーションで使用できる有効なレスポンスグループについては、Product Advertising API API Reference Guide をご参照ください。

Product Advertising API の全てのオペレーションは、デフォルトでいくつかのレスポンスグループを使用します。そのため、追加のレスポンスグループの指定はオプションです。Product Advertising API のどのオペレーションでもRequest レスポンスグループを使用します。これは、リクエストで送信したオペレーション名と入力パラメータをそのまま返すものです。これ以外にデフォルトで使用されるレスポンスグループは、オペレーションによって異なります。例えば、 CartCreate, CartAdd, および CartModify は、デフォルトで Cart レスポンスグループを使用します。API Reference Guide には、各オペレーションで使用されるデフォルトのレスポンスグループの一覧が記載されています。

このため、このガイドのリクエストを読む際に、Operation パラメータと、Product Advertising API の指定したオペレーションに関連する全ての必須およびオプションのパラメータをすぐに確認できます。