1Net::Amazon(3) User Contributed Perl Documentation Net::Amazon(3)
2
6 Net::Amazon - Framework for accessing amazon.com via REST
7
9 use Net::Amazon;
10 my $ua = Net::Amazon->new(
12 associate_tag => 'YOUR_AMZN_ASSOCIATE_TAG',
13 token => 'YOUR_AMZN_TOKEN',
14 secret_key => 'YOUR_AMZN_SECRET_KEY');
15 # Get a request object
17 my $response = $ua->search(asin => '0201360683');
18 if($response->is_success()) {
20 print $response->as_string(), "\n";
21 } else {
22 print "Error: ", $response->message(), "\n";
23 }
24
26 Net::Amazon provides an object-oriented interface to amazon.com's
27 REST interface. This way it's possible to create applications
28 using Amazon's vast amount of data via a functional interface, without
29 having to worry about the underlying communication mechanism.
30
32 "Net::Amazon" works very much like "LWP": First you define a useragent
33 like
34 my $ua = Net::Amazon->new(
36 associate_tag => 'YOUR_AMZN_ASSOCIATE_TAG',
37 token => 'YOUR_AMZN_TOKEN',
38 secret_key => 'YOUR_AMZN_SECRET_KEY',
39 max_pages => 3,
40 );
41 which you pass your personal amazon developer's token (can be obtained
43 from <http://amazon.com/soap>) and (optionally) the maximum number of
44 result pages the agent is going to request from Amazon in case all
45 results don't fit on a single page (typically holding 20 items). Note
46 that each new page requires a minimum delay of 1 second to comply with
47 Amazon's one-query-per-second policy.
48 According to the different search methods on Amazon, there's a bunch of
50 different request types in "Net::Amazon". The user agent's convenience
51 method "search()" triggers different request objects, depending on
52 which parameters you pass to it:
53 "$ua->search(asin => "0201360683")"
55 The "asin" parameter has Net::Amazon search for an item with the
56 specified ASIN. If the specified value is an arrayref instead of a
57 single scalar, like in
58 $ua->search(asin => ["0201360683", "0596005083"])
60 then a search for multiple ASINs is performed, returning a list of
62 results.
63 "$ua->search(actor => "Adam Sandler")"
65 The "actor" parameter has the user agent search for items created
66 by the specified actor. Can return many results.
67 "$ua->search(artist => "Rolling Stones")"
69 The "artist" parameter has the user agent search for items created
70 by the specified artist. Can return many results.
71 "$ua->search(author => "Robert Jordan")"
73 The "author" parameter has the user agent search for items created
74 by the specified author. Can return many results.
75 "$ua->search(browsenode=>"4025", mode=>"books" [, keywords=>"perl"])"
77 Returns a list of items by category ID (node). For example node
78 "4025" is the CGI books category. You can add a keywords parameter
79 to filter the results by that keyword.
80 "$ua->search(exchange => 'Y04Y3424291Y2398445')"
82 Returns an item offered by a third-party seller. The item is
83 referenced by the so-called exchange ID.
84 "$ua->search(keyword => "perl xml", mode => "books")"
86 Search by keyword, mandatory parameters "keyword" and "mode". Can
87 return many results.
88 DETAILS
90 Net::Amazon is based on Amazon Web Services version 4, and
91 uses
92 WSDL version 2011-08-01.
93
95 Responses returned by Amazon's web service can be cached locally.
96 "Net::Amazon"'s "new" method accepts a reference to a "Cache" object.
97 "Cache" (or one of its companions like "Cache::Memory", "Cache::File",
98 etc.) can be downloaded from CPAN, please check their documentation for
99 details. In fact, any other type of cache implementation will do as
100 well, see the requirements below.
101 Here's an example utilizing a file cache which causes "Net::Amazon" to
103 cache responses for 30 minutes:
104 use Cache::File;
106 my $cache = Cache::File->new(
108 cache_root => '/tmp/mycache',
109 default_expires => '30 min',
110 );
111 my $ua = Net::Amazon->new(
113 token => 'YOUR_AMZN_TOKEN',
114 secret_key => 'YOUR_AMZN_SECRET_KEY',
115 cache => $cache,
116 );
117 "Net::Amazon" uses positive caching only, errors won't be cached.
119 Erroneous requests will be sent to Amazon every time. Positive cache
120 entries are keyed by the full URL used internally by requests submitted
121 to Amazon.
122 Caching isn't limited to the "Cache" class. Any cache object which
124 adheres to the following interface can be used:
125 # Set a cache value
127 $cache->set($key, $value);
128 # Return a cached value, 'undef' if it doesn't exist
130 $cache->get($key);
131
133 "Net::Amazon" uses "LWP::UserAgent" under the hood to send web requests
134 to Amazon's web site. If you're in an environment where all Web traffic
135 goes through a proxy, there's two ways to configure that.
136 First, "Net::Amazon" picks up proxy settings from environment
138 variables:
139 export http_proxy=http://proxy.my.place:8080
141 in the surrounding shell or setting
143 $ENV{http_proxy} = "http://proxy.my.place:8080";
145 in your Perl script will route all requests through the specified
147 proxy.
148 Secondly, you can pass a user agent instance to Net::Amazon's
150 constructor:
151 use Net::Amazon;
153 use LWP::UserAgent;
154 my $ua = LWP::UserAgent->new();
156 my $na = Net::Amazon->new(
157 ua => $ua,
158 associate_tag => 'YOUR_AMZN_ASSOCIATE_TAG',
159 token => 'YOUR_AMZN_TOKEN',
160 secret_key => 'YOUR_AMZN_SECRET_KEY',
161 );
162 # ...
163 This way, you can configure $ua up front before Net::Amazon will use
165 it.
166
168 If something's going wrong and you want more verbosity, just bump up
169 "Net::Amazon"'s logging level. "Net::Amazon" comes with "Log::Log4perl"
170 statements embedded, which are disabled by default. However, if you
171 initialize "Log::Log4perl", e.g. like
172 use Net::Amazon;
174 use Log::Log4perl qw(:easy);
175 Log::Log4perl->easy_init($DEBUG);
177 my Net::Amazon->new();
178 # ...
179 you'll see what's going on behind the scenes, what URLs the module is
181 requesting from Amazon and so forth. Log::Log4perl allows all kinds of
182 fancy stuff, like writing to a file or enabling verbosity in certain
183 parts only -- check http://log4perl.sourceforge.net for details.
184
186 Results returned by Amazon can be incomplete or simply wrong at times,
187 due to their "best effort" design of the service. This is why the test
188 suite that comes with this module has been changed to perform its test
189 cases against canned data. If you want to perform the tests against the
190 live Amazon servers instead, just set the environment variable
191 NET_AMAZON_LIVE_TESTS=1
193
195 Because nobody wrote it yet. If Net::Amazon doesn't yet support a
196 method advertised on Amazon's web service, you could help us out.
197 Net::Amazon has been designed to be expanded over time, usually it only
198 takes a couple of lines to support a new method, the rest is done via
199 inheritance within Net::Amazon.
200 Here's the basic plot:
202 · Get Net::Amazon from CVS. Use
204 # (Just hit enter when prompted for a password)
206 cvs -d:pserver:anonymous@cvs.net-amazon.sourceforge.net:/cvsroot/net-amazon login
207 cvs -z3 -d:pserver:anonymous@cvs.net-amazon.sourceforge.net:/cvsroot/net-amazon co Net-Amazon
208 If this doesn't work, just use the latest distribution from
210 net-amazon.sourceforge.net.
211 · Write a new Net::Amazon::Request::XYZ package, start with this
213 template
214 ######################################
216 package Net::Amazon::Request::XYZ;
217 ######################################
218 use base qw(Net::Amazon::Request);
219 ######################################
221 sub new {
222 ######################################
223 my($class, %options) = @_;
224 if(!exists $options{XYZ_option}) {
226 die "Mandatory parameter 'XYZ_option' not defined";
227 }
228 my $self = $class->SUPER::new(%options);
230 bless $self, $class; # reconsecrate
232 }
233 and add documentation. Then, create a new
235 Net::Amazon::Response::XYZ module:
236 ##############################
238 package Net::Amazon::Response;
239 ##############################
240 use base qw(Net::Amazon::Response);
241 use Net::Amazon::Property;
243 ##############################
245 sub new {
246 ##############################
247 my($class, %options) = @_;
248 my $self = $class->SUPER::new(%options);
250 bless $self, $class; # reconsecrate
252 }
253 and also add documentation to it. Then, add the line
255 use Net::Amazon::Request::XYZ;
257 to Net/Amazon.pm.
259 And that's it! Again, don't forget the add documentation part. Modules
261 without documentation are of no use to anybody but yourself.
262 Check out the different Net::Amazon::Request::* and
264 Net::Amazon::Response modules in the distribution if you need to adapt
265 your new module to fulfil any special needs, like a different Amazon
266 URL or a different way to handle the as_string() method. Also, post and
267 problems you might encounter to the mailing list, we're gonna help you
268 out.
269 If possible, provide a test case for your extension. When finished,
271 send a patch to the mailing list at
272 net-amazon-devel@lists.sourceforge.net
274 and if it works, I'll accept it and will work it into the main
276 distribution. Your name will show up in the contributor's list below
277 (unless you tell me otherwise).
278 SAMPLE SCRIPTS
280 There's a number of useful scripts in the distribution's eg/ directory.
281 Take "power" for example, written by Martin Streicher
282 <martin.streicher@apress.com>: I lets you perform a power search using
283 Amazon's query language. To search for all books written by Randal
284 Schwartz about Perl, call this from the command line:
285 power 'author: schwartz subject: perl'
287 Note that you need to quote the query string to pass it as one argument
289 to "power". If a power search returns more results than you want to
290 process at a time, just limit the number of pages, telling "power"
291 which page to start at ("-s") and which one to finish with ("-f").
292 Here's a search for all books on the subject "computer", limited to the
293 first 10 pages:
294 power -s 1 -f 10 'subject: computer'
296 Check out the script "power" in eg/ for more options.
298 HOW TO SEND ME PATCHES
300 If you want me to include your modification or enhancement in the
301 distribution of Net::Amazon, please do the following:
302 · Work off the latest CVS version. Here's the steps to get it:
304 CVSROOT=:pserver:anonymous@cvs.net-amazon.sourceforge.net:/cvsroot/net-amazon
306 export CVSROOT
307 cvs login (just hit Enter)
308 cvs co Net-Amazon
309 This will create a new "Net-Amazon" directory with the latest
311 development version of "Net::Amazon" on your local machine.
312 · Apply your changes to this development tree.
314 · Run a diff between the tree and your changes it in this way:
316 cd Net-Amazon
318 cvs diff -Nau >patch_to_christopher.txt
319 · Email me "patch_to_christopher.txt". If your patch works (and
321 you've included test cases and documentation), I'll apply it on the
322 spot.
323
325 "Net::Amazon" depends on Log::Log4perl, which can be pulled from CPAN
326 by simply saying
327 perl -MCPAN -eshell 'install Log::Log4perl'
329 Also, it needs LWP::UserAgent and XML::Simple 2.x, which can be
331 obtained in a similar way.
332 Once all dependencies have been resolved, "Net::Amazon" installs with
334 the typical sequence
335 perl Makefile.PL
337 make
338 make test
339 make install
340 Make sure you're connected to the Internet while running "make test"
342 because it will actually contact amazon.com and run a couple of live
343 tests.
344 The module's distribution tarball and documentation are available at
346 http://perlmeister.com/devel/#amzn
348 and on CPAN.
350
352 The following modules play well within the "Net::Amazon" framework:
353 "Net::Amazon::RemoteCart"
355 by David Emery <dave@skiddlydee.com> provides a complete API for
356 creating Amazon shopping carts on a local site, managing them and
357 finally submitting them to Amazon for checkout. It is available on
358 CPAN.
359
361 The "Net::Amazon" project's home page is hosted on
362 http://net-amazon.sourceforge.net
364 where you can find documentation, news and the latest development and
366 stable releases for download. If you have questions about how to use
367 "Net::Amazon", want to report a bug or just participate in its
368 development, please send a message to the mailing list
369 net-amazon-devel@lists.sourceforge.net
370 The source code has moved from sourceforge.net to github.com. The git
372 URL is
373 git://github.com/boumenot/p5-Net-Amazon.git
375 The hope is that github.com makes collaboration much easier, and git is
377 a much more modern SCM tool.
378
380 Mike Schilli, <na@perlmeister.com> (Please contact me via the mailing
381 list: net-amazon-devel@lists.sourceforge.net )
382 Maintainers: Christopher Boumenot, <boumenot+na@gmail.com>
384 Contributors (thanks y'all!):
386 Andy Grundman <andy@hybridized.org>
388 Barnaby Claydon <bclaydon@perseus.com>
389 Batara Kesuma <bkesuma@gaijinweb.com>
390 Bill Fitzpatrick
391 Brian <brianbrian@gmail.com>
392 Brian Hirt <bhirt@mobygames.com>
393 Dan Kreft <dan@kreft.net>
394 Dan Sully <daniel@electricrain.com>
395 Jackie Hamilton <kira@cgi101.com>
396 Konstantin Gredeskoul <kig@get.topica.com>
397 Lance Cleveland <lancec@proactivewm.com>
398 Martha Greenberg <marthag@mit.edu>
399 Martin Streicher <martin.streicher@apress.com>
400 Mike Evron <evronm@dtcinc.net>
401 Padraic Renaghan <padraic@renaghan.com>
402 rayg <rayg@varchars.com>
403 Robert Graff <rgraff@workingdemo.com>
404 Robert Rothenberg <wlkngowl@i-2000.com>
405 Steve Rushe <steve@deeden.co.uk>
406 Tatsuhiko Miyagawa <miyagawa@livedoor.jp>
407 Tony Bowden <tony@kasei.com>
408 Vince Veselosky
409
411 Copyright 2003, 2004 by Mike Schilli <na@perlmeister.com> Copyright
412 2007-2009 by Christopher Boumenot <boumenot+na@gmail.com>
413 This library is free software; you can redistribute it and/or modify it
415 under the same terms as Perl itself.
416
418 Hey! The above document had some coding errors, which are explained
419 below:
420 Around line 748:
422 You forgot a '=back' before '=head1'
423perl v5.12.4 2011-10-29 Net::Amazon(3)