.NETプログラミング研究第75号 [まぐまぐ！]

2006/10/20

.NETプログラミング研究第75号

┏第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.
＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝＝