Amazon ECS 4.0 解説1 RESTリクエストのパラメータ

アマゾンの新しいWEBサービス、Amazon E-Commerce Service 4.0は、AWS3.0から結構仕様が変わっているのですが、ECS4.0を使うために必要な情報をまとめてみます。

最初はRESTリクエスト(RESTとは?)を対象にしたいと思います。RESTでは、httpリクエストのURLとして、各種の問い合わせパラメーターを設定します。このパラメーターはAmazon Web Service 3.0から、がらっと変更されています。G-Toolsを作る際にも、このRESTパラメータを理解するのに結構時間がかかりました。

まずはRESTリクエストで問い合わせする先のAmazonのWEBサービスのURL

Amazon.co.jphttp://webservices.amazon.co.jp/onca/xml?
JPベータ版http://aws-beta.amazon.co.jp/onca/xml?
Amazon.comhttp://webservices.amazon.com/onca/xml?

このURLの後にGETパラメータとして、問い合わせパラメータを指定します。
まずは、すべてのリクエストに共通のパラメータ。これはすべての種類のリクエストに共通して必要です。

Service=AWSECommerceService
&SubscriptionId=[登録時のsubscription ID]
&AssociateTag=[アソシエイトID]

ここまでを追加したRESTリクエストのサンプルは以下のようになります。このURLでリクエストすると、当然ですが「検索用のパラメータが足りないよ!」と怒られてしまいます。ただし、ECS 4.0からは、かなり具体的にエラーメッセージを表示してくれるようになっているので、何のパラメータが足りないかは、すぐに把握することができます。この場合は、The Operation parameter が無いよと注意されます。

サンプル リクエスト

それでは、Operation Parameterを追加してみましょう。

The Operation parameter : 問い合わせの種類
&Operation= ItemSearch (商品名、著者名などで検索)
ItemLookup (ASINなどのItemIdで、商品を検索)
ListSearch (リストマニア情報を検索)
ListLookup (リストマニア情報をID検索)
SimilarityLookup (関連商品の検索)
Help (HELPを表示。開発ツールなど用)

CartCreate (リモートショッピングカートを作成)
CartClear (カートをクリア)
CartAdd (カートに商品追加)
CartModify (カート内の情報変更)
CartGet (カートを取得)

TransactionLookup(USのみ)
CustomerContentSearch(USのみ)
CustomerContentLookup(USのみ)
SellerListingLookup (USのみ)
SellerLookup (USのみ)
SellerListingSearch (USのみ)

USのみの機能もありますが、通常は、ItemSearchとItemLookupを主に使うことが多いでしょう。ItemSearchは、商品名や、著者、アルバムの曲名など、キーワード検索の際に指定します。ItemLookupはASIN番号などを指定して、特定の商品を検索するのが主な用途です。

2番目は、検索結果として、どのような情報を取得したいか?というResponseGroupの指定です。AWS3.0ではSmall, Medium, Largeという3段階でしか取得情報のバリエーションを選べませんでしたが、Amazon ECS4.0では、きめ細かに取得する情報を指定できます。



ResponseGroup : 取得したい情報

&ResponseGroup=

Request (RESTリクエストのパラメータ)
ItemIds (商品のASIN、商品数、ページ数)
Small (最小限の情報)
Medium (中くらいの情報)
Large (沢山の情報)

ItemAttributes (商品の詳細情報)
EditorialReview (商品の紹介文)
Reviews (カスタマーレビュー)
ListmaniaLists (リストマニア)
Tracks (音楽CDの楽曲情報)
SalesRank (売り上げランキング)
BrowseNodes (商品がリストされるカテゴリ)
Images(商品画像のURL)
Similarities(関連商品)

OfferFull(在庫情報や価格など)
Offers (新品かユーズドかなど)
OfferSummary  
Accessories(デジカメなどのアクセサリのASIN)
Variation (以下をまとめて)
VariationMinimum(シャツのサイズ違いなど関連ASIN)
VariationSummary(最高値や最安値、出品数など)

上記のパラメータは組み合わせて使うことが可能で、例えば、最低限の情報と、関連商品の情報だけが欲しいときは、&ResponseGroup=Small,Similarities などのようにカンマ(,)で区切って複数のパラメータを指定することが出来ます。

3番目に、検索結果をどのようなフォーマットでもらいたいかを指定します。主には2種類のフォーマットが想定できるでしょう。PerlやPHPなどスクリプトで処理するためにXMLデータで受け取りたい場合と、ブラウザでそのまま表示などするためにHTMLとして出力してもらいたい場合です。

ContentType :フォーマット
&ContentType= text/xml (結果をXMLで取得したい場合) 
text/html (結果をHTMLで取得したい場合)

4番目は、取得するページの指定です。キーワード検索や、ブラウズノード検索など、複数の商品が検索結果として返ってきます。通常は、1ページにつき10個の商品が検索結果として返ってきます。リクエスト・パラメータを組み合わせることで、10個以上の商品を取得することもできるのですが、それはまたの機会に。
例えば「インターネット」という単語で検索した場合、4871件の商品がマッチするので、480ページあることになります。
このページ指定は、主にナビゲーションなどで利用するのですが、特定のページを指定する必要が無い場合でも、Page=1と指定しておく必要があります。

Page : 取得する検索結果のページ指定
&Page= 1 ( 1~検索結果の数に応じて任意の数字)


