┏第75号━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃　　　　　　　　　.NETプログラミング研究　　　　　　　　　┃ ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛ ──＜メニュー＞─────────────────────── ■.NET Tips ・Amazon E-Commerce Serviceを使用する -プロキシクラスの作成 -ECSのオペレーション紹介 -ItemSearchオペレーション -ItemLookupオペレーション -SimilarityLookupオペレーション -ListSearchオペレーション -ListLookupオペレーション -SellerLookupオペレーション -SellerListingSearchオペレーション -SellerListingLookupオペレーション -CartAdd、CartClear、CartCreate、CartGet、CartModifyオペレー ション -Helpオペレーション -MultiOperation -最後に ─────────────────────────────── ─────────────────────────────── ■.NET Tips ─────────────────────────────── ●Amazon E-Commerce Serviceを使用する DoboWikiでは様々なWebサービスを紹介していますが、その中でも横 綱格といえるのが、Amazonの提供するWebサービスE-Commerce Service（ECS）でしょう。ECSは利用者の多いサービスであり、また これから使いたいと考えている方も多いでしょう。ECSの機能はあま りに膨大で、奥が深いですが、その割にはドキュメントの説明が足り ないように思われます。そこで今回は私が実際にECSをいろいろと使 ってみて分かったことを含め、ECSの使い方について説明します。 [URL]DoboWiki http://wiki.dobon.net/ [URL]Webサービス紹介 http://wiki.dobon.net/index.php?%BC%AB%CD%B3%B6%E8%2FWeb%A5%B5%A1%BC%A5%D3%A5%B9%BE%D2%B2%F0 [URL]Amazon Web Services Developer Connection : Technical Documentation http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=19 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に載せます。 [URL]Amazon E-Commerce Service http://wiki.dobon.net/index.php?%BC%AB%CD%B3%B6%E8%2FWeb%A5%B5%A1%BC%A5%D3%A5%B9%BE%D2%B2%F0%2FAmazon%20E-Commerce%20Service ★ItemSearchオペレーション 指定したキーワードで商品を検索します。 ItemSearchオペレーションはAWSECommerceService.ItemSearchメソッ ドを呼び出すことにより実行できます。簡単な流れは、次のようにな ります。 1.ItemSearchRequestクラスのインスタンスと作成し、プロパティを 適当に設定する。詳しくは、後述。 2.ItemSearchクラスのインスタンスを作成し、AWSAccessKeyIdに自分 のAccess Key ID（無ければ作成する）を、AssociateTagに自分の Associate ID（無ければ指定する必要なし）を設定する。また、 Requestに先ほど作成したItemSearchRequestを設定する。 3.AWSECommerceServiceクラスのインスタンスを作成して、2で作成し たItemSearchを引数としてItemSearchメソッドを呼び出す。 4.3で返されるItemSearchResponseオブジェクトから、検索結果を取 得する。 ☆検索オプションの設定 上記の手順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のヘルプをご覧ください。 [URL]ウィッシュリスト http://www.amazon.co.jp/gp/help/customer/display.html?nodeId=720602 ListSearchRequest.ListTypeに検索するリストの種類を指定します。 Amazon.co.jpではWishListしか指定できませんので、ウィッシュリス トしか検索できません。 これ以外に検索対象としてName、FirstName、LastName、Emailのうち どれか1つを必ず指定する必要があります。Nameは名前で検索し、 Emailはメールアドレスで検索します。 ListSearchではリスト内の商品の詳しい情報までは取得できませんの で、それが必要ならば、ListLookupを使います。 ★ListLookupオペレーション 指定したウィッシュリストやリストマニアの情報を取得します。リス トマニアとは、ユーザーが商品のリストを作成し、一般に公開できる サービスです。詳しくはAmazonのヘルプをご覧ください。 [URL]リストマニア http://www.amazon.co.jp/gp/help/customer/display.html?nodeId=747410 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」をご覧ください。 [URL]Combining Operations into a Single Request http://docs.amazonwebservices.com/AWSEcommerceService/2006-09-13/PgCombiningOperations.html ★最後に ECSに関して私より詳しい方はたくさんいらっしゃるでしょう。もし 私の解説に間違いや不足などがございましたら、DoboWikiで補足して いただければ幸いです。 ＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝ ■ここで示したコードの多くはまずC#で書き、それを「C# to VB.NET Translator」でVB.NETのコードに変換し、修正を加えたものです。 [URL]C# to VB.NET Translator http://authors.aspalliance.com/aldotnet/examples/translate.aspx ■このマガジンの購読、購読中止、バックナンバー、説明に関しては 　次のページをご覧ください。 　http://www.mag2.com/m/0000104516.htm ■発行人・編集人：どぼん！ 　(Microsoft MVP for Visual Basic, Oct 2005-Oct 2006) 　http://dobon.net 　dobon_info@yahoo.co.jp ■ご質問等はメールではなく、掲示板へお願いいたします。 　http://dobon.net/vb/bbs.html ■上記メールアドレスへのメールは確実に読まれる保障はありません 　（スパム、ウィルス対策です）。メールは下記URLのフォームメール 　から送信してください。 　http://dobon.net/mail.html Copyright (c) 2003 - 2006 DOBON! All rights reserved. ＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