So I got bored one afternoon and made a cool little application that uses Amazon Web Services to get information about music. This tutorial will show how to connect to Amazon Web Services and use the information returned from it. This tutorial uses Flex 3.0, so in order to use this code you need to be writing a Flex 3.0 application. Most of the code should be able to be used in Flex 2.0, but no guarantees. You can go grab Flex 3.0 here.

Below you can see the application that we are going to create. All you have to do is type in your search, hit the "Search" button, and your off getting music information. Once you have some results you can select one in the datagrid to get more information about it. This extra information includes the cover art image, album information, and editorial reviews. I apologize for the fact that the application is so narrow, the blog is only about 500px wide. You're welcome to create a wider version if you want . Well then, what are we waiting for? Let's write some flex.

The first thing we're going to do is setup the interface for the application. The code below is the basic application setup with a couple of items to note. At the top of the application the search textbox and button are added, and I also added a small note in the top right hand corner. There is also a datagrid inside the application with four columns - don't mind them just yet. A canvas is added to the application which will hold the extra information about the specific album we are looking at. You will also notice in the code below that I added a gradient property to the <mx:Application> tag to get the nice gradient on the app. You can read more about this property at the Adobe Livedocs here. I also added some alpha transparency to the canvas so the gradient would show up a little on it.


To finish off the user interface lets add the components for the extended information. There aren't any here that are funky so nothing should look off kilter. The only customized item is the textarea used for displaying the reviews which is changed to be uneditable. Besides that element we have a bunch of labels to show data we bring in and an <mx:Image> tag to show the cover art. The code is added right below our opening <mx:Canvas> tagw.


Next thing we are going to do is setup our web service from Amazon, but we have to take care of some janitorial issues first. To be able to use Amazon Web Services we need to get an AWS Access Id. The id is free, all you have to do to get one is sign up at the Web Services website. You can create an account right here. Once you have signed up you can get your AWS Access Id by going to right-hand side of the home page and to "Your Web Services Account" and to "AWS Access Identifiers". This should take you to the page where you can get your access id. The image below shows the location of the "AWS Access Identifiers" link.


Ok, let's get back to the flex code. What we are going to do now is setup the webservice using a <mx:WebService> tag. This tag will go right under our opening application tag. There are a couple of properties we need to make sure we set for this. These include the id, which we use to identify the service later, the wsdl (or Web Service Definition Language), which describes the service and how it can used (and in this case is a link given to us by Amazon), showBusyCursor, and fault event. The fault event tells flex what to do if the service doesn't work.

Inside our <mx:WebService> tag we add an operation (<mx:operation>), which is basically a function that the service has available to call. For this tag we set two properties, which are both very important. The first is name, which is the qualified name of the operation - in this case "ItemSearch" (this is defined by Amazon). The second is resultFormat, which we set to "object". This tells flex to create objects from the xml data we get back from Amazon. This makes it really easy for us to use the data coming back. The last thing we need to do is setup what parameters are sent to the operation.

To set the parameters we use a <mx:request> tag inside the <mx:operation> tag. We then set a few parameters. The first one is the "AWSAccessKeyId", which is given to us by Amazon. The next couple of parameters we send as a "Shared" object by wrapping them in a <Shared> tag. These are the parameters we actually use for the search query. We use "Keywords", "SearchIndex", and "Count", which are pretty self explanatory, but there are tons of parameters that can be sent with this operation. The documentation from Amazon on their operation is pretty good and can be found here - under ECS API Reference -> ECS Operations. So all of this results in the following code which is added right below the opening application tag.


But wait! It won't even compile yet. You will see some compile errors for the missing variable we are using, "keywords", and something about Alert. We need to add some script to import the Alert and create a variable for our keywords. We add a <mx:Script> tag right above our <mx:WebService> tag to do this. The following is the script tag we are creating.


Because we want to actually use the keywords from our text input we use a <mx:Binding> tag to bind our textInput text to our keywords variable. If you need more information on the binding tag check out this earlier tutorial. Our new binding tag goes directly under the closing script tag.


Now we can compile the app but we have no interaction with our new service yet. To do this we need two pieces: some way to send the service a request and a way to handle the data when it comes back. The first is accomplished pretty easily. We do this by adding a click event to our button which will call a function to send an operation request. Our new button code is below.


Adding the function "sendRequest" to our actionscript will now let us call our service. Inside our function we do two things. The first is escape our keywords because amazon needs whitespaces to be changed to "%20". The second is calling the service request. This is accomplished by simply calling the send command on our operation. This function goes inside our script tag.


To process the information coming back we need to add a result event to our operation. This event will call a function with a ResultEvent object passed in as a parameter, which will hold our data. I called this function "showItemSearchResult". Our operation tag looks like the following:


Again, we add this function to our script tag, but we need to add a couple of supporting imports and a variables. The var we create is an ArrayCollection named "itemResults", which we are going to use to put the data into our datagrid. Then in our function we can set our new "itemResults" equal to the array of items returned. To actually find out where in the result object we get the item array you can look through the Amazon documentation. I actually spent some time in the debugger checking out the contents of the res.result object, which helped me determine how to get all the information we need. So our new script block is updated to the following.


With a little work on our datagrid we will be able to display our results from Amazon. The first thing we are going to do is bind our arrayCollection to the dataprovider of the datagrid. We do this inside the <mx:DataGrid> tag. The next thing we need to do is bind the set of info that is going to be displayed in our columns. We are going to use the labelFunction property of the DataGridColumns. Basically this calls a function that returns a string (which will be the data shown). For more information on this look for a upcoming tutorial on advanced dataGrid techniques. The last column, "ASIN", which is Amazon's product Id number, will just be a datafield. Our Datagrid object now looks like:


Wallah! We can now search Amazon for music albums using a keyword search and display the results in our datagrid. The next step is to get the extended data when we select a particular album in the list. This entails pretty much the same kinds of things we did before but we process the data a little differently. The first thing we do is add another operation to the our WebService which will be used to get detailed information about the album we have selected.

This new operation is named "ItemLookup" and we set it up to call a function named "showItemLookupResults" when the results come back. The parameters are added the same way as before but they are a little different. We still pass our access key but our Shared parameters need to be changed. The first is the amazon item id of the current item we have selected (don't worry, we will set this up in a moment). The second parameter we pass is ResponseGroup. This parameter defines the information that will be passed back to us. Again this information can be found in the Amazon documentation. The following code goes inside in the <mx:WebService> tag after the first operation.


Next we do a little actionscript work. We setup three new variables, the one referred to in the new operation and two that are used for the details we process from the web service. We also create our function to receive and process the information we get back from "ItemLookup". We will fill this out in just a second. The new code we add to our script tag is below.


When we get the data back we process it using our "showItemLookupResults" function. To start off we take the item object we get back and set it to "currentItemDetails" (one of the variables we created), next we set the ItemAttributes of this item equal to another one of the variables we created, "currentItemAttr". Really the only reason this var is created is to save space on the blog so the code will fit nicely. We will bind these variables to the UI in a minute.

The next thing done in this function is setting the title. I first check to see if the artist is filled in, and if not I use the string "Unknown" just to make it look nice.Then I set the text of that label to the title string. The editorial reviews take a little bit more work. I first check to see if the incoming review(s) is an ArrayCollection. If there are multiple reviews it is, and if so append each of the reviews together to make a long review. If it is isn't multiple reviews we check to see if there are any reviews at all (if property for reviews is available). If not we just print out "No Reviews Available", otherwise we print out the review(s). The final thing done is setting the image component source to highest quality image or to nothing if they are not available. The following code replaces our recently created "showItemLookupResults" function.


For a quick task we add a new binding statement for our datagrid and the currently selected Item. This is a simple <mx:Binding> tag where the source is the selected item in our datagrid and the destination is our variable. So our new binding code goes right underneath the old one.


To finish off our data bindings we bind the text of several labels to properties of our "currentItemAttr" variable. These include the original release date, number of discs, and label. For the ASIN we bind to our "currentItemDetails". We replace the following labels.





And the very last thing we need to do is actually send the request for the data. We are going to do this using the change event of the datagrid. This is done by simply adding the event to the component and making it send the service request directly from the event property. Now our <mx:DataGrid> tag is in its final state:


Boom Shakalaka! We have a fully working music search using Amazon's great Web Services. I also added a little code to initialize the app on this page, but it isn't important for the tutorial. Here is the full source for the application.


I hope you have found this tutorial helpful and interesting. As an added bonus I decided to create this as an AIR application, which can be downloaded here. If you are interested in Adobe AIR keep an eye out for some AIR tutorials coming soon and check out the Adobe AIR Site. If you have any questions (or comments), please feel free to leave them below.