13.3. Zend_Service_Amazon
Anterior | Capítulo 13. Zend_Service | Próxima

## 13.3. Zend_Service_Amazon

### 13.3.1. Introdução

`Zend_Service_Amazon` é uma simples API para utilização dos web services do Amazon. `Zend_Service_Amazon` possui duas APIs: uma mais tradicional que segue o padrão da própria Amazon API, e uma simples API de consultas para facilitar a construção de pesquisas mais complexas.

`Zend_Service_Amazon` dá aos desenvolvedores a capacidade de recuperar informações como se estivessem accessando os sites Amazon.com diretamente através da Amazon Web Services API. Exemplos incluídos:

- Armazenar informações de ítens, como imagens, descrições, preços, entre outros.
- Revisões editoriais e por parte do cliente.
- Produtos similares e acessórios.
- Ofertas do Amazon.com.
- Listas do tipo ListMania.

Para usar o `Zend_Service_Amazon`, você deve possuir uma chave de desenvolvedor para acessar a Amazon API. Para obter uma chave e outras informações, por favor visite o web site Amazon Web Services.

| Nota
Sua chave de desenvolvedor Amazon API está ligada à sua identificação Amazon, então, tome medidas de segurança apropriadas para garantir a privacidade de sua chave.

Exemplo 13.2. Busca no Amazon usando a API tradicional

Neste exemplo, pesquisamos por livros de PHP no Amazon, executando um laço para imprimir os resultados.

    <?php
    require_once 'Zend/Service/Amazon.php';
    $amazon = new Zend_Service_Amazon('AMAZON_API_KEY&');
    $response = $amazon->itemSearch(array('SearchIndex' => 'Books', 'Keywords' => 'php'));
    foreach ($response as $r) {
        echo $r->Title .'<br />';
    }
    ?>

Exemplo 13.3. Busca no Amazon usando a Query API

Aqui, nós pesquisamos por livros de PHP no Amazon, mas usando a API de consulta, que implementa o padrão de projeto "Fluent Interface".

    <?php
    require_once 'Zend/Service/Amazon/Query.php';
    $query = new Zend_Service_Amazon_Query('AMAZON_API_KEY');
    $query->category('Books')->Keywords('PHP');
    $results = $query->search();
    foreach ($results as $result) {
        echo $result->Title .'<br />';
    }
    ?>

### 13.3.2. Códigos de Países

Por padrão, `Zend_Service_Amazon` conecta ao web service do Amazon localizado nos Estado Unidos ("`US`"). Para conectar-se a um país diferente, simplesmente especifique a respectiva string de código de país como segundo parâmetro para o construtor:

Exemplo 13.4. Selecionando o Amazon Web Service de um país

    <?php
    // Connect to Amazon in Japan
    require_once 'Zend/Service/Amazon.php';
    $amazon = new Zend_Service_Amazon('AMAZON_API_KEY', 'JP');
    ?>

| Nota
Códigos válidos podem ser: `CA`, `DE`, `FR`, `JP`, `UK`, e `US`.

### 13.3.3. Procurando por um ítem específico do Amazon com o código ASIN

O método `itemLookup()` oferece a capacidade de procurar por um ítem em particular quando o código ASIN é conhecido.

Exemplo 13.5. Procurando por um ítem específico no Amazon usando ASIN

    <?php
    require_once 'Zend/Service/Amazon.php';
    $amazon = new Zend_Service_Amazon('AMAZON_API_KEY');
    $item = $amazon->itemLookup('B0000A432X');
    ?>

O método `itemLookup()` também aceita um segundo parâmetro opcional para lidar com as opções de busca. Para maiores detalhes, incluíndo uma lista de opções disponíveis, por favor consulte a respectiva documentação do Amazon .

### 13.3.4. Executando pesquisas de ítens no Amazon

Efetuar buscas de ítens, baseando-se em um dos vários critérios de busca disponíveis, são tarefas simples se empregado o método `itemSearch()`, como mostrado no exemplo seguinte:

Exemplo 13.6. Efetuando buscas de ítens no Amazon

    <?php
    require_once 'Zend/Service/Amazon.php';
    $amazon = new Zend_Service_Amazon('AMAZON_API_KEY');
    $response = $amazon->itemSearch(array('SearchIndex' => 'Books', 'Keywords' => 'php'));
    foreach($response as $r) {
        echo $r->Title .'<br />';
    }
    ?>

O método `itemSearch()` aceita um simples array de parâmetros para lidar com as opções de busca. Para mais detalhes, incluíndo uma lista de opções disponíveis, consulte a respectiva documentação do Amazon

| Dica
A classe `Zend_Service_Amazon_Query` é um meio fácil de usar um encapsulamento deste método.

### 13.3.5. Usando a Query API Alternativa

#### 13.3.5.1. Introdução

`Zend_Service_Amazon_Query` oferece uma API alternativa para utilizar o Amazon Web Service. A API alternetiva utiliza o padrão de projeto "Fluent Interface". Ou seja, todas as chamadas são feitas usando métodos encadeados (ex: `$obj->method()->method2($arg)`)

A API `Zend_Service_Amazon_Query` usa sobrecarga para facilitar a definição dos ítens de busca, permitindo buscas baseadas nos critérios especificados. Cada uma das opções é implementada como uma chamada a método, e cada argumento respectivo, corresponde ao nome da opção:

Exemplo 13.7. Pesquisando o Amazon usando a Query API Alternativa

Neste exemplo, a Query API alternativa é usada como uma interface "fluente" para especificar opções e seus respectivos valores:

    <?php
    require_once 'Zend/Service/Amazon/Query.php';
    $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 />';
    }
    ?>

Isto atribui à opção `Category` o valor "Books" e à opção `Keywords` o valor "PHP".

Para mais informações e opções disponíveis, consulte a documentação do Amazon específica ao assunto.

### 13.3.6. Classes Zend_Service_Amazon

As classes abaixo listadas são retornadas pelos métodos `Zend_Service_Amazon::itemLookup()` e `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`

#### 13.3.6.1. Zend_Service_Amazon_Item

`Zend_Service_Amazon_Item` é uma classe usada para representar um ítem do Amazon retornado pelo web service. Ele abrange todos os atributos dos ítens, incluíndo título, descrição, críticas, etc.

##### 13.3.6.1.1. Zend_Service_Amazon_Item::asXML()

`string asXML();`

Retorna o XML original para o ítem pesquisado.

##### 13.3.6.1.2. Propriedades

`Zend_Service_Amazon_Item` possui algumas propriedades que estão diretamente relacionadas com suas similares na API padrão do Amazon API.

Tabela 13.1. Propriedade de Zend_Service_Amazon_Item

Nome | Tipo | Descrição
--- | --- | ---
ASIN | string | ID do ítem
DetailPageURL | string | URL para a página de detalhes do ítem
SalesRank | string | Pontuação de vendas para o ítem
SmallImage | Zend_Service_Amazon_Image | Imagem reduzida para o ítem
MediumImage | Zend_Service_Amazon_Image | Imagem de tamanho médio para o ítem
LargeImage | Zend_Service_Amazon_Image | Imagem grande para o ítem
Subjects | array | Assunto do ítem
Offers | `Zend_Service_Amazon_OfferSet` | Resumo de ofertas e Ofertas para o ítem
CustomerReviews | array | Criticas dos clientes representadas como um array de objetos `Zend_Service_Amazon_CustomerReview`
EditorialReviews | array | Críticas editoriais representadas como um array de objetos `Zend_Service_Amazon_EditorialReview`
SimilarProducts | array | Produtos similares representados como um array de objetos `Zend_Service_Amazon_SimilarProduct`
Accessories | array | Acessórios para o ítem representadas como um array de objetos `Zend_Service_Amazon_Accessories`
Tracks | array | Um array de números de trilhas e nomes para DVDs e CDs de música
ListmaniaLists | array | Ítem relacionada à lista Listmania como um array de objetos `Zend_Service_Amazon_ListmainList`
PromotionalTag | string | Tag de ítem promocional

Retornar para a Lista de Classes

#### 13.3.6.2. Zend_Service_Amazon_Image

`Zend_Service_Amazon_Image` representa uma imagem remota de um produto.

##### 13.3.6.2.1. Propriedades

Tabela 13.2. Propriedades de Zend_Service_Amazon_Image

Nome | Tipo | Descrição
--- | --- | ---
Url | string | URL remota para a imagem
Height | int | Altura da imagem em pixels
Width | int | Largura da imagem em pixels

Retornar para a Lista de Classes

#### 13.3.6.3. Zend_Service_Amazon_ResultSet

Objetos `Zend_Service_Amazon_ResultSet` saõ retornados por Zend_Service_Amazon::itemSearch() e permitem a você manusear facilmente os múltiplos resultados retornados.

| Nota
Implemente o `SeekableIterator` para fácil iteração (ex: usando `foreach`), bem como, acesso direto a uma string específica de resultados usando `seek()`.

##### 13.3.6.3.1. Zend_Service_Amazon_ResultSet::totalResults()

`int totalResults();`

Número total de resultados retornados pela pesquisa

Retornar para a Lista de Classes

#### 13.3.6.4. Zend_Service_Amazon_OfferSet

Cada resultado retornado por Zend_Service_Amazon::itemSearch() e Zend_Service_Amazon::itemLookup() contém um objeto `Zend_Service_Amazon_OfferSet` através do qual o preço do ítem pode ser recuperado.

##### 13.3.6.4.1. Propriedades

Tabela 13.3. Propriedades de Zend_Service_Amazon_OfferSet

Nome | Tipo | Descrição
--- | --- | ---
LowestNewPrice | int | Menor preço para o ítem na condição de NOVO
LowestNewPriceCurrency | string | A moeda em que está expresso o `LowestNewPrice`
LowestOldPrice | int | Menor preço para o ítem na condição de USADO
LowestOldPriceCurrency | string | A moeda em que está expresso o `LowestOldPrice`
TotalNew | int | Total de ítens "Novos" disponíveis
TotalUsed | int | Total de ítens "Usados" disponíveis
TotalCollectible | int | Total de ítens "colecionáveis" disponíveis
TotalRefurbished | int | Total de ítens "refurbished" disponíveis
Offers | array | Um array de objetos `Zend_Service_Amazon_Offer`.

Retornar para a Lista de Classes

#### 13.3.6.5. Zend_Service_Amazon_Offer

As ofertas para um dado ítem, são retornadas como objetos `Zend_Service_Amazon_Offer`.

Tabela 13.4. Propriedades de Zend_Service_Amazon_Offer

Name | Type | Description
--- | --- | ---
MerchantId | string | ID Amazon para fornecedores
GlancePage | string | URL para uma página contendo um resumo do fornecedor.
Condition | string | Condição do ítem
OfferListingId | string | ID da listagem de Ofertas
Price | int | Preço do ítem
CurrencyCode | string | Código de moeda para o preço do ítem
Availability | string | Disponibilidade do ítem
IsEligibleForSuperSaverShipping | boolean | Informa se o ítem é elegível para remessa super econômica ou não

Retornar para a Lista de Classes

#### 13.3.6.6. Zend_Service_Amazon_SimilarProduct

Ao executar uma busca por ítens, O Amazon também retorna uma lista de produtos similares que podem ser localizados ao seu gosto. Cada um deles é retornado como um objeto `Zend_Service_Amazon_SimilarProduct`.

Cada objeto contém a informação necessária para que as requisições subsequentes recuperem informações detalhadas sobre o ítem.

##### 13.3.6.6.1. Propriedades

Tabela 13.5. Propriedades de Zend_Service_Amazon_SimilarProduct

Name | Type | Description
--- | --- | ---
ASIN | string | Identificador único do produto no Amazon (ASIN)
Title | string | Título do Produto

Retornar para a Lista de Classes

#### 13.3.6.7. Zend_Service_Amazon_Accessories

Acessórios para o ítem retornado, são representados como objetos `Zend_Service_Amazon_Accessories`

##### 13.3.6.7.1. Propriedades

Tabela 13.6. Zend_Service_Amazon_Accessories Properties

Name | Type | Description
--- | --- | ---
ASIN | string | Identificador único do produto no Amazon (ASIN)
Title | string | Título do Produto

Retornar para a Lista de Classes

#### 13.3.6.8. Zend_Service_Amazon_CustomerReview

Cada crítica feita pelo cliente é retornada como um objeto `Zend_Service_Amazon_CustomerReview`.

##### 13.3.6.8.1. Propriedades

Tabela 13.7. Propriedades de Zend_Service_Amazon_CustomerReview

Name | Type | Description
--- | --- | ---
Rating | string | Cotação do ítem
HelpfulVotes | string | Votos na "utilidade" da crítica emitida
CustomerId | string | ID do Cliente
TotalVotes | string | Total de votos
Date | string | Data
Summary | string | Resumo
Content | string | Conteúdo

Retornar para a Lista de Classes

#### 13.3.6.9. Zend_Service_Amazon_EditorialReview

As críticas editoriais são retornadoas como objetos `Zend_Service_Amazon_EditorialReview`

##### 13.3.6.9.1. Propriedades

Tabela 13.8. Propriedades de Zend_Service_Amazon_EditorialReview

Name | Type | Description
--- | --- | ---
Source | string | Fonte da crítica editorial
Content | string | Conteúdo

Retornar para a Lista de Classes

#### 13.3.6.10. Zend_Service_Amazon_Listmania

Os ítens da lista List Mania são retornados como objetos `Zend_Service_Amazon_Listmania`.

##### 13.3.6.10.1. Propriedades

Tabela 13.9. Propriedades de Zend_Service_Amazon_Listmania

Name | Type | Description
--- | --- | ---
ListId | string | List ID
ListName | string | List Name

Retornar para a Lista de Classes

Anterior | Acima | Próxima
13.2. Zend_Service_Rest | Principal | 13.4. Zend_Service_Flickr