papercavalier-ruby-aaws 0.8.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (59) hide show
  1. data/.gitignore +3 -0
  2. data/COPYING +340 -0
  3. data/INSTALL +260 -0
  4. data/NEWS +808 -0
  5. data/README +679 -0
  6. data/README.rdoc +140 -0
  7. data/Rakefile +17 -0
  8. data/VERSION.yml +5 -0
  9. data/example/batch_operation +28 -0
  10. data/example/browse_node_lookup1 +46 -0
  11. data/example/customer_content_lookup1 +27 -0
  12. data/example/customer_content_search1 +21 -0
  13. data/example/example1 +78 -0
  14. data/example/help1 +24 -0
  15. data/example/item_lookup1 +56 -0
  16. data/example/item_lookup2 +56 -0
  17. data/example/item_search1 +30 -0
  18. data/example/item_search2 +37 -0
  19. data/example/item_search3 +23 -0
  20. data/example/list_lookup1 +29 -0
  21. data/example/list_search1 +30 -0
  22. data/example/multiple_operation1 +69 -0
  23. data/example/seller_listing_lookup1 +30 -0
  24. data/example/seller_listing_search1 +29 -0
  25. data/example/seller_lookup1 +45 -0
  26. data/example/shopping_cart1 +42 -0
  27. data/example/similarity_lookup1 +48 -0
  28. data/example/tag_lookup1 +34 -0
  29. data/example/transaction_lookup1 +25 -0
  30. data/example/vehicle_search +22 -0
  31. data/lib/amazon.rb +165 -0
  32. data/lib/amazon/aws.rb +1493 -0
  33. data/lib/amazon/aws/cache.rb +141 -0
  34. data/lib/amazon/aws/search.rb +464 -0
  35. data/lib/amazon/aws/shoppingcart.rb +537 -0
  36. data/lib/amazon/locale.rb +102 -0
  37. data/test/setup.rb +56 -0
  38. data/test/tc_amazon.rb +20 -0
  39. data/test/tc_aws.rb +160 -0
  40. data/test/tc_browse_node_lookup.rb +49 -0
  41. data/test/tc_customer_content_lookup.rb +49 -0
  42. data/test/tc_help.rb +44 -0
  43. data/test/tc_item_lookup.rb +47 -0
  44. data/test/tc_item_search.rb +105 -0
  45. data/test/tc_list_lookup.rb +60 -0
  46. data/test/tc_list_search.rb +44 -0
  47. data/test/tc_multiple_operation.rb +375 -0
  48. data/test/tc_operation_request.rb +64 -0
  49. data/test/tc_seller_listing_lookup.rb +47 -0
  50. data/test/tc_seller_listing_search.rb +55 -0
  51. data/test/tc_seller_lookup.rb +44 -0
  52. data/test/tc_serialisation.rb +107 -0
  53. data/test/tc_shopping_cart.rb +214 -0
  54. data/test/tc_similarity_lookup.rb +48 -0
  55. data/test/tc_tag_lookup.rb +24 -0
  56. data/test/tc_transaction_lookup.rb +24 -0
  57. data/test/tc_vehicle_operations.rb +118 -0
  58. data/test/ts_aws.rb +24 -0
  59. metadata +141 -0
@@ -0,0 +1,140 @@
1
+ = Ruby/AWS - A Ruby interface to the Amazon Associates Web Services API.
2
+
3
+ == Introduction
4
+
5
+ Ruby/AWS is a Ruby language library that allows programmatic access to
6
+ the popular Amazon Web sites via the AWS v4 API. It is the successor to the
7
+ now obsolete Ruby/Amazon.
8
+
9
+ In addition to the original
10
+ amazon.com[http://www.amazon.com/exec/obidos/redirect-home/calibanorg-20]
11
+ site, the local sites
12
+ amazon.co.uk[http://www.amazon.co.uk/exec/obidos/redirect-home/caliban-21],
13
+ amazon.de[http://www.amazon.de/exec/obidos/redirect-home/calibanorg0a-21],
14
+ amazon.fr[http://www.amazon.fr/exec/obidos/redirect-home/caliban08-21],
15
+ amazon.ca[http://www.amazon.ca/exec/obidos/redirect-home/caliban-20] and
16
+ amazon.co.jp[http://www.amazon.co.jp/exec/obidos/redirect-home/calibanorg-20]
17
+ are also supported.
18
+
19
+ Although the library is still in development, the AWS v4 API is now more or
20
+ less fully supported, with only tiny gaps in the functionality of some
21
+ operations.
22
+
23
+ The following operations are supported:
24
+
25
+ BrowseNodeLookup
26
+ CustomerContentLookup
27
+ CustomerContentSearch
28
+ Help
29
+ ItemLookup
30
+ ItemSearch
31
+ ListLookup
32
+ ListSearch
33
+ SellerListingLookup
34
+ SellerListingSearch
35
+ SellerLookup
36
+ SimilarityLookup
37
+ TagLookup
38
+ TransactionLookup
39
+ VehiclePartLookup
40
+ VehiclePartSearch
41
+ VehicleSearch
42
+
43
+ Remote shopping-carts are also supported. This adds the following operations:
44
+
45
+ CartCreate
46
+ CartAdd
47
+ CartModify
48
+ CartClear
49
+ CartGet
50
+
51
+ Finally, multiple operations and batch requests are also supported.
52
+
53
+ Ruby/AWS supports request authentication, using your secret key to sign your
54
+ requests to AWS.
55
+
56
+ Beyond wrapping features readily available in the AWS API, Ruby/AWS also
57
+ offers advanced features not directly supported by the AWS API, such as the
58
+ ability to retrieve *all* results pages for a particular search, rather than
59
+ having to manually deal with multiple AWS responses of 10 results per page.
60
+
61
+ You can also retrieve product images and optionally overlay them with
62
+ percentage discount icons.
63
+
64
+ Another advanced feature is the ability to cache responses returned by AWS.
65
+ If the cache is used (as it is by default), the results of each unique
66
+ search will be cached and used for 24 hours. The cache can be manually
67
+ flushed of all or just the expired entries.
68
+
69
+ One other useful advanced feature is the ability to determine the
70
+ appropriate Amazon locale for a given client, based on its IP address or
71
+ host name. This allows you to perform AWS operations using the correct
72
+ geographical Amazon site for any given client. German and Austrian clients
73
+ can be made to interact with amazon.de, British and Irish clients with
74
+ amazon.co.uk, etc.
75
+
76
+
77
+ == Installation
78
+
79
+ Please see the +INSTALL+ file supplied with the software for details of how
80
+ to install Ruby/AWS. You can choose between an installation script and a
81
+ RubyGems[http://www.rubygems.org/] installation.
82
+
83
+ Note, however, if opting for the gem installation, that Ruby/AWS's RubyForge
84
+ UNIX name is now ruby-aaws. The ruby-aws name was taken by {another
85
+ project}[http://rubyforge.org/projects/ruby-aws/] and this namespace clash
86
+ prevented remote installation of the Ruby/AWS gem.
87
+
88
+
89
+ == Prerequisites
90
+
91
+ Before you can use this library, you need to obtain an Amazon Web Services
92
+ {access key
93
+ ID}[https://aws-portal.amazon.com/gp/aws/developer/registration/index.html].
94
+
95
+ You should also apply for an {Associates
96
+ account}[http://docs.amazonwebservices.com/AWSECommerceService/2009-11-01/GSG/BecominganAssociate.html],
97
+ although this isn't strictly necessary. If you do not explicitly provide an
98
+ Associates tag in the operations you conduct via Ruby/AWS, the tag of the
99
+ Ruby/AWS author will be used by default.
100
+
101
+
102
+ == See Also
103
+
104
+ Ultimately, the way to get the most from Ruby/AWS is to read the AWS
105
+ documentation to get a feel for what is possible, and then experiment with
106
+ the library to see how the calls to AWS are mapped to the Ruby world. You
107
+ should also review this library's
108
+ RDoc[http://www.ruby-doc.org/core/classes/RDoc.html]
109
+ documentation[http://caliban.org/ruby/ruby-aws/] as well as the
110
+ plain-text +README+ file that came with the archive.
111
+
112
+ Additionally, there's a
113
+ {mailing-list}[http://caliban.org/mailman/listinfo/ruby-aws] available,
114
+ where you can discuss any Ruby/AWS-related subjects and issues.
115
+
116
+ Please see the AWS Developer Resources {home
117
+ page}[https://affiliate-program.amazon.com/gp/advertising/api/detail/main.html],
118
+ the Amazon Web Services API
119
+ documentation[http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=5],
120
+ and, in particular, the {release
121
+ notes}[http://developer.amazonwebservices.com/connect/kbcategory.jspa?categoryID=17]
122
+ for definitive information on the capabilities and inner workings of the AWS
123
+ API.
124
+
125
+
126
+ == Download
127
+
128
+ Version 0.8.1
129
+ === {gzip'ed tar archive}[http://caliban.org/files/ruby/ruby-aws-0.8.1.tar.gz]
130
+ === {Ruby Gem}[http://caliban.org/files/ruby/ruby-aaws-0.8.1.gem]
131
+ === {Fedora 12 RPM}[http://caliban.org/files/redhat/RPMS/noarch/ruby-aws-0.8.1-1.fc12.noarch.rpm]
132
+ === {Fedora 12 doc RPM}[http://caliban.org/files/redhat/RPMS/noarch/ruby-aws-doc-0.8.1-1.fc12.noarch.rpm]
133
+ === {Fedora 12 source RPM}[http://caliban.org/files/redhat/SRPMS/ruby-aws-0.8.1-1.fc12.src.rpm]
134
+
135
+
136
+ ---
137
+ Author:: Ian Macdonald <mailto:ian@caliban.org>
138
+ Version:: 0.8.1
139
+ Copyright:: (C) 2008-2010 Ian Macdonald
140
+ Licence:: GPL[http://www.gnu.org/copyleft/gpl.html]
@@ -0,0 +1,17 @@
1
+ require 'rubygems'
2
+ require 'rake'
3
+
4
+ begin
5
+ require 'jeweler'
6
+ Jeweler::Tasks.new do |gemspec|
7
+ gemspec.name = 'papercavalier-ruby-aaws'
8
+ gemspec.summary = 'Ruby/AWS is a Ruby wrapper to the Amazon Product Advertising API.'
9
+ gemspec.email = 'code@papercavalier.com'
10
+ gemspec.homepage = 'http://github.com/papercavalier/ruby-aaws'
11
+ gemspec.description = 'Ruby/AWS is a Ruby wrapper to the Amazon Product Advertising API.'
12
+ gemspec.authors = ['Ian Macdonald']
13
+ end
14
+ Jeweler::GemcutterTasks.new
15
+ rescue LoadError
16
+ puts 'Jeweler (or a dependency) not available. Install it with: sudo gem install jeweler'
17
+ end
@@ -0,0 +1,5 @@
1
+ ---
2
+ :patch: 1
3
+ :major: 0
4
+ :minor: 8
5
+ :build:
@@ -0,0 +1,28 @@
1
+ #!/usr/bin/ruby -w
2
+ #
3
+ # $Id: batch_operation,v 1.3 2010/02/20 16:49:11 ianmacd Exp $
4
+
5
+ require 'amazon/aws/search'
6
+
7
+ include Amazon::AWS
8
+ include Amazon::AWS::Search
9
+
10
+ rg = ResponseGroup.new( :Small )
11
+ req = Request.new
12
+ req.locale = 'uk'
13
+ req.cache = false
14
+
15
+ is = ItemSearch.new( 'Books', { 'Title' => 'ruby programming' } )
16
+ is2 = ItemSearch.new( 'Music', { 'Title' => 'stranglers' } )
17
+ #more_is = [ ItemSearch.new( 'Music', { 'Title' => 'stranglers' } ),
18
+ # ItemSearch.new( 'DVD', { 'Director' => 'scorsese' } ) ]
19
+
20
+ more_is = [ ItemSearch.new( 'Music', { 'Artist' => 'stranglers' } ) ]
21
+
22
+ is.batch( more_is )
23
+ is.response_group = rg
24
+
25
+ batched_response = req.search( is )
26
+ itemsearch = batched_response.item_search_response[0].items
27
+
28
+ puts itemsearch
@@ -0,0 +1,46 @@
1
+ #!/usr/bin/ruby -w
2
+ #
3
+ # $Id: browse_node_lookup1,v 1.4 2010/02/20 16:49:11 ianmacd Exp $
4
+
5
+ require 'amazon/aws/search'
6
+
7
+ include Amazon::AWS
8
+ include Amazon::AWS::Search
9
+
10
+ # This is the node for Social Sciences.
11
+ #
12
+ START_NODE = '11232'
13
+
14
+ def follow_node(id)
15
+
16
+ req ||= Request.new
17
+ req.locale = 'us'
18
+
19
+ bnl = BrowseNodeLookup.new( id, {} )
20
+ bnl.response_group ||= ResponseGroup.new( 'BrowseNodeInfo' )
21
+ resp = req.search( bnl )
22
+
23
+ #items = resp.browse_node_sets.browse_nodes
24
+ nodes = resp.browse_node_lookup_response[0].browse_nodes[0].browse_node
25
+
26
+ nodes.each do |bn|
27
+
28
+ if bn.children
29
+ puts '%s (%s) has the following children:' % [ bn.name, id ]
30
+
31
+ bn.children[0].browse_node.each do |child_node|
32
+ puts ' %s' % [ child_node.name ]
33
+ end
34
+ puts
35
+
36
+ bn.children[0].browse_node.each do |child_node|
37
+ follow_node( child_node.browse_node_id )
38
+ end
39
+
40
+ else
41
+ puts '%s (%s) has no children.' % [ bn.name, id ]
42
+ end
43
+ end
44
+ end
45
+
46
+ follow_node( START_NODE )
@@ -0,0 +1,27 @@
1
+ #!/usr/bin/ruby -w
2
+ #
3
+ # $Id: customer_content_lookup1,v 1.4 2010/02/20 16:49:12 ianmacd Exp $
4
+
5
+ require 'amazon/aws/search'
6
+
7
+ include Amazon::AWS
8
+ include Amazon::AWS::Search
9
+
10
+ ccl = CustomerContentLookup.new( 'AJDWXANG1SYZP' )
11
+ ccl.response_group = ResponseGroup.new( 'CustomerReviews' )
12
+
13
+ req = Request.new
14
+ req.locale = 'us'
15
+
16
+ resp = req.search( ccl )
17
+
18
+ review = resp.customer_content_lookup_response.customers.customer.customer_reviews.review[0]
19
+
20
+ printf( "Customer's name is %s.\n", review.reviewer.name )
21
+ printf( "Customer's location is %s.\n", review.reviewer.location )
22
+ printf( "Review date is %s.\n", review.date )
23
+ printf( "Review has received %s votes.\n", review.total_votes )
24
+ printf( "Of these, %d deemed the review helpful.\n", review.helpful_votes )
25
+ printf( "Product reviewed has ASIN '%s'.\n", review.asin )
26
+ printf( "Review summary is: %s.\n", review.summary )
27
+ printf( "Review content is:\n%s.\n", review.content )
@@ -0,0 +1,21 @@
1
+ #!/usr/bin/ruby -w
2
+ #
3
+ # $Id: customer_content_search1,v 1.2 2010/02/20 16:49:12 ianmacd Exp $
4
+
5
+ require 'amazon/aws/search'
6
+
7
+ include Amazon::AWS
8
+ include Amazon::AWS::Search
9
+
10
+ ccs = CustomerContentSearch.new( 'ian@caliban.org' )
11
+ ccs.response_group = ResponseGroup.new( 'CustomerInfo' )
12
+
13
+ req = Request.new
14
+ req.locale = 'us'
15
+
16
+ resp = req.search( ccs )
17
+ cust = resp.customer_content_search_response.customers.customer
18
+
19
+ printf( "Customer's ID is %s.\n", cust.customer_id )
20
+ printf( "Customer's nickname is %s.\n", cust.nickname )
21
+ printf( "Customer's location is %s.\n", cust.location.user_defined_location )
@@ -0,0 +1,78 @@
1
+ #!/usr/bin/ruby -w
2
+ #
3
+ # $Id: example1,v 1.6 2010/02/20 16:49:12 ianmacd Exp $
4
+
5
+ require 'amazon/aws'
6
+ require 'amazon/aws/search'
7
+
8
+ # We don't want to have to fully qualify identifiers.
9
+ #
10
+ include Amazon::AWS
11
+ include Amazon::AWS::Search
12
+
13
+ # If you don't have one of these, don't pass the second argument to
14
+ # Request.new.
15
+ #
16
+ ASSOCIATES_ID = "webservices-20"
17
+
18
+ # Your access key ID.
19
+ #
20
+ KEY_ID = "0Y44V8FAFNM119C6PTR2"
21
+
22
+ request = Request.new( KEY_ID, ASSOCIATES_ID )
23
+
24
+ # Create an item search object.
25
+ #
26
+ is = ItemSearch.new( 'Books', { 'Title' => 'ruby programming' } )
27
+
28
+ # Create a response group object. Examples of response groups are 'Small',
29
+ # 'Medium' and 'Large'. 'Large' returns all data about an item.
30
+ #
31
+ is.response_group = ResponseGroup.new( 'Large' )
32
+
33
+ # Search for the items, passing the result into a block.
34
+ #
35
+ nr_items = 0
36
+ page_nr = 0
37
+ response = request.search( is, :ALL_PAGES ) do |page|
38
+ printf( "Page %d had unique request ID %s.\n",
39
+ page_nr += 1,
40
+ page.item_search_response[0].operation_request[0].request_id )
41
+ printf( "Page %d contained %d result(s).\n",
42
+ page_nr,
43
+ page.item_search_response[0].items[0].item.size )
44
+ end
45
+
46
+ # You don't have to access the items through a block.
47
+ #
48
+ nr_items = 0
49
+ response.each do |page|
50
+ page.item_search_response[0].items.each do |item_set|
51
+ nr_items += item_set.item.size
52
+ end
53
+ end
54
+ printf( "Search returned %d items.\n", nr_items )
55
+
56
+ # The first item in the list.
57
+ #
58
+ items = response[0].item_search_response[0].items[0].item
59
+ product1 = items[0]
60
+ puts "\nProperties available for the first product returned:",
61
+ product1.properties.sort
62
+ puts
63
+
64
+ # There are three ways to retrieve the property of a product:
65
+ #
66
+
67
+ # Instance variable:
68
+ #
69
+ p product1.asin
70
+ p product1.item_attributes[0].title
71
+
72
+ # Feels more like a Hash:
73
+ #
74
+ p product1.item_attributes[0]['list_price'][0]['formatted_price']
75
+
76
+ # A variation on the hash theme:
77
+ #
78
+ p product1.item_attributes[0][:author]
@@ -0,0 +1,24 @@
1
+ #!/usr/bin/ruby -w
2
+ #
3
+ # $Id: help1,v 1.2 2010/02/20 16:49:12 ianmacd Exp $
4
+
5
+ require 'amazon/aws/search'
6
+
7
+ include Amazon::AWS
8
+ include Amazon::AWS::Search
9
+
10
+ h = Help.new( 'ResponseGroup', 'Large' )
11
+ h.response_group = ResponseGroup.new( 'Help' )
12
+
13
+ req = Request.new
14
+ req.locale = 'uk'
15
+
16
+ resp = req.search( h )
17
+ help = resp.help_response[0].information.response_group_information
18
+
19
+ printf( "The response group 'Large' was created on %s\n", help.creation_date )
20
+ puts 'It can be used with the following operations:'
21
+ puts help.valid_operations.operation.join( ', ' )
22
+ puts
23
+ puts "and causes the following elements to be returned:\n\n"
24
+ puts help.elements.element
@@ -0,0 +1,56 @@
1
+ #!/usr/bin/ruby -w
2
+ #
3
+ # $Id: item_lookup1,v 1.7 2010/02/20 16:49:12 ianmacd Exp $
4
+
5
+ require 'amazon/aws'
6
+ require 'amazon/aws/search'
7
+
8
+ include Amazon::AWS
9
+ include Amazon::AWS::Search
10
+
11
+ # Example of a batch operation.
12
+ #
13
+ # The MerchantId restriction is to ensure that we retrieve only items that
14
+ # are for sale by Amazon. This is important when we later want to retrieve the
15
+ # availability status.
16
+ #
17
+ il = ItemLookup.new( 'ASIN', { 'ItemId' => 'B000AE4QEC',
18
+ 'MerchantId' => 'Amazon' } )
19
+ il2 = ItemLookup.new( 'ASIN', { 'ItemId' => 'B000051WBE',
20
+ 'MerchantId' => 'Amazon' } )
21
+ il.batch( il2 )
22
+
23
+ # You can have multiple response groups.
24
+ #
25
+ il.response_group = ResponseGroup.new( 'Medium', 'Offers', 'Reviews' )
26
+
27
+ req = Request.new
28
+ req.locale = 'uk'
29
+
30
+ resp = req.search( il )
31
+ item_sets = resp.item_lookup_response[0].items
32
+
33
+ item_sets.each do |item_set|
34
+ item_set.item.each do |item|
35
+ attribs = item.item_attributes[0]
36
+ puts attribs.label
37
+ if attribs.list_price
38
+ puts attribs.title, attribs.list_price[0].formatted_price
39
+ end
40
+
41
+ # Availability has become a cumbersome thing to retrieve in AWSv4.
42
+ #
43
+ puts 'Availability: %s' %
44
+ [ item.offers[0].offer[0].offer_listing[0].availability ]
45
+ puts 'Average rating: %s' % [ item.customer_reviews[0].average_rating ]
46
+ puts 'Reviewed by %s customers.' %
47
+ [ item.customer_reviews[0].total_reviews ]
48
+
49
+ puts 'Customers said:'
50
+ item.customer_reviews[0].review.each do |review|
51
+ puts ' %s (%s votes)' % [ review.summary, review.total_votes ]
52
+ end
53
+
54
+ puts
55
+ end
56
+ end