Amazon E-Commerce Service (ECS) access library

If you are building a Project Zero application that needs to access Amazon.com's E-Commerce data, you can use this extension. The Project Zero Amazon ECS module (zero.amazon.ecs) allows you to access the REST interface to Amazon ECS from your Project Zero application. This extension provides a simple Java API to access Amazon ECS and integration with Groovy scripts. Use it to search the Amazon catalog using the ItemSearch REST API. The results are provided directly to you as either XML or raw data (as a string or stream). Use the samples described in the following sections of this article.

Signing up with Amazon

To get started, you need an access key ID from Amazon. To get an ID, sign up for an account at Amazon. For more general information on Amazon's Web services, see the AWS Home Page.

When you sign up, you are given a 20-digit access key ID. You need this key to access the Amazon services.

Adding zero.amazon.ecs to your project

When you have an access key from Amazon, add the zero.amazon.ecs extension to your project. You can do this with the Project Zero tooling by editing your config/ivy.xml file and adding the zero.amazon.ecs library to your dependencies. If you do not have the library installed, it is downloaded automatically when you save the ivy.xml file or the next time you resolve your project.

Configuring your access ID key

After you add the extension to your project you need to configure your access ID key so that the zero.amazon.ecs module can access Amazon on your behalf. This is accomplished by adding an entry to your config/zero.config file. The entry looks like the following example:

/config/amazon/accessKeyId="xyxyxyxyxyxyxyxyxyxy"

In this example, xyxyxyxyxyxyxyxyxyxy is your access ID key so you would insert your access ID key in this field.

Performing a search

To perform a simple search you can start with the quickItemSearch() API. This API enables you to perform a simple catalog search using a search index and a keyword. The results are provided as a DOM. The following example is a Groovy script that searches for Harry Potter books and prints the results to the browser:

amazonecs.quickItemSearch("Books", "Harry Potter", request.amazon.mySearch.toString());

request.headers.out.'Content-Type'="text/plain";
request.view="XML";
request.xml.output = request.amazon.mySearch.result[]
render();

The first line of this example,

amazonecs.quickItemSearch("Books", "Harry Potter", request.amazon.mySearch.toString());

Creating advanced searches

The quickItemSearch is quick and easy but it does not give you full access to Amazon's ItemSearch API. You can use the itemSearch() API to customize your search. The itemSearch() API provides full access to all of the parameters of the ItemSearch REST API. For details, see the links in the Additional resources section for pointers to the full Amazon documentation. The itemSearch() API uses the global context to set up the search and to access the results. To use the API, first choose a place in the global context to use as the scratch pad for your search, for example /request/amazon/mySearch. Setting up the search requires the following basic procedure:

1. Setup the search parameters.
2. Invoke the itemSearch() API.
3. Access the results.

Setting up the search

To do the search, begin by setting up the search parameters. Set the attributes under the global context location (/request/amazon/mySearch) that match the attribute names supported by the Amazon API. For example, to do the Harry Potter search described in the previous section, use the following (Groovy) example:

def m = [SearchIndex:"Books", 
         Keywords:"Harry Potter",
         ];
request.amazon.mySearch.zputs(m);

This example uses the puts() global context method to simplify the syntax. You could also use the following example to set up the search:

request.amazon.mySearch.SearchIndex="Books";
request.amazon.mySearch.Keywords="Harry Potter";

Running the search

Once the search is set up, you can issue the actual search request, as shown in the following example:

amazonecs.itemSearch(request.amazon.mySearch.toString());

In Groovy, the amazonecs variable is always available and pre-initialized by the zero.amazon.ecs library. In Java, you must first create an instance of the zero.amazon.ecs.AmazonECSClient class. The itemSearch() API takes a single parameter that is the location in the global context which you are using as the scratch pad. The search is run immediately and control returns when the search is completed.

Getting results

After the search completes, the results are stored in the global context under your scratch pad in the results attribute (for example, /request/amazon/mySearch/results). By default, the results from Amazon are parsed and made available as an XML DOM tree. This makes it easy to navigate the results or apply a style sheet to produce output. If you want a different output format, you can add the responseType attribute to your search set up, as shown in the following example:

request.amazon.mySearch.responseType = "string";

Output is available in one of the following formats:

XML DOM

responseType = dom

Single string

responseType = string

InputStream

responseType = stream

You can then use the results in your application.

Advanced Topics

Validating your search set up

Amazon provides a way to check the validity of your search before you actually run the search. The ItemSearch API is complex with many options and a variety of required and optional combinations. To check the set up of your search to be sure it is correct before you run the search, you can use the isValidItemSearch() API. The format of this API is exactly the same as the itemSearch() API described in the previous section. The only difference is the output. Instead of returning search results, the API returns a boolean value indicating if the search was valid (true) or not valid (false). If the search was not valid, the global context attribute /request/amazon/mySearch/statusMessage returns the reason the set up was not valid.

Applying a style sheet

Project Zero provides an XML view component to apply an XSL style sheet to an XML DOM when producing output to the client. The zero.amazon.ecs extension provides a sample item search style sheet that converts the XML Amazon search results to an HTML list view. To use this, use the following sample:

def m = [SearchIndex:"Books", 
Keywords:"Harry Potter",
ResponseGroup:"Medium,ItemAttributes",
responseType: "dom"
];

def ms = request.amazon.mySearch
ms.zputs(m);

amazonecs.itemSearch(ms.toString());

request.headers.out.'Content-Type'="text/html";           // Line 1
request.view="XML";                                                        // Line 2
request.xml.output = ms.result[]                                     // Line 3
request.xml.stylesheet = "amazon-item-search.xsl";     // Line 4

render();                                                                           // Line 5

The last 5 lines of code in this sample provide all of the following output formatting:

• Line 1 sets the output Content-Type to text/html.
• Line 2 sets the view component to the Zero XML view component.
• Line 3 sets the desired output object to the results of the Amazon ItemSearch.
• Line 4 sets the desired XSL style sheet to the item search style sheet provided with the zero.amazon.ecs extension.
• Line 5 renders the output to the client

Note: The XSL style sheet does NOT have to be copied into your project. It is automatically available when you declare a dependency on the zero.amazon.ecs extension.

You could also create your own style sheet and place it in app/views of your project and use that instead.

Paging through search results

By default, Amazon returns 10 results in the response to your search. Your search probably has more than 10 results. To page through the results you need to know the total number of pages. That information is provided in the XML returned from Amazon and can be accessed as shown in the following example:

TODO:  Show accessing TotalPages example

Knowing the total number of pages, you can start going page by page getting the next set of results. To get a specific page from Amazon, add the ItemPage attribute to your existing search set up as shown in the following example:

request.amazon.mySearch.ItemPage="2";
amazonecs.itemSearch(request.amazon.mySearch.toString());

This reissues your search but requests page 2 instead of page 1. You can build a loop or respond to a Next Page request with your application.

Overriding the Amazon ECS service URL

By default, the zero.amazon.ecs API is configured to work with the appropriate Amazon ECS URL. However, if you have a reason to point the extension to a different URL, add the following snippet to your config/zero.config file.

/config/amazon/ecs/serviceURL="http://some.new.url"

This changes the service URL for your project without effecting other users of the zero.amazon.ecs extension.

Additional resources

• Zero Amazon ECS module Javadoc
• Amazon Web Services home page
• Amazon E-Commerce Service Documentation
• Amazon ECS ItemSearch Documentation