.\" Automatically generated by Pod::Man 2.25 (Pod::Simple 3.16) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .ie \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . nr % 0 . rr F .\} .el \{\ . de IX .. .\} .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Net::Amazon 3pm" .TH Net::Amazon 3pm "2013-03-09" "perl v5.14.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Net::Amazon \- Framework for accessing amazon.com via REST .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Net::Amazon; \& \& my $ua = Net::Amazon\->new( \& associate_tag => \*(AqYOUR_AMZN_ASSOCIATE_TAG\*(Aq, \& token => \*(AqYOUR_AMZN_TOKEN\*(Aq, \& secret_key => \*(AqYOUR_AMZN_SECRET_KEY\*(Aq); \& \& # Get a request object \& my $response = $ua\->search(asin => \*(Aq0201360683\*(Aq); \& \& if($response\->is_success()) { \& print $response\->as_string(), "\en"; \& } else { \& print "Error: ", $response\->message(), "\en"; \& } .Ve .SH "ABSTRACT" .IX Header "ABSTRACT" .Vb 4 \& Net::Amazon provides an object\-oriented interface to amazon.com\*(Aqs \& REST interface. This way it\*(Aqs possible to create applications \& using Amazon\*(Aqs vast amount of data via a functional interface, without \& having to worry about the underlying communication mechanism. .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\f(CW\*(C`Net::Amazon\*(C'\fR works very much like \f(CW\*(C`LWP\*(C'\fR: First you define a useragent like .PP .Vb 6 \& my $ua = Net::Amazon\->new( \& associate_tag => \*(AqYOUR_AMZN_ASSOCIATE_TAG\*(Aq, \& token => \*(AqYOUR_AMZN_TOKEN\*(Aq, \& secret_key => \*(AqYOUR_AMZN_SECRET_KEY\*(Aq, \& max_pages => 3, \& ); .Ve .PP which you pass your personal amazon developer's token (can be obtained from ) and (optionally) the maximum number of result pages the agent is going to request from Amazon in case all results don't fit on a single page (typically holding 20 items). Note that each new page requires a minimum delay of 1 second to comply with Amazon's one-query-per-second policy. .PP According to the different search methods on Amazon, there's a bunch of different request types in \f(CW\*(C`Net::Amazon\*(C'\fR. The user agent's convenience method \f(CW\*(C`search()\*(C'\fR triggers different request objects, depending on which parameters you pass to it: .ie n .IP """$ua\->search(asin => ""0201360683"")""" 4 .el .IP "\f(CW$ua\->search(asin => ``0201360683'')\fR" 4 .IX Item "$ua->search(asin => ""0201360683"")" The \f(CW\*(C`asin\*(C'\fR parameter has Net::Amazon search for an item with the specified \s-1ASIN\s0. If the specified value is an arrayref instead of a single scalar, like in .Sp .Vb 1 \& $ua\->search(asin => ["0201360683", "0596005083"]) .Ve .Sp then a search for multiple ASINs is performed, returning a list of results. .ie n .IP """$ua\->search(actor => ""Adam Sandler"")""" 4 .el .IP "\f(CW$ua\->search(actor => ``Adam Sandler'')\fR" 4 .IX Item "$ua->search(actor => ""Adam Sandler"")" The \f(CW\*(C`actor\*(C'\fR parameter has the user agent search for items created by the specified actor. Can return many results. .ie n .IP """$ua\->search(artist => ""Rolling Stones"")""" 4 .el .IP "\f(CW$ua\->search(artist => ``Rolling Stones'')\fR" 4 .IX Item "$ua->search(artist => ""Rolling Stones"")" The \f(CW\*(C`artist\*(C'\fR parameter has the user agent search for items created by the specified artist. Can return many results. .ie n .IP """$ua\->search(author => ""Robert Jordan"")""" 4 .el .IP "\f(CW$ua\->search(author => ``Robert Jordan'')\fR" 4 .IX Item "$ua->search(author => ""Robert Jordan"")" The \f(CW\*(C`author\*(C'\fR parameter has the user agent search for items created by the specified author. Can return many results. .ie n .IP """$ua\->search(browsenode=>""4025"", mode=>""books"" [, keywords=>""perl""])""" 4 .el .IP "\f(CW$ua\->search(browsenode=>``4025'', mode=>``books'' [, keywords=>``perl''])\fR" 4 .IX Item "$ua->search(browsenode=>""4025"", mode=>""books"" [, keywords=>""perl""])" Returns a list of items by category \s-1ID\s0 (node). For example node \*(L"4025\*(R" is the \s-1CGI\s0 books category. You can add a keywords parameter to filter the results by that keyword. .ie n .IP """$ua\->search(exchange => \*(AqY04Y3424291Y2398445\*(Aq)""" 4 .el .IP "\f(CW$ua\->search(exchange => \*(AqY04Y3424291Y2398445\*(Aq)\fR" 4 .IX Item "$ua->search(exchange => Y04Y3424291Y2398445)" Returns an item offered by a third-party seller. The item is referenced by the so-called \fIexchange \s-1ID\s0\fR. .ie n .IP """$ua\->search(keyword => ""perl xml"", mode => ""books"")""" 4 .el .IP "\f(CW$ua\->search(keyword => ``perl xml'', mode => ``books'')\fR" 4 .IX Item "$ua->search(keyword => ""perl xml"", mode => ""books"")" Search by keyword, mandatory parameters \f(CW\*(C`keyword\*(C'\fR and \f(CW\*(C`mode\*(C'\fR. Can return many results. .SH "DETAILS Net::Amazon is based on Amazon Web Services version 4, and uses WSDL version 2011\-08\-01." .IX Header "DETAILS Net::Amazon is based on Amazon Web Services version 4, and uses WSDL version 2011-08-01." .SH "CACHING" .IX Header "CACHING" Responses returned by Amazon's web service can be cached locally. \&\f(CW\*(C`Net::Amazon\*(C'\fR's \f(CW\*(C`new\*(C'\fR method accepts a reference to a \f(CW\*(C`Cache\*(C'\fR object. \f(CW\*(C`Cache\*(C'\fR (or one of its companions like \f(CW\*(C`Cache::Memory\*(C'\fR, \&\f(CW\*(C`Cache::File\*(C'\fR, etc.) can be downloaded from \s-1CPAN\s0, please check their documentation for details. In fact, any other type of cache implementation will do as well, see the requirements below. .PP Here's an example utilizing a file cache which causes \f(CW\*(C`Net::Amazon\*(C'\fR to cache responses for 30 minutes: .PP .Vb 1 \& use Cache::File; \& \& my $cache = Cache::File\->new( \& cache_root => \*(Aq/tmp/mycache\*(Aq, \& default_expires => \*(Aq30 min\*(Aq, \& ); \& \& my $ua = Net::Amazon\->new( \& token => \*(AqYOUR_AMZN_TOKEN\*(Aq, \& secret_key => \*(AqYOUR_AMZN_SECRET_KEY\*(Aq, \& cache => $cache, \& ); .Ve .PP \&\f(CW\*(C`Net::Amazon\*(C'\fR uses \fIpositive\fR caching only, errors won't be cached. Erroneous requests will be sent to Amazon every time. Positive cache entries are keyed by the full \s-1URL\s0 used internally by requests submitted to Amazon. .PP Caching isn't limited to the \f(CW\*(C`Cache\*(C'\fR class. Any cache object which adheres to the following interface can be used: .PP .Vb 2 \& # Set a cache value \& $cache\->set($key, $value); \& \& # Return a cached value, \*(Aqundef\*(Aq if it doesn\*(Aqt exist \& $cache\->get($key); .Ve .SH "COMPRESSION" .IX Header "COMPRESSION" By default \f(CW\*(C`Net::Amazon\*(C'\fR will attempt to use \s-1HTTP\s0 compression if the Compress::Zlib module is available. Pass \f(CW\*(C`compress => 0\*(C'\fR to \&\f(CW\*(C`\->new()\*(C'\fR to disable this feature. .SH "PROXY SETTINGS" .IX Header "PROXY SETTINGS" \&\f(CW\*(C`Net::Amazon\*(C'\fR uses \f(CW\*(C`LWP::UserAgent\*(C'\fR under the hood to send web requests to Amazon's web site. If you're in an environment where all Web traffic goes through a proxy, there's two ways to configure that. .PP First, \f(CW\*(C`Net::Amazon\*(C'\fR picks up proxy settings from environment variables: .PP .Vb 1 \& export http_proxy=http://proxy.my.place:8080 .Ve .PP in the surrounding shell or setting .PP .Vb 1 \& $ENV{http_proxy} = "http://proxy.my.place:8080"; .Ve .PP in your Perl script will route all requests through the specified proxy. .PP Secondly, you can pass a user agent instance to Net::Amazon's constructor: .PP .Vb 2 \& use Net::Amazon; \& use LWP::UserAgent; \& \& my $ua = LWP::UserAgent\->new(); \& my $na = Net::Amazon\->new( \& ua => $ua, \& associate_tag => \*(AqYOUR_AMZN_ASSOCIATE_TAG\*(Aq, \& token => \*(AqYOUR_AMZN_TOKEN\*(Aq, \& secret_key => \*(AqYOUR_AMZN_SECRET_KEY\*(Aq, \& ); \& # ... .Ve .PP This way, you can configure \f(CW$ua\fR up front before Net::Amazon will use it. .SH "DEBUGGING" .IX Header "DEBUGGING" If something's going wrong and you want more verbosity, just bump up \&\f(CW\*(C`Net::Amazon\*(C'\fR's logging level. \f(CW\*(C`Net::Amazon\*(C'\fR comes with \f(CW\*(C`Log::Log4perl\*(C'\fR statements embedded, which are disabled by default. However, if you initialize \&\f(CW\*(C`Log::Log4perl\*(C'\fR, e.g. like .PP .Vb 2 \& use Net::Amazon; \& use Log::Log4perl qw(:easy); \& \& Log::Log4perl\->easy_init($DEBUG); \& my Net::Amazon\->new(); \& # ... .Ve .PP you'll see what's going on behind the scenes, what URLs the module is requesting from Amazon and so forth. Log::Log4perl allows all kinds of fancy stuff, like writing to a file or enabling verbosity in certain parts only \*(-- check http://log4perl.sourceforge.net for details. .SH "LIVE TESTING" .IX Header "LIVE TESTING" Results returned by Amazon can be incomplete or simply wrong at times, due to their \*(L"best effort\*(R" design of the service. This is why the test suite that comes with this module has been changed to perform its test cases against canned data. If you want to perform the tests against the live Amazon servers instead, just set the environment variable .PP .Vb 1 \& NET_AMAZON_LIVE_TESTS=1 .Ve .SH "WHY ISN'T THERE SUPPORT FOR METHOD XYZ?" .IX Header "WHY ISN'T THERE SUPPORT FOR METHOD XYZ?" Because nobody wrote it yet. If Net::Amazon doesn't yet support a method advertised on Amazon's web service, you could help us out. Net::Amazon has been designed to be expanded over time, usually it only takes a couple of lines to support a new method, the rest is done via inheritance within Net::Amazon. .PP Here's the basic plot: .IP "\(bu" 4 Get Net::Amazon from \s-1CVS\s0. Use .Sp .Vb 3 \& # (Just hit enter when prompted for a password) \& cvs \-d:pserver:anonymous@cvs.net\-amazon.sourceforge.net:/cvsroot/net\-amazon login \& cvs \-z3 \-d:pserver:anonymous@cvs.net\-amazon.sourceforge.net:/cvsroot/net\-amazon co Net\-Amazon .Ve .Sp If this doesn't work, just use the latest distribution from net\-amazon.sourceforge.net. .IP "\(bu" 4 Write a new Net::Amazon::Request::XYZ package, start with this template .Sp .Vb 4 \& ###################################### \& package Net::Amazon::Request::XYZ; \& ###################################### \& use base qw(Net::Amazon::Request); \& \& ###################################### \& sub new { \& ###################################### \& my($class, %options) = @_; \& \& if(!exists $options{XYZ_option}) { \& die "Mandatory parameter \*(AqXYZ_option\*(Aq not defined"; \& } \& \& my $self = $class\->SUPER::new(%options); \& \& bless $self, $class; # reconsecrate \& } .Ve .Sp and add documentation. Then, create a new Net::Amazon::Response::XYZ module: .Sp .Vb 4 \& ############################## \& package Net::Amazon::Response; \& ############################## \& use base qw(Net::Amazon::Response); \& \& use Net::Amazon::Property; \& \& ############################## \& sub new { \& ############################## \& my($class, %options) = @_; \& \& my $self = $class\->SUPER::new(%options); \& \& bless $self, $class; # reconsecrate \& } .Ve .Sp and also add documentation to it. Then, add the line .Sp .Vb 1 \& use Net::Amazon::Request::XYZ; .Ve .Sp to Net/Amazon.pm. .PP And that's it! Again, don't forget the \fIadd documentation\fR part. Modules without documentation are of no use to anybody but yourself. .PP Check out the different Net::Amazon::Request::* and Net::Amazon::Response modules in the distribution if you need to adapt your new module to fulfil any special needs, like a different Amazon \s-1URL\s0 or a different way to handle the \fIas_string()\fR method. Also, post and problems you might encounter to the mailing list, we're gonna help you out. .PP If possible, provide a test case for your extension. When finished, send a patch to the mailing list at .PP .Vb 1 \& net\-amazon\-devel@lists.sourceforge.net .Ve .PP and if it works, I'll accept it and will work it into the main distribution. Your name will show up in the contributor's list below (unless you tell me otherwise). .SS "\s-1SAMPLE\s0 \s-1SCRIPTS\s0" .IX Subsection "SAMPLE SCRIPTS" There's a number of useful scripts in the distribution's eg/ directory. Take \f(CW\*(C`power\*(C'\fR for example, written by Martin Streicher : I lets you perform a \fIpower search\fR using Amazon's query language. To search for all books written by Randal Schwartz about Perl, call this from the command line: .PP .Vb 1 \& power \*(Aqauthor: schwartz subject: perl\*(Aq .Ve .PP Note that you need to quote the query string to pass it as one argument to \f(CW\*(C`power\*(C'\fR. If a power search returns more results than you want to process at a time, just limit the number of pages, telling \f(CW\*(C`power\*(C'\fR which page to start at (\f(CW\*(C`\-s\*(C'\fR) and which one to finish with (\f(CW\*(C`\-f\*(C'\fR). Here's a search for all books on the subject \f(CW\*(C`computer\*(C'\fR, limited to the first 10 pages: .PP .Vb 1 \& power \-s 1 \-f 10 \*(Aqsubject: computer\*(Aq .Ve .PP Check out the script \f(CW\*(C`power\*(C'\fR in eg/ for more options. .SS "\s-1HOW\s0 \s-1TO\s0 \s-1SEND\s0 \s-1ME\s0 \s-1PATCHES\s0" .IX Subsection "HOW TO SEND ME PATCHES" If you want me to include your modification or enhancement in the distribution of Net::Amazon, please do the following: .IP "\(bu" 4 Work off the latest \s-1CVS\s0 version. Here's the steps to get it: .Sp .Vb 4 \& CVSROOT=:pserver:anonymous@cvs.net\-amazon.sourceforge.net:/cvsroot/net\-amazon \& export CVSROOT \& cvs login (just hit Enter) \& cvs co Net\-Amazon .Ve .Sp This will create a new \f(CW\*(C`Net\-Amazon\*(C'\fR directory with the latest development version of \f(CW\*(C`Net::Amazon\*(C'\fR on your local machine. .IP "\(bu" 4 Apply your changes to this development tree. .IP "\(bu" 4 Run a diff between the tree and your changes it in this way: .Sp .Vb 2 \& cd Net\-Amazon \& cvs diff \-Nau >patch_to_christopher.txt .Ve .IP "\(bu" 4 Email me \f(CW\*(C`patch_to_christopher.txt\*(C'\fR. If your patch works (and you've included test cases and documentation), I'll apply it on the spot. .SH "INSTALLATION" .IX Header "INSTALLATION" \&\f(CW\*(C`Net::Amazon\*(C'\fR depends on Log::Log4perl, which can be pulled from \s-1CPAN\s0 by simply saying .PP .Vb 1 \& perl \-MCPAN \-eshell \*(Aqinstall Log::Log4perl\*(Aq .Ve .PP Also, it needs LWP::UserAgent and XML::Simple 2.x, which can be obtained in a similar way. .PP Once all dependencies have been resolved, \f(CW\*(C`Net::Amazon\*(C'\fR installs with the typical sequence .PP .Vb 4 \& perl Makefile.PL \& make \& make test \& make install .Ve .PP Make sure you're connected to the Internet while running \f(CW\*(C`make test\*(C'\fR because it will actually contact amazon.com and run a couple of live tests. .PP The module's distribution tarball and documentation are available at .PP .Vb 1 \& http://perlmeister.com/devel/#amzn .Ve .PP and on \s-1CPAN\s0. .SH "SEE ALSO" .IX Header "SEE ALSO" The following modules play well within the \f(CW\*(C`Net::Amazon\*(C'\fR framework: .ie n .IP """Net::Amazon::RemoteCart""" 4 .el .IP "\f(CWNet::Amazon::RemoteCart\fR" 4 .IX Item "Net::Amazon::RemoteCart" by David Emery provides a complete \s-1API\s0 for creating Amazon shopping carts on a local site, managing them and finally submitting them to Amazon for checkout. It is available on \s-1CPAN\s0. .SH "CONTACT" .IX Header "CONTACT" The \f(CW\*(C`Net::Amazon\*(C'\fR project's home page is hosted on .PP .Vb 1 \& http://net\-amazon.sourceforge.net .Ve .PP where you can find documentation, news and the latest development and stable releases for download. If you have questions about how to use \f(CW\*(C`Net::Amazon\*(C'\fR, want to report a bug or just participate in its development, please send a message to the mailing list net\-amazon\-devel@lists.sourceforge.net .PP The source code has moved from sourceforge.net to github.com. The git \s-1URL\s0 is .PP .Vb 1 \& git://github.com/boumenot/p5\-Net\-Amazon.git .Ve .PP The hope is that github.com makes collaboration much easier, and git is a much more modern \s-1SCM\s0 tool. .SH "AUTHOR" .IX Header "AUTHOR" Mike Schilli, (Please contact me via the mailing list: net\-amazon\-devel@lists.sourceforge.net ) .PP Maintainers: Christopher Boumenot, .PP Contributors (thanks y'all!): .PP .Vb 10 \& Andy Grundman \& Barnaby Claydon \& Batara Kesuma \& Bill Fitzpatrick \& Brian \& Brian Hirt \& Dan Kreft \& Dan Sully \& Dave Cardwell \& Jackie Hamilton \& Konstantin Gredeskoul \& Lance Cleveland \& Martha Greenberg \& Martin Streicher \& Mike Evron \& Padraic Renaghan \& rayg \& Robert Graff \& Robert Rothenberg \& Steve Rushe \& Tatsuhiko Miyagawa \& Tony Bowden \& Vince Veselosky .Ve .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright 2003, 2004 by Mike Schilli Copyright 2007\-2009 by Christopher Boumenot .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.