# Zend_Service_Amazon

## 導入

`Zend_Service_Amazon` は Amazon ウェブサービスを使用するためのシンプルな API です。 `Zend_Service_Amazon` は、ふたつの API を実装しています。 Amazon 自身の API に従った伝統的な API と、 複雑な検索クエリを簡単に作成するためのシンプルな「クエリ API」です。

`Zend_Service_Amazon` を使用すると、開発者が Amazon Web Services API を直接使用して、Amazon.com の情報を取得できるようになります。 取得できる情報には以下のようなものがあります。

- 商品の情報、例えば画像や説明や価格など

- カスタマーレビュー

- 似た製品やアクセサリの情報

- Amazon.com のおすすめ

- リストマニアのリスト

`Zend_Service_Amazon` を使用するには、 Amazon デベロッパ API キーとシークレットキーが必要です。 このキーを取得するには、 Amazon Web Services のウェブサイトを参照ください。 2009年8月15日以降、Amazon Product Advertising API を `Zend_Service_Amazon` で使うにはシークレットキーが必要となります。

### 注意

Amazon デベロッパ API キーおよびシークレットキーは Amazon のアカウントと関連付けられます。 取得した API キーは自分自身でのみ使用するようにしましょう。

### 伝統的な API を使用した Amazon 検索

この例では、Amazon で PHP に関する書籍を検索し、 結果の一覧を表示します。

    $amazon = new Zend_Service_Amazon('AMAZON_API_KEY', 'US', 'AMAZON_SECRET_KEY');
    $results = $amazon->itemSearch(array('SearchIndex' => 'Books',
                                         'Keywords' => 'php'));
    foreach ($results as $result) {
        echo $result->Title . '<br />';
    }

### クエリ API を使用した Amazon 検索

ここでも Amazon で PHP に関する書籍を検索します。 しかし、ここではクエリ API を使用します。この API は、Fluent Interface パターンと似た形式です。

    $query = new Zend_Service_Amazon_Query('AMAZON_API_KEY', 'US, 'AMAZON_SECRET_KEY');
    $query->category('Books')->Keywords('PHP');
    $results = $query->search();
    foreach ($results as $result) {
        echo $result->Title . '<br />';
    }

## 国コード

デフォルトでは、`Zend_Service_Amazon` は米国 ("`US`") の Amazon Web Service に接続します。他の国のサービスに接続するには、 コンストラクタの 2 番目のパラメータとして、適切な国コード文字列を指定するだけです。

### Amazon Web Service の国の選択

    // 日本の Amazon に接続します
    $amazon = new Zend_Service_Amazon('AMAZON_API_KEY', 'JP', 'AMAZON_SECRET_KEY');

### 国コード

使用できる国コードは `CA`、`DE`、`FR`、`JP`、 `UK` および `US` です。

## ASIN を使用した商品の検索

ASIN がわかっている場合は、`itemLookup()` メソッドを使用すると Amazon の商品を検索できます。

### ASIN を使用した Amazon の商品検索

    $amazon = new Zend_Service_Amazon('AMAZON_API_KEY', 'US', 'AMAZON_SECRET_KEY');
    $item = $amazon->itemLookup('B0000A432X');

`itemLookup()` メソッドにオプションの第 2 パラメータを渡すことで、 検索オプションを指定できます。使用可能なオプションを含む詳細は、 関連する Amazon の文書 を参照ください。

### 画像の情報

検索結果の画像情報を取得するには、オプション `ResponseGroup` を `Medium` あるいは `Large` に設定しなければなりません。

## Amazon の商品検索の実行

さまざまな条件指定による商品検索を行うには `itemSearch()` メソッドを使用します。 以下に例を示します。

### Amazon の商品検索の実行

    $amazon = new Zend_Service_Amazon('AMAZON_API_KEY', 'US', 'AMAZON_SECRET_KEY');
    $results = $amazon->itemSearch(array('SearchIndex' => 'Books',
                                         'Keywords' => 'php'));
    foreach ($results as $result) {
        echo $result->Title . '<br />';
    }

### ResponseGroup オプションの使用法

`ResponseGroup` オプションを使用すると、 レスポンスで返される情報を制御することができます。

    $amazon = new Zend_Service_Amazon('AMAZON_API_KEY', 'US', 'AMAZON_SECRET_KEY');
    $results = $amazon->itemSearch(array(
        'SearchIndex'   => 'Books',
        'Keywords'      => 'php',
        'ResponseGroup' => 'Small,ItemAttributes,Images,SalesRank,Reviews,' .
                           'EditorialReview,Similarities,ListmaniaLists'
        ));
    foreach ($results as $result) {
        echo $result->Title . '<br />';
    }

`itemSearch()` は配列のパラメータをひとつ受け取り、 このパラメータで検索オプションを指定します。使用可能なオプションを含む詳細は、 関連する Amazon の文書 を参照ください。

`Zend_Service_Amazon_Query` クラスを使用すると、これらのメソッドをより簡単に使用できるようになります。

## もうひとつのクエリ API の使用法

### 導入

`Zend_Service_Amazon_Query` は、Amazon Web Service を使用するためのもうひとつの API を提供します。 この API では Fluent Interface パターンを使用します。 つまり、すべてのコールはメソッド呼び出しを連結した形式になります (例: `$obj->method()->method2($arg)`)。

商品検索の設定を行いやすく、また条件に基づく検索をしやすくするために、 `Zend_Service_Amazon_Query` API ではオーバーロードを使用しています。 各オプションの設定はメソッドのコールで行い、メソッドの引数がオプションの値に対応します。

#### もうひとつのクエリ API を使用した Amazon の検索

この例では、もうひとつのクエリ API のインターフェイスを使用して、 オプションとその値を設定します。

    $query = new Zend_Service_Amazon_Query('MY_API_KEY');
    $query->Category('Books')->Keywords('PHP');
    $results = $query->search();
    foreach ($results as $result) {
        echo $result->Title . '<br />';
    }

これは、オプション `Category` の値を "Books"、 そして `Keywords` の値を "PHP" に設定します。

使用可能なオプションについての詳細な情報は、 関連する Amazon の文書 を参照ください。

## Zend_Service_Amazon クラス群

以下のクラスは、すべて `Zend_Service_Amazon::itemLookup()` および `Zend_Service_Amazon::itemSearch()` から返されるものです。

- `Zend_Service_Amazon_Item`

- `Zend_Service_Amazon_Image`

- `Zend_Service_Amazon_ResultSet`

- `Zend_Service_Amazon_OfferSet`

- `Zend_Service_Amazon_Offer`

- `Zend_Service_Amazon_SimilarProduct`

- `Zend_Service_Amazon_Accessories`

- `Zend_Service_Amazon_CustomerReview`

- `Zend_Service_Amazon_EditorialReview`

- `Zend_Service_Amazon_ListMania`

### Zend_Service_Amazon_Item

`Zend_Service_Amazon_Item` は、ウェブサービスから返される Amazon の商品を表すために使用されるクラスです。 商品のタイトル、説明、レビューなどを含むすべての属性を包含します。

#### Zend_Service_Amazon_Item::asXML()

string `asXML`

商品情報を、元の XML で返します。

#### プロパティ

`Zend_Service_Amazon_Item` が持つプロパティは、 それぞれが標準の Amazon API に直接対応しています。

##### Zend_Service_Amazon_Item のプロパティ

名前 | 型 | 説明
--- | --- | ---
ASIN | string | Amazon の商品 ID
DetailPageURL | string | 商品の詳細情報ページの URL
SalesRank | int | 商品の売上ランキング
SmallImage | Zend_Service_Amazon_Image | 商品の画像 (小)
MediumImage | Zend_Service_Amazon_Image | 商品の画像 (中)
LargeImage | Zend_Service_Amazon_Image | 商品の画像 (大)
Subjects | array | 商品のテーマ
Offers | `Zend_Service_Amazon_OfferSet` | 提供内容の概要および商品の提供情報
CustomerReviews | array | `Zend_Service_Amazon_CustomerReview` オブジェクトの配列で表されるカスタマーレビュー
EditorialReviews | array | `Zend_Service_Amazon_EditorialReview` オブジェクトの配列で表される、出版社/著者からの内容紹介
SimilarProducts | array | `Zend_Service_Amazon_SimilarProduct` オブジェクトの配列で表される、似た商品の情報
Accessories | array | `Zend_Service_Amazon_Accessories` オブジェクトの配列で表される、関連アクセサリの情報
Tracks | array | 音楽 CD や DVD の、トラック番号と曲名の配列
ListmaniaLists | array | Item related Listmania Lists as an array of `Zend_Service_Amazon_ListmainList` オブジェクトの配列で表される、この商品に関連するリストマニアのリスト
PromotionalTag | string | 商品の販売促進用のタグ

クラス一覧に戻る

### Zend_Service_Amazon_Image

`Zend_Service_Amazon_Image` は、商品の画像を表します。

#### プロパティ

##### Zend_Service_Amazon_Image のプロパティ

名前 | 型 | 説明
--- | --- | ---
Url | Zend_Uri | 画像のリモート URL
Height | int | 画像の高さ (ピクセル単位)
Width | int | 画像の幅 (ピクセル単位)

クラス一覧に戻る

### Zend_Service_Amazon_ResultSet

`Zend_Service_Amazon_ResultSet` オブジェクトは Zend_Service_Amazon::itemSearch() から返され、結果が複数返された場合に簡単に処理できるようにします。

#### SeekableIterator

操作性を高めるため、`SeekableIterator` を実装しています。 これにより、一般的な順次処理 (例えば `foreach` など) だけでなく `seek()` を使用した特定の結果への直接アクセスも可能です。

#### Zend_Service_Amazon_ResultSet::totalResults()

int `totalResults`

検索結果の総数を返します。

クラス一覧に戻る

### Zend_Service_Amazon_OfferSet

Each result returned by Zend_Service_Amazon::itemSearch() および Zend_Service_Amazon::itemLookup() から返される各結果には `Zend_Service_Amazon_OfferSet` オブジェクトが含まれており、 ここから商品の販売情報が取得できます。

#### プロパティ

##### Zend_Service_Amazon_OfferSet のプロパティ

名前 | 型 | 説明
--- | --- | ---
LowestNewPrice | int | "新品" の最低価格
LowestNewPriceCurrency | string | `LowestNewPrice` の通貨単位
LowestOldPrice | int | "ユーズド商品" の最低価格
LowestOldPriceCurrency | string | `LowestOldPrice` の通貨単位
TotalNew | int | "新品" の在庫数
TotalUsed | int | "ユーズド商品" の在庫数
TotalCollectible | int | "コレクター商品" の在庫数
TotalRefurbished | int | "refurbished" の在庫数
Offers | array | `Zend_Service_Amazon_Offer` オブジェクトの配列

クラス一覧に戻る

### Zend_Service_Amazon_Offer

商品の個々の販売情報が `Zend_Service_Amazon_Offer` オブジェクトとして返されます。

#### Zend_Service_Amazon_Offer のプロパティ

##### プロパティ

名前 | 型 | 説明
--- | --- | ---
MerchantId | string | 出品者の Amazon ID
GlancePage | string | 出品者の概要が掲載されているページの URL
Condition | string | 商品のコンディション
OfferListingId | string | 販売情報リストの ID
Price | int | 商品の価格
CurrencyCode | string | 商品価格の通貨コード
Availability | string | 商品の在庫状況
IsEligibleForSuperSaverShipping | boolean | Super Saver Shipping に対応しているか否か

クラス一覧に戻る

### Zend_Service_Amazon_SimilarProduct

商品を検索した際に、Amazon は検索結果の商品と似た商品の一覧も返します。 個々のデータは `Zend_Service_Amazon_SimilarProduct` オブジェクトとして返されます。

各オブジェクトに含まれる情報を元にして、 その商品の完全な情報を取得するリクエストを行うことができます。

#### プロパティ

##### Zend_Service_Amazon_SimilarProduct のプロパティ

名前 | 型 | 説明
--- | --- | ---
ASIN | string | Amazon 商品 ID (ASIN)
Title | string | 商品名

クラス一覧に戻る

### Zend_Service_Amazon_Accessories

返される結果の中の「アクセサリ」については `Zend_Service_Amazon_Accessories` オブジェクトで表されます。

#### プロパティ

##### Zend_Service_Amazon_Accessories のプロパティ

名前 | 型 | 説明
--- | --- | ---
ASIN | string | Amazon 商品 ID (ASIN)
Title | string | 商品名

クラス一覧に戻る

### Zend_Service_Amazon_CustomerReview

カスタマーレビューのデータは `Zend_Service_Amazon_CustomerReview` オブジェクトで返されます。

#### プロパティ

##### Zend_Service_Amazon_CustomerReview のプロパティ

名前 | 型 | 説明
--- | --- | ---
Rating | string | 商品のおすすめ度
HelpfulVotes | string | 「このレビューが参考になった」の投票
CustomerId | string | カスタマー ID
TotalVotes | string | 全投票数
Date | string | レビューされた日付
Summary | string | レビューの概要
Content | string | レビューの内容

クラス一覧に戻る

### Zend_Service_Amazon_EditorialReview

出版社/著者からの内容紹介は `Zend_Service_Amazon_EditorialReview` オブジェクトで返されます。

#### プロパティ

##### Zend_Service_Amazon_EditorialReview のプロパティ

名前 | 型 | 説明
--- | --- | ---
Source | string | レビュー元
Content | string | レビューの内容

クラス一覧に戻る

### Zend_Service_Amazon_Listmania

リストマニアのリストデータは `Zend_Service_Amazon_Listmania` オブジェクトで返されます。

#### プロパティ

##### Zend_Service_Amazon_Listmania のプロパティ

名前 | 型 | 説明
--- | --- | ---
ListId | string | リスト ID
ListName | string | リスト名

クラス一覧に戻る