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 By default "Net::Amazon" will attempt to use HTTP compression if the
134 Compress::Zlib module is available. Pass "compress => 0" to "->new()"
135 to disable this feature.
136
138 "Net::Amazon" uses "LWP::UserAgent" under the hood to send web requests
139 to Amazon's web site. If you're in an environment where all Web traffic
140 goes through a proxy, there's two ways to configure that.
141 First, "Net::Amazon" picks up proxy settings from environment
143 variables:
144 export http_proxy=http://proxy.my.place:8080
146 in the surrounding shell or setting
148 $ENV{http_proxy} = "http://proxy.my.place:8080";
150 in your Perl script will route all requests through the specified
152 proxy.
153 Secondly, you can pass a user agent instance to Net::Amazon's
155 constructor:
156 use Net::Amazon;
158 use LWP::UserAgent;
159 my $ua = LWP::UserAgent->new();
161 my $na = Net::Amazon->new(
162 ua => $ua,
163 associate_tag => 'YOUR_AMZN_ASSOCIATE_TAG',
164 token => 'YOUR_AMZN_TOKEN',
165 secret_key => 'YOUR_AMZN_SECRET_KEY',
166 );
167 # ...
168 This way, you can configure $ua up front before Net::Amazon will use
170 it.
171
173 If something's going wrong and you want more verbosity, just bump up
174 "Net::Amazon"'s logging level. "Net::Amazon" comes with "Log::Log4perl"
175 statements embedded, which are disabled by default. However, if you
176 initialize "Log::Log4perl", e.g. like
177 use Net::Amazon;
179 use Log::Log4perl qw(:easy);
180 Log::Log4perl->easy_init($DEBUG);
182 my Net::Amazon->new();
183 # ...
184 you'll see what's going on behind the scenes, what URLs the module is
186 requesting from Amazon and so forth. Log::Log4perl allows all kinds of
187 fancy stuff, like writing to a file or enabling verbosity in certain
188 parts only -- check http://log4perl.sourceforge.net for details.
189
191 Results returned by Amazon can be incomplete or simply wrong at times,
192 due to their "best effort" design of the service. This is why the test
193 suite that comes with this module has been changed to perform its test
194 cases against canned data. If you want to perform the tests against the
195 live Amazon servers instead, just set the environment variable
196 NET_AMAZON_LIVE_TESTS=1
198
200 Because nobody wrote it yet. If Net::Amazon doesn't yet support a
201 method advertised on Amazon's web service, you could help us out.
202 Net::Amazon has been designed to be expanded over time, usually it only
203 takes a couple of lines to support a new method, the rest is done via
204 inheritance within Net::Amazon.
205 Here's the basic plot:
207 · Get Net::Amazon from CVS. Use
209 # (Just hit enter when prompted for a password)
211 cvs -d:pserver:anonymous@cvs.net-amazon.sourceforge.net:/cvsroot/net-amazon login
212 cvs -z3 -d:pserver:anonymous@cvs.net-amazon.sourceforge.net:/cvsroot/net-amazon co Net-Amazon
213 If this doesn't work, just use the latest distribution from
215 net-amazon.sourceforge.net.
216 · Write a new Net::Amazon::Request::XYZ package, start with this
218 template
219 ######################################
221 package Net::Amazon::Request::XYZ;
222 ######################################
223 use base qw(Net::Amazon::Request);
224 ######################################
226 sub new {
227 ######################################
228 my($class, %options) = @_;
229 if(!exists $options{XYZ_option}) {
231 die "Mandatory parameter 'XYZ_option' not defined";
232 }
233 my $self = $class->SUPER::new(%options);
235 bless $self, $class; # reconsecrate
237 }
238 and add documentation. Then, create a new
240 Net::Amazon::Response::XYZ module:
241 ##############################
243 package Net::Amazon::Response;
244 ##############################
245 use base qw(Net::Amazon::Response);
246 use Net::Amazon::Property;
248 ##############################
250 sub new {
251 ##############################
252 my($class, %options) = @_;
253 my $self = $class->SUPER::new(%options);
255 bless $self, $class; # reconsecrate
257 }
258 and also add documentation to it. Then, add the line
260 use Net::Amazon::Request::XYZ;
262 to Net/Amazon.pm.
264 And that's it! Again, don't forget the add documentation part. Modules
266 without documentation are of no use to anybody but yourself.
267 Check out the different Net::Amazon::Request::* and
269 Net::Amazon::Response modules in the distribution if you need to adapt
270 your new module to fulfil any special needs, like a different Amazon
271 URL or a different way to handle the as_string() method. Also, post and
272 problems you might encounter to the mailing list, we're gonna help you
273 out.
274 If possible, provide a test case for your extension. When finished,
276 send a patch to the mailing list at
277 net-amazon-devel@lists.sourceforge.net
279 and if it works, I'll accept it and will work it into the main
281 distribution. Your name will show up in the contributor's list below
282 (unless you tell me otherwise).
283 SAMPLE SCRIPTS
285 There's a number of useful scripts in the distribution's eg/ directory.
286 Take "power" for example, written by Martin Streicher
287 <martin.streicher@apress.com>: I lets you perform a power search using
288 Amazon's query language. To search for all books written by Randal
289 Schwartz about Perl, call this from the command line:
290 power 'author: schwartz subject: perl'
292 Note that you need to quote the query string to pass it as one argument
294 to "power". If a power search returns more results than you want to
295 process at a time, just limit the number of pages, telling "power"
296 which page to start at ("-s") and which one to finish with ("-f").
297 Here's a search for all books on the subject "computer", limited to the
298 first 10 pages:
299 power -s 1 -f 10 'subject: computer'
301 Check out the script "power" in eg/ for more options.
303 HOW TO SEND ME PATCHES
305 If you want me to include your modification or enhancement in the
306 distribution of Net::Amazon, please do the following:
307 · Work off the latest CVS version. Here's the steps to get it:
309 CVSROOT=:pserver:anonymous@cvs.net-amazon.sourceforge.net:/cvsroot/net-amazon
311 export CVSROOT
312 cvs login (just hit Enter)
313 cvs co Net-Amazon
314 This will create a new "Net-Amazon" directory with the latest
316 development version of "Net::Amazon" on your local machine.
317 · Apply your changes to this development tree.
319 · Run a diff between the tree and your changes it in this way:
321 cd Net-Amazon
323 cvs diff -Nau >patch_to_christopher.txt
324 · Email me "patch_to_christopher.txt". If your patch works (and
326 you've included test cases and documentation), I'll apply it on the
327 spot.
328
330 "Net::Amazon" depends on Log::Log4perl, which can be pulled from CPAN
331 by simply saying
332 perl -MCPAN -eshell 'install Log::Log4perl'
334 Also, it needs LWP::UserAgent and XML::Simple 2.x, which can be
336 obtained in a similar way.
337 Once all dependencies have been resolved, "Net::Amazon" installs with
339 the typical sequence
340 perl Makefile.PL
342 make
343 make test
344 make install
345 Make sure you're connected to the Internet while running "make test"
347 because it will actually contact amazon.com and run a couple of live
348 tests.
349 The module's distribution tarball and documentation are available at
351 http://perlmeister.com/devel/#amzn
353 and on CPAN.
355
357 The following modules play well within the "Net::Amazon" framework:
358 "Net::Amazon::RemoteCart"
360 by David Emery <dave@skiddlydee.com> provides a complete API for
361 creating Amazon shopping carts on a local site, managing them and
362 finally submitting them to Amazon for checkout. It is available on
363 CPAN.
364
366 The "Net::Amazon" project's home page is hosted on
367 http://net-amazon.sourceforge.net
369 where you can find documentation, news and the latest development and
371 stable releases for download. If you have questions about how to use
372 "Net::Amazon", want to report a bug or just participate in its
373 development, please send a message to the mailing list
374 net-amazon-devel@lists.sourceforge.net
375 The source code has moved from sourceforge.net to github.com. The git
377 URL is
378 git://github.com/boumenot/p5-Net-Amazon.git
380 The hope is that github.com makes collaboration much easier, and git is
382 a much more modern SCM tool.
383
385 Mike Schilli, <na@perlmeister.com> (Please contact me via the mailing
386 list: net-amazon-devel@lists.sourceforge.net )
387 Maintainers: Christopher Boumenot, <boumenot+na@gmail.com>
389 Contributors (thanks y'all!):
391 Andy Grundman <andy@hybridized.org>
393 Barnaby Claydon <bclaydon@perseus.com>
394 Batara Kesuma <bkesuma@gaijinweb.com>
395 Bill Fitzpatrick
396 Brian <brianbrian@gmail.com>
397 Brian Hirt <bhirt@mobygames.com>
398 Dan Kreft <dan@kreft.net>
399 Dan Sully <daniel@electricrain.com>
400 Dave Cardwell <http://davecardwell.co.uk/>
401 Jackie Hamilton <kira@cgi101.com>
402 Konstantin Gredeskoul <kig@get.topica.com>
403 Lance Cleveland <lancec@proactivewm.com>
404 Martha Greenberg <marthag@mit.edu>
405 Martin Streicher <martin.streicher@apress.com>
406 Mike Evron <evronm@dtcinc.net>
407 Padraic Renaghan <padraic@renaghan.com>
408 rayg <rayg@varchars.com>
409 Robert Graff <rgraff@workingdemo.com>
410 Robert Rothenberg <wlkngowl@i-2000.com>
411 Steve Rushe <steve@deeden.co.uk>
412 Tatsuhiko Miyagawa <miyagawa@livedoor.jp>
413 Tony Bowden <tony@kasei.com>
414 Vince Veselosky
415
417 Copyright 2003, 2004 by Mike Schilli <na@perlmeister.com> Copyright
418 2007-2009 by Christopher Boumenot <boumenot+na@gmail.com>
419 This library is free software; you can redistribute it and/or modify it
421 under the same terms as Perl itself.
422
424 Hey! The above document had some coding errors, which are explained
425 below:
426 Around line 761:
428 You forgot a '=back' before '=head1'
429perl v5.28.1 2013-01-26 Net::Amazon(3)