.NETプログラミング研究 第75号 †.NET Tips †Amazon E-Commerce Serviceを使用する †DoboWikiでは様々なWebサービスを紹介していますが、その中でも横綱格といえるのが、Amazonの提供するWebサービスE-Commerce Service（ECS）でしょう。ECSは利用者の多いサービスであり、またこれから使いたいと考えている方も多いでしょう。ECSの機能はあまりに膨大で、奥が深いですが、その割にはドキュメントの説明が足りないように思われます。そこで今回は私が実際にECSをいろいろと使ってみて分かったことを含め、ECSの使い方について説明します。 ECSはSOAPとRESTの2種類のインターフェイスを提供していますが、ここではSOAPを使用します。またSOAPを使用したWebサービスにアクセスする方法については、「.NETプログラミング研究」の第72号で説明しましたので、すでに知識があるものとさせていただきます。 プロキシクラスの作成 †Wsdl.exeなどで作成されるプロキシクラスについて、注意すべき点を幾つか挙げます。 ECSのバージョンについて プロキシクラスを作成する際に指定するWSDLですが、Amazon.co.jpのECSの場合は、次の場所にあります。 http://webservices.amazon.com/AWSECommerceService/JP/AWSECommerceService.wsdl ただしこれは最新のバージョンのWSDLを返します。あるバージョンのECSの下では正常に動いていたアプリケーションが、ECSのバージョンがアップデートされたら動かなくなるということは十分考えられます。ECSのWSDLはバージョンごとに別々のURLでも公開されていますので、通常は上記のようなURLのWSDLを使うのではなく、バージョンが指定されたWSDLを指定すべきです。例えばECSのバージョンが2006-09-13のAmazon.co.jpのWSDLは次の場所にあります。 http://webservices.amazon.com/AWSECommerceService/2006-09-13/JP/AWSECommerceService.wsdl 補足：RESTの場合はVersionパラメータでECSのバージョンを指定します。 正しいプロキシクラスが作成されない Amazonの提供するWSDLを使用してプロキスクラスを作成し使用すると、エラーが発生し、全く使用できないことがあるようです。私が試したところでは、ECSのバージョン2006-06-28のWSDLでは正しいプロキシクラスが作成されないようでした。 このような場合は作成されたプロキスクラスを自分で修正して使用するとうまく行きます。しかし、Visual Studio 2005の「Web参照の追加」でプロキスクラスを作成するとプロキスクラスがファイルとして出力されませんので、修正は困難です。そのような場合は、Wsdl.exeを使ってプロキスクラスのファイルを実際に作成した方が良いかもしれません。 ともかく、提供されているWSDLによりVisual StudioやWsdl.exeで作成されるプロキシクラスがそのまま使えるとは限らないケースもあることを知っておいたほうがよいでしょう。 ...Specifiedプロパティ †プロキシクラスには名前が「Specified」で終わるbool型のプロパティが存在することがあります。例えば、ListLookupRequestクラスのListTypeSpecifiedなどです。このプロパティは、「Specified」以前の名前で表されるプロパティ（「ListTypeSpecified」であれば、「ListType」プロパティ）に値を設定したかを示すためのものです。例えばListTypeSpecifiedプロパティをfalseとしたならば、ListTypeプロパティを設定したとしてもその情報はリクエストに含まれず、無視されます。つまりListTypeをリクエストに加えるには、ListTypeSpecifiedをtrueにしなければなりません。 サーバーが返すレスポンスについても同じで、...Specifiedプロパティがfalseであれば、...プロパティの値はサーバーから返されたものではなく、意味がないということになります。 ECSのオペレーション紹介 †ここからは実際にECSの個々の機能（オペレーション）を使用する方法を紹介します。Amazon.co.jpで現在使用できるすべてのオペレーションを紹介しますが、その機能はあまりに膨大ですので、ここにはとても書ききれません（あまりにも多く、私自身調べるのに疲れ果てました）。よってここではその要点のみを紹介し、詳しい解説とサンプルのコードはDoboWikiに載せます。 ItemSearchオペレーション †指定したキーワードで商品を検索します。 ItemSearchオペレーションはAWSECommerceService.ItemSearchメソッドを呼び出すことにより実行できます。簡単な流れは、次のようになります。
検索オプションの設定 上記の手順1について、補足します。 ItemSearchRequest.SearchIndexプロパティにより、検索する商品のカテゴリー（本、音楽、DVD、ゲーム、おもちゃなど）を指定します。"Blended"を指定することにより、すべての商品を検索することもできます。また、SearchIndexに指定した値により、使用できるItemSearchRequestのプロパティや、プロパティに指定できる値が変わってきます。 さらにカテゴリーを絞るには、BrowseNodeプロパティを使います。これにより、例えば本であれば、文学、ノンフィクション、コンピュータ、コミックなどといったさらに細かいカテゴリーを指定できます。 検索するキーワードは通常Keywordsプロパティに指定します。しかし例えば本の題名で検索したい時はTitle、著者名で検索したい時はAuthorプロパティを指定するという風に検索する対象を決めて検索することもできます。 指定されたキーワードが間違えているとサーバーが判断して、正しいと思われるキーワードに勝手に変更して検索して結果を返す場合があります。このような場合は、どのような理由でどのようなキーワードに変更されたかを、ItemsのCorrectedQueryで知ることができます。 検索の結果見つかった商品は、最大10個まで返されます（ただしSearchIndexがBlendedの場合はそれ以上）。それ以降の商品を取得するには、ItemPageプロパティでページ数を指定します。ItemPageが1の時（デフォルト）は1〜10番目の商品が返され、ItemPageを2とすると11〜20、3では21〜30の商品が返されます。 サーバーが返す商品の並び方は、Sortプロパティで指定します。商品の売れている順番や、価格、タイトル名、発売日などによる並び順を指定できます。ただし、SearchIndexにより指定できる値が異なります。 ResponseGroupはすべてのオペレーションに共通するプロパティで、ECSの返すデータの種類を指定するために使用します。ECSがすべての情報を返していたのでは膨大なデータ量になってしまうため、クライアントが必要なデータを選択する仕組みになっています。 ResponseGroupの難しい点は、指定した値が不適切だと、欲しいデータを取得できないということです。例えばResponseGroupに何も指定しないと（デフォルトでは"Request"と"Small"を指定したことになります）商品のタイトルやURL、クリエーター情報の一部などは返されますが、商品の画像や価格、売り上げ順位、レビューなどの情報は返されません。これらの情報を取得するには、例えば商品の画像であれば"Images"を、売り上げ順位であれば"SalesRank"を追加しなければなりません。 ResponseGroupに"Medium"を指定すると、"Small", "Request", "ItemAttributes", "OfferSummary", "SalesRank", "EditorialReview", "Images"のすべてを指定したことになりますので、"Medium"だけで商品の画像も売り上げ順位も取得できます。さらに"Large"はこれに加えて"Tracks", "BrowseNodes", "Reviews", "ListmaniaLists", "Similarities", "Offers", "Accessories"をも含んでいます。これらを指定するとデータの取りこぼしは少なくなりますが、無駄なデータを含んでいる可能性が大きく、パフォーマンスは落ちるでしょう。取得したいデータを返す最低限のResponseGroupを指定することがベストでしょう。 結果の取得 結果の取得についても、簡単に説明しておきます。 検索結果の主要な内容はItemSearchResponse.Itemsプロパティで取得できます。これは商品の情報を表すItemオブジェクトの配列となりますが、ItemSearchRequestを一つしか指定せずに検索した場合は、要素は一つだけ返され、これが検索の結果です。 リクエストに関するエラーがECSから返された場合は、Request.Errorsが設定されますので、Request.ErrorsがNULLで無い場合はエラーと判断できます。ItemクラスにもErrorsプロパティがありますが、こちらは特定の商品に関するエラーを表します。 検索された商品の情報はItemオブジェクトで取得できますが、目的の情報を探すのは結構大変かもしれません。まず商品に関する細かい情報は、ItemAttributesプロパティに格納されています。ItemAttributesのメンバの数は膨大で、商品の種類によっても取得できるものとできないものが異なります。その中でも主要なものは、商品のタイトルを表す"Title"や、作成者の情報を格納した"Creator"、価格情報の"ListPrice"などでしょう。 商品の価格についても注意が必要です。ItemAttributes.ListPriceの示す価格は商品の参考価格であって、実際にAmazonで売れられいる価格ではありません。実際の価格は、Offer.OfferListingにあります。また、最安値の情報は、OfferSummary.LowestNewPriceにあります。詳しくはDoboWikiにあるであろうサンプルをご覧ください。 ItemLookupオペレーション †指定した商品に関する詳細なデータを取得します。 商品を指定するために、ItemLookupRequest.ItemIdプロパティにASINを指定します。または、Amazon.co.jpではIdTypeをEANとすることにより、JANを指定することもできます。 SimilarityLookupオペレーション †指定した商品と類似する商品（Amazonで「この商品を買った人はこんな商品も買っています」として表示される商品、関連商品）を見つけます。 商品を指定するために、SimilarityLookupRequest.ItemIdプロパティにASINを指定します。複数のASINを指定できます。 ListSearchオペレーション †ウィッシュリストを検索します。ウィッシュリストとは、ユーザーが自分のほしい商品をリストにして一般に公開できるサービスです。詳しくはAmazonのヘルプをご覧ください。 ListSearchRequest.ListTypeに検索するリストの種類を指定します。Amazon.co.jpではWishListしか指定できませんので、ウィッシュリストしか検索できません。 これ以外に検索対象としてName、FirstName、LastName、Emailのうちどれか1つを必ず指定する必要があります。Nameは名前で検索し、Emailはメールアドレスで検索します。 ListSearchではリスト内の商品の詳しい情報までは取得できませんので、それが必要ならば、ListLookupを使います。 ListLookupオペレーション †指定したウィッシュリストやリストマニアの情報を取得します。リストマニアとは、ユーザーが商品のリストを作成し、一般に公開できるサービスです。詳しくはAmazonのヘルプをご覧ください。 ListLookupRequest.ListTypeにリストの種類を指定します。Amazon.co.jpではWishListかListmaniaです。必ずListTypeSpecifiedをtrueとしなければならないことにも注意してください。 さらにListIdにリストのIDを指定します。このIDは例えばListSearchで返されるListSearchResponse.ListIdで取得できます。 SellerLookupオペレーション †指定した出品者（セーラー）の情報を取得します。出品者のニックネームやAmazonでのURLなどの情報の他に、出品者への利用者の評価やフィードバックも取得できます。 SellerLookupRequest.SellerIdに出品者のIDを指定する必要がありますが、このIDはAmazon以外の売り手が持っており、ItemSearchやItemLookupなどにより取得できます。 SellerListingSearchオペレーション †指定した出品者が出品している商品を検索します。 SellerListingLookupRequestにはSellerIdを必ず指定します。さらにTitleを指定すると、SellerIdの出品者が出品している商品の中からTitleに指定した文字列をタイトルに含む商品を検索します。Titleを指定しないと、すべての商品が指定されたことになります。 サーバーから返される情報は、商品のタイトル、価格、出品数や、ListingId、ExchangeIdなどのID情報の他に、コンディション（新品、再生品、ユーズド商品、コレクター商品など）やサブコンディション（新品、再生品、ほぼ新品、非常に良い、良い、可など）などもあります。 SellerListingLookupオペレーション †指定した出品者が出品している、指定した商品の情報を取得します。 SellerListingLookupではSellerIdの他に、商品のIDをSellerListingLookupRequest.Idに指定する必要があります。ここに指定するIDは通常ExchangeIdですが、IdTypeを設定することにより、ListingIdやASINを指定できるようになります。 CartAdd、CartClear、CartCreate、CartGet、CartModifyオペレーション †これらのオペレーションはショッピングカートを操作するためのものです。 まずCartCreateでショッピングカートを作成します。このとき必ず商品を一つはカートに入れなければなりません。ショッピングカートを作成すると、CartIdとHMACという2つのIDが返されます。今後このショッピングカートを操作する際にはこの2つのIDが両方とも必要になります。ショッピングカートはアクセスしてから90日間有効です。ショッピングカート内の商品を購入するには、Cart.PurchaseURLで返されるURLへ移動する必要があります。 ショッピングカートに商品を追加するには、CartAddを使います。既にショッピングカート内にある商品は、追加できません。 既にショッピングカートに入っている商品の購入数を変更するためには、CartModifyを使います。ショッピングカートから商品を削除するには、CartModifyでその商品の購入数を0にします。CartModifyではショッピングカートにある商品を「今は買わない」状態にすることもできます。 CartClearを使うと、ショッピングカート内のすべての商品を削除できます。ただし、ショッピングカート自体がなくなるわけではなく、CartIdとHMACはその後も有効です。 現在ショッピングカートにある商品を取得するには、CartGetを使います。 ショッピングカートに入れる商品を指定には、商品のASINかOfferListingIdのどちらかを使用します。商品がAmazonが売っているものであればASINを指定し、それ以外の売り手の商品はOfferListingIdを指定します。OfferListingIdはItemSearchやItemLookupで取得できますが、SellerListingSearchやSellerListingLookupでは取得できないようです。 Helpオペレーション †ECSで使用できるオペレーションやResponseGroupの情報を取得します。 オペレーションに関する情報は、必須のパラメータや指定可能なパラメータ、デフォルトのResponseGroupや指定可能なResponseGroupを取得できます。 ResponseGroupに関する情報は、このResponseGroupを指定できるオペレーションや、このResponseGroupを指定することにより返されるエレメントなどを取得できます。 MultiOperation †Multi-Operationリクエスト（別々のオペレーションを一回のリクエストで行う）を行います。詳しくはECSのドキュメントの「Combining Operations into a Single Request」をご覧ください。 最後に †ECSに関して私より詳しい方はたくさんいらっしゃるでしょう。もし私の解説に間違いや不足などがございましたら、DoboWikiで補足していただければ幸いです。 コメント †
|
Site admin: DOBON!
PukiWiki 1.5.0 Copyright © 2001-2006 PukiWiki Developers Team. License is GPL.
Based on "PukiWiki" 1.3 by yu-ji. Powered by PHP 5.6.40. HTML convert time: 0.036 sec.