A To Z, And Everything In Between
Everyone, but everyone, knows what Amazon.com is - it's the largest (and, for my money, coolest) online store on the planet, selling everything from baby clothes to the new Volkswagen Beetle. It's been around since the beginning of the Web and offers one of the friendliest shopping experiences online, together with great customer service and a wide variety of discounts.
One of the reasons for Amazon's dominance in the online shopping space is its creativity - the store's managers are constantly coming up with innovative new ideas to simplify and enhance the customer experience. And one of the cooler new ideas to emerge from Amazon HQ in recent months has been Amazon Web Services, a set of APIs designed to let users query the complete Amazon database using a series of SOAP-based remote procedure calls. These Web services allow regular users to easily create online stores that leverage off Amazon's experience (and huge product catalog), and to build cutting-edge e-commerce applications quickly and efficiently.
Now, your favourite language and mine, PHP, has recently started shipping with support for XML-based remote procedure calls (including SOAP) over HTTP. This makes PHP ideal for developers looking to integrate Amazon Web Services into their Web applications. The only problem? Not too many people know how to do it.
That's where this tutorial comes in. Over the next few pages, I'll be demonstrating how you can use PHP, in combination with Amazon Web Services, to add powerful new capabilities to your Web applications. Take a look.
Remote Control
Before we get into the code, though, you need to have a clear understanding of how Amazon Web Services, aka AWS, works. This involves getting up close and personal with a complicated little critter known as SOAP, the Simple Object Access Protocol.
According to the primer available on the W3C's site (http://www.w3.org/2002/ws/), SOAP is a "lightweight protocol for exchange of information in a decentralized, distributed environment. It is an XML based protocol at the core of which is an envelope that defines a framework for describing what is in a message and how to process it and a transport binding framework for exchanging messages using an underlying protocol."
If you're anything like me, that probably made very little sense to you. So here's the Reader's Digest version, which is far more cogent: "SOAP is a simple XML based protocol to let applications exchange information over HTTP." (http://www.w3schools.com/soap/soap_intro.asp)
SOAP is a client-server paradigm which builds on existing Internet technologies to simplify the task of invoking procedures and accessing objects across a network. It uses XML to encode procedure invocations (and decode procedure responses) into a package suitable for transmission across a network, and HTTP to actually perform the transmission.
At one end of the connection, a SOAP server receives SOAP requests containing procedure calls, decodes them, invokes the function and packages the response into a SOAP packet suitable for retransmission back to the requesting client. The client can then decode the response and use the results of the procedure invocation in whatever manner it chooses. The entire process is fairly streamlined and, because of its reliance on existing standards, relatively easy to understand and use.
Here's a quick example of what a SOAP request for the procedure getFlavourOfTheDay() might look like:
<?xml version="1.0" ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:si="http://soapinterop.org/xsd" xmlns:ns6="http://testuri.org" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns6:getFlavourOfTheDay>
<day xsi:type="xsd:string">monday</day>
</ns6:getFlavourOfTheDay>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
And here's what the response might look like:
<?xml version="1.0" ?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:si="http://soapinterop.org/xsd" xmlns:ns6="http://testuri.org" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<SOAP-ENV:Body>
<ns6:getFlavourOfTheDayResponse>
<flavour xsi:type="xsd:string">pineapple</flavour>
</ns6:getFlavourOfTheDayResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
I'm not going to get into the details of how SOAP works in this article, preferring instead to focus on how SOAP can be exploited in the context of PHP and AWS. If you're new to SOAP, the information above should be sufficient to explain the basic concepts and ensure that you can follow the material that comes next; however, if you're interested in learning more about SOAP (or if you just have trouble falling asleep at night), you should read the W3C's specifications on the protocol - links will be included at the end of this article.
The Bare Necessities
There are a couple of things you'll need before you can get started with PHP and AWS. Obviously, you need a working build of PHP - I recommend the latest version, PHP 4.2.3, which you can download from http://www.php.net/
You'll also need an external PHP class named NuSOAP, which exposes a number of methods that can be used to instantiate a SOAP client and perform SOAP transactions over HTTP. You can download NuSOAP from http://dietrich.ganx4.com/.
Finally, you need a ticket to the Amazon.com gravy train. Drop by http://www.amazon.com/webservices/, register with Amazon.com, and pick up your free developer token. This developer token will be used in all your interaction with AWS, so handle it carefully - you're going to need it very soon.
While you're on the Amazon.com Web site, you might also want to download the AWS software development kit, which contains numerous examples of how AWS can be used on different platforms, together with detailed documentation of the AWS API. Be sure to read the SOAP development guidelines in the AWS documentation, so that you don't inadvertently burn down Amazon's servers.
All set up? Let's rock and roll.
Anatomy Class
Amazon has made a number of important method calls available in the AWS API - here's a brief list:
BrowseNodeSearchRequest() - retrieve a list of catalog items attached to a particular node in the Amazon database;
ASINSearchRequest() - retrieve detailed information for a given product code;
KeywordSearchRequest() - perform a keyword search on the Amazon database;
SellerSearchRequest() - perform a search for products listed by third-party sellers;
PowerSearchRequest() - perform an advanced search on the Amazon database;
SimilaritySearchRequest() - perform a search for similar items, given a specific product code.
Additionally, AWS includes methods to search for authors, actors, directors, artists, manufacturers, wish lists and user lists.
This might not seem like much to start with - but, as you'll see, looks are deceptive. Consider the following simple example, which provides a gentle introduction to the power of AWS:
<?php
// include class
include("nusoap.php");
// create a instance of the SOAP client object
// remember that this script is the client,
// accessing the web service provided by Amazon.com
$soapclient = new soapclient("http://soap.amazon.com/schemas2/AmazonWebServices.wsdl", true);
// uncomment the next line to see debug messages
// $soapclient->debug_flag = 1;
// create a proxy so that WSDL methods can be accessed directly
$proxy = $soapclient->getProxy();
// set up an array containing input parameters to be
// passed to the remote procedure
$params = array(
'browse_node' => 18,
'page' => 1,
'mode' => 'books',
'tag' => 'melonfire-20',
'type' => 'lite',
'devtag' => 'YOUR-TOKEN-HERE'
);
// invoke the method
$result = $proxy->BrowseNodeSearchRequest($params);
// print the results of the search
print_r($result);
?>
The first order of business is to include the SOAP class which contains all the methods needed to access SOAP services.
<?php
// include the class
include("nusoap.php");
?>
Now, in this SOAP universe, Amazon provides the SOAP server, and this PHP script works as the client. So, the next step is to instantiate this client, using the class constructs provided by NuSOAP.
<?php
// create a instance of the SOAP client object
// remember that this script is the client,
// accessing the web service provided by Amazon.com
$soapclient = new soapclient("http://soap.amazon.com/schemas2/AmazonWebServices.wsdl", true);
?>
The class constructor accepts a single parameter, which is the URL of the SOAP service to be accessed (this is sometimes referred to by geeks as the "endpoint"). In case you're wondering where I got this URL from - it's listed in the AWS documentation. So there!
In order to simplify usage of the AWS API, I've created a "proxy client", one which lets me directly invoke AWS methods, rather than passing them to the NuSOAP class' call() method.
<?php
// create a proxy so that WSDL methods can be accessed directly
$proxy = $soapclient->getProxy();
?>
All that remains is to send a request to the SOAP server via this proxy,
<?php
// invoke the method
$result = $proxy->BrowseNodeSearchRequest($params);
?>
and print the resulting output.
<?php
// print the results of the search
print_r($result);
?>
In this case, I'm calling the BrowseNodeSearchRequest() method on the AWS SOAP server, and passing it a list of arguments (this argument list is also documented in the AWS API). This argument list is stored in the $params array, which looks like this:
<?php
// set up an array containing input parameters to be
// passed to the remote procedure
$params = array(
'browse_node' => 18,
'page' => 1,
'mode' => 'books',
'tag' => 'melonfire-20',
'type' => 'lite',
'devtag' => 'YOUR-TOKEN-HERE'
);
?>
Here's what those arguments mean:
- The "browse_node" argument specifies the node to begin with in the catalog. This node ID can be obtained by visiting the Amazon.com Web site and looking at the URL for the section you're interested in browsing. For example, the URL
http://www.amazon.com/exec/obidos/tg/browse/-/18
points to the Mystery category in Amazon's bookstore and has node ID 18.
In case this seems like too much work, a list of the most popular node IDs is available in the AWS documentation.
- The "page" argument specifies the page offset to display. AWS is currently hard-wired to display 10 items per page, so if you wanted to display items 11-20, you would need to set
'page' => 2
and so on.
- The "mode" argument specifies the particular store to browse. As of this writing, AWS defines 16 stores, each with a unique "mode" identifier - here's a list of the ones I visit most often:
Books: 'mode' => 'books'
Popular Music: 'mode' => 'music'
Electronics: 'mode' => 'electronics'
DVD: 'mode' => 'dvd'
Computers: 'mode' => 'pc-hardware'
Software: 'mode' => 'software'
Toys: 'mode' => 'toys'
Again, a complete list of stores is available in the AWS documentation.
4. The "tag" argument specifies your Amazon.com Associates ID, if you have one. In case you don't, and if you're serious about building an online store with AWS, I suggest you get one post-haste from http://associates.amazon.com/, since it entitles you to a commission on every purchase made via your site.
5. The "type" argument specifies the type of result set you would like. AWS gives you two choices - "lite", which contains basic product information, and "heavy", which contains detailed product information. I'll show you both in this article.
6. Finally, remember that developer token you got when you first registered for AWS? You need to specify it via the "devtag" argument in order to use AWS; if it isn't included in the argument list, AWS will deny you access.
If you take a look at the internals of the SOAP class, you'll see that the proxy uses the class' call() method and the arguments passed to it to generate a SOAP request, which looks something like this:
POST /onca/soap2 HTTP/1.0 User-Agent: NuSOAP/0.6.3 Host: soap.amazon.com Content-Type: text/xml Content-Length: 942 SOAPAction: "urn:PI/DevCentral/SoapService"
<?xml version="1.0" encoding="ISO-8859-1"?>
<SOAP-ENV:Envelope SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" xmlns:si="http://soapinterop.org/xsd" xmlns:typens="urn:PI/DevCentral/SoapService">
<SOAP-ENV:Body>``<typens:BrowseNodeSearchRequest>
<BrowseNodeSearchRequest xsi:type="typens:BrowseNodeRequest">
<browse_node xsi:type="xsd:string">
18<page xsi:type="xsd:string">
1<mode xsi:type="xsd:string">
books<tag xsi:type="xsd:string">
melonfire-20<type xsi:type="xsd:string">
lite<devtag xsi:type="xsd:string">
YOUR-TOKEN-HERE<sort xsi:type="xsd:string">
18</typens:BrowseNodeSearchRequest>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>
This request packet is transmitted to the SOAP server using the POST method, and a server response packet is transmitted back to the client. Here's what one such packet might look like:
HTTP/1.1 200 OK Date: Tue, 05 Nov 2002 15:38:54 GMT Server: Stronghold/2.4.2 Apache/1.3.6 C2NetEU/2412 (Unix) mod_fastcgi/2.2.10 Connection: close Content-Type: text/xml
<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" SOAP-ENV:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:amazon="urn:PI/DevCentral/SoapService">
<SOAP-ENV:Body>
<namesp44:BrowseNodeSearchRequestResponse xmlns:namesp44="urn:PI/DevCentral/SoapService">
<return xsi:type="amazon:ProductInfo">
<TotalResults xsi:type="xsd:string">
55656
<Details SOAP-ENC:arrayType="amazon:Details[10]" xsi:type="SOAP-ENC:Array">
<Details xsi:type="amazon:Details">``<Url xsi:type="xsd:string">
http://www.amazon.com/exec/obidos/redirect?tag=melonfire-20%26creative=YOUR-TOKEN-HERE%26camp=2025%26link_code=sp1%26path=ASIN/0060092572<Asin xsi:type="xsd:string">
0060092572<ProductName xsi:type="xsd:string">
The Terminal Man<Catalog xsi:type="xsd:string">
Book<Authors SOAP-ENC:arrayType="xsd:string[1]" xsi:type="SOAP-ENC:Array">``<Author xsi:type="xsd:string">
Michael Crichton<ReleaseDate xsi:type="xsd:string">
05 November, 2002<Manufacturer xsi:type="xsd:string">
Avon<ImageUrlSmall xsi:type="xsd:string">
http://images.amazon.com/images/P/0060092572.01.THUMBZZZ.jpg<ImageUrlMedium xsi:type="xsd:string">
http://images.amazon.com/images/P/0060092572.01.MZZZZZZZ.jpg<ImageUrlLarge xsi:type="xsd:string">
http://images.amazon.com/images/P/0060092572.01.LZZZZZZZ.jpg<ListPrice xsi:type="xsd:string">
$7.99<OurPrice xsi:type="xsd:string">
$7.99<UsedPrice xsi:type="xsd:string">
$4.00
<Details xsi:type="amazon:Details">``<Url xsi:type="xsd:string">
http://www.amazon.com/exec/obidos/redirect?tag=melonfire-20%26creative=YOUR-TOKEN-HERE%26camp=2025%26link_code=sp1%26path=ASIN/0060505397<Asin xsi:type="xsd:string">
0060505397<ProductName xsi:type="xsd:string">
Bet Your Life<Catalog xsi:type="xsd:string">
Book<Authors SOAP-ENC:arrayType="xsd:string[1]" xsi:type="SOAP-ENC:Array">``<Author xsi:type="xsd:string">
Richard Dooling<ReleaseDate xsi:type="xsd:string">
05 November, 2002<Manufacturer xsi:type="xsd:string">
HarperCollins<ImageUrlSmall xsi:type="xsd:string">
http://images.amazon.com/images/P/0060505397.01.THUMBZZZ.jpg<ImageUrlMedium xsi:type="xsd:string">
http://images.amazon.com/images/P/0060505397.01.MZZZZZZZ.jpg<ImageUrlLarge xsi:type="xsd:string">
http://images.amazon.com/images/P/0060505397.01.LZZZZZZZ.jpg<ListPrice xsi:type="xsd:string">
$25.95<OurPrice xsi:type="xsd:string">
$18.17<UsedPrice xsi:type="xsd:string">
$12.98
... and so on...
</namesp44:BrowseNodeSearchRequestResponse> </SOAP-ENV:Body> </SOAP-ENV:Envelope>
This response packet is decoded by the client into a native PHP structure, which can be used within the script. At the moment, all I'm doing is printing it - and here's what the output looks like:
Array ( [TotalResults] => 55656 [Details] => Array ( [0] => Array ( [Url] => http://www.amazon.com/exec/obidos/redirect?tag=melonfire-20%26creative=YOUR-TOKEN-HERE%26camp=2025%26link_code=sp1%26path=ASIN/0060092572 [Asin] => 60092572 [ProductName] => The Terminal Man [Catalog] => Book [Authors] => Array ( [0] => Michael Crichton )
[ReleaseDate] => 05 November, 2002
[Manufacturer] => Avon
[ImageUrlSmall] => http://images.amazon.com/images/P/0060092572.01.THUMBZZZ.jpg
[ImageUrlMedium] => http://images.amazon.com/images/P/0060092572.01.MZZZZZZZ.jpg
[ImageUrlLarge] => http://images.amazon.com/images/P/0060092572.01.LZZZZZZZ.jpg
[ListPrice] => $7.99
[OurPrice] => $7.99
[UsedPrice] => $4.00
)
[1] => Array
(
[Url] => http://www.amazon.com/exec/obidos/redirect?tag=melonfire-20%26creative=YOUR-TOKEN-HERE%26camp=2025%26link_code=sp1%26path=ASIN/0060505397
[Asin] => 60505397
[ProductName] => Bet Your Life
[Catalog] => Book
[Authors] => Array
(
[0] => Richard Dooling
)
[ReleaseDate] => 05 November, 2002
[Manufacturer] => HarperCollins
[ImageUrlSmall] => http://images.amazon.com/images/P/0060505397.01.THUMBZZZ.jpg
[ImageUrlMedium] => http://images.amazon.com/images/P/0060505397.01.MZZZZZZZ.jpg
[ImageUrlLarge] => http://images.amazon.com/images/P/0060505397.01.LZZZZZZZ.jpg
[ListPrice] => $25.95
[OurPrice] => $18.17
[UsedPrice] => $12.98
)
... and so on ...
[9] => Array
(
[Url] => http://www.amazon.com/exec/obidos/redirect?tag=melonfire-20%26creative=YOUR-TOKEN-HERE%26camp=2025%26link_code=sp1%26path=ASIN/0195122623
[Asin] => 195122623
[ProductName] => Arthur Conan Doyle: Beyond Baker Street (Oxford Portraits Series)
[Catalog] => Book
[Authors] => Array
(
[0] => Janet B. Pascal
)
[ReleaseDate] => March, 2000
[Manufacturer] => Oxford Univ Pr Childrens Books
[ImageUrlSmall] => http://images.amazon.com/images/P/0195122623.01.THUMBZZZ.jpg
[ImageUrlMedium] => http://images.amazon.com/images/P/0195122623.01.MZZZZZZZ.jpg
[ImageUrlLarge] => http://images.amazon.com/images/P/0195122623.01.LZZZZZZZ.jpg
[ListPrice] => $24.00
[OurPrice] => $24.00
[UsedPrice] => $5.49
)
)
)
Obviously, this is not very useful - but we're just getting started. Flip the page, and I'll show you how to massage all this raw data into something a little less ugly.
## The Bookworm Turns
If you take a close look at the output of the previous example, you'll see that the call to BrowseNodeSearchRequest() results in a PHP associative array containing a series of result elements. It's extremely simple to convert the raw data contained within this array into a properly-formatted HTML page. Watch!
<?php // include class include("nusoap.php");
// create a instance of the SOAP client object $soapclient = new soapclient("http://soap.amazon.com/schemas2/AmazonWebServices.wsdl", true);
// uncomment the next line to see debug messages // $soapclient->debug_flag = 1;
// create a proxy so that WSDL methods can be accessed directly $proxy = $soapclient->getProxy();
// set up an array containing input parameters to be // passed to the remote procedure $params = array( 'browse_node' => 18, 'page' => 1, 'mode' => 'books', 'tag' => 'melonfire-20', 'type' => 'lite', 'devtag' => 'YOUR-TOKEN-HERE' );
// invoke the method $result = $proxy->BrowseNodeSearchRequest($params);
if ($result['faultstring']) {
?>
<h2>
Error
<?php echo $result['faultstring']; ?>
<?php
} else {
$total = $result['TotalResults'];
$items = $result['Details'];
// format and display the results ?>
<html>
<head>
<basefont face="Verdana">
<body bgcolor="white">
<p> <p>
<table width="100%" cellspacing="0" cellpadding="5">
<tr>
<td bgcolor="Navy">``<font color="white" size="-1">``<b>Welcome to The Mystery Bookstore!</b>
<td bgcolor="Navy" align="right">``<font color="white" size="-1">``<b><?php echo date("d M Y", mktime()); ?></b>
<p>
Browse the catalog below, or search for a specific title.
<p>
<table width="100%" border="0" cellspacing="5" cellpadding="0">
<?php
// parse the $items[] array and extract the necessary information
// (image, price, title, author, item URL)
foreach ($items as $i) {
?>
<tr>
<td align="center" valign="top" rowspan="3">``<a href="<?php echo $i['Url']; ?>">``<img border="0" src=<?php echo $i['ImageUrlSmall']; ?>>
<td>``<font size="-1">``<b><?php echo $i['ProductName']; ?></b>
/ <?php echo implode(", ", $i['Authors']); ?>
<tr>
<td align="left" valign="top">``<font size="-1">
List Price: <?php echo $i['ListPrice']; ?> / Amazon.com Price: <?php echo $i['OurPrice']; ?>
<tr>
<td align="left" valign="top">``<font size="-1">``<a href="<?php echo $i['Url']; ?>">
Read more about this title on Amazon.com
<tr>
<td colspan=2>
<?php
} ?>
<font size="-1">
Disclaimer: All product data on this page belongs to Amazon.com. No guarantees are made as to accuracy of prices and information. YMMV!