5番目に忘れてはいけない項目として、Versionがあります。これは新しくECS4.0から導入されたパラメータで、Amazonのサーバがアップデートするにしたがって、Versionもあがっていきます。Versionを指定しないと、WEBサービスからのレスポンスデータが変更された場合など、自分の開発したアプリに影響が出る可能性が高いので、かならず指定しましょう。
特に、トラブルになりやすいのは、XSLT機能を利用している時です。変換ルールとして自作するXSLT内ではXMLのnamespaceとしてVersionを指定するのですが、RESTリクエスト内のVersionと、XSLT内のnamespaceで指定するバージョンが異なっていると、XSLT変換が行われず、期待するレスポンスを受け取れません。
RESTリクエストでVersionを指定しないと、デフォルトとして最新のVersionとみなされるので、スクリプトを開発したときは、問題なく動いていても、アマゾンが新しいVersionにアップデートした段階で、動作しなくなります。
ここはECS4.0のハマリどころなので(僕もはまりました)、しっかりVersionを指定しましょう。

Version : ECSのバージョン情報
&Version= 2004-10-04 (任意のバージョンを指定)


6番目は、検索したい商品の種類を指定します。Blendedを指定すると、すべての商品から検索されますが、1種類あたりの商品数が少なくなってしまうので、詳細検索の際には各商品種別を指定する必要があります。指定できる商品種類は、Amazonの国ごとに違うのですが、日本では下記の種類が指定できるようです。最近、発表された、おもちゃ&ホビーもありますね。

&SearchIndex : 商品の種類
&SearchIndex= Blended (すべての商品)
Books (和書)
Music (音楽)
MusicTracks (曲名から調べる)
Classical (クラシック音楽)
Video (DVD&VHS)
DVD (DVD)
VHS (VHS)
VideoGames (ゲーム)
Electronics (家電 エレクトロニクス)
Kitchen (ホーム&キッチン)
Toys (おもちゃ&ホビー)
Software (PC ソフトウェア)

7番目は、もしXSLT変換機能を利用する場合は、XSLTファイルのURLを指定します。XSLTを使用せず、XMLを直接取得したい場合は、指定の必要はありません。

&Style : XSLTファイルのURL
&Style= http://www.my-web.com/xsl/my.xsl (自分で作成したXSLTファイルのURL)


ここまでは、ほとんどのRESTリクエストに共通の項目。最後は、検索のキーとなる値を指定します。こちらはOperationの種類によるのですが、ひとまず最もよく使いそうなものだけを紹介します。
Operation=ItemSearchの場合は、キーワードによる検索か、BrowseNodeの指定による、ベストセラー商品の検索がよくつかわれるでしょう。&Keywords=、あるいは&BrowseNodeのどちらかを指定して検索します。

Operation=ItemSearchの場合の検索キー
&Keywords= 検索したいキーワード
&BrowseNode= BrowseNode番号 (Amazonのカテゴリごとのベストセラーを取得)

Operation=ItemLookupを選択した場合は、ASINなどのID番号の種類と、番号の2種類を指定して検索します。

Operation=ItemLookupの場合の検索キー
&IdType=ASIN&ItemId= 検索したいASIN番号

以上のパラメータを組み合わせると、以下のようなREST検索用のURLとなります。

サンプル リクエスト


ECS4.0では、AWS3.0に比べると、パラメータは論理的に整理されているので、プログラムは組みやすくなっているのではないでしょうか。ただし、検索で指定するパラメーターが増えて、最初はかなりとっつきにくい感じがします。自分でも、すぐパラメーターが分からなくなってしまうので、このページをまとめたという感じです。

最後にBrowseNode検索で指定するBrowseNode IDの一覧を参考までに整理しておきます。

&SearchIndex=Books&BrowseNode=
466300新刊
466284文学 小説
571582哲学 地域
571584社会 政治
492152ノンフィクション
466286旅行 地理
466282ビジネス キャリア
492054投資
466298コンピューター ネット
466294アート 写真集
466296エンターテイメント
466292スポーツ ホビー
466304ホーム ファミリー
466302外国語
466306子供向け
466280マンガ アニメ
746102楽譜
&SearchIndex=DVD&BrowseNode=
562014邦画
562016洋画
562018音楽
562020アニメ
562022ホビー フィットネス
562024スポーツ
562026ファミリー
562028ドキュメンタリー
564522DVDボックス
896246アダルト
&SearchIndex=Electronics&BrowseNode=
3371371デジタル カメラ
3371441DVDプレーヤー
3371411ポータブル音楽機器
3371341コンピューター
3371351PC周辺機器
3371361プリンタ スキャナ
3371381ネットワーク機器
3371401PDA
3371421アクセサリ
3371391メモリーカード HDD
3371431オーディオ ビジュアル
&SearchIndex=Music&BrowseNode=
569170J-POP
569290ポップ
569292ロック
569298ハードロック
562050ブルース カントリー
569318ソウル R&B
569320ヒップホップ
569322ダンス
562052ジャズ フュージョン
562056ワールド
562064ニューエイジ
562058サウンドトラック
562060アニメ
562062子供 ファミリー
569174バラード
569186伝統音楽
899296スポーツ
&SearchIndex=VideoGames&BrowseNode=
637874プレイステーション2
637876プレイステーション
637878Nintendo Gamecube
637880ゲームボーイ アドバンス
637882ゲームボーイ
639096Xbox
637886その他