| Description: |
Ruby/AWS is the sequel to Ruby/Amazon. See the README file in the archive for more information.
Ruby/AWS is a Ruby language library that allows the programmer to retrieve information from the popular Amazon Web site via Amazon Web Services. In addition to the original amazon.com site, the local sites amazon.co.uk, amazon.de, amazon.fr, amazon.ca and amazon.co.jp are also supported.
This library is the sequel to Ruby/Amazon, which worked with the AWS v3 API.
AWS v4 API is supported almost in its entirety, with just a few gaps in the implementation of a couple of operations.
Currently implemented operations are:
BrowseNodeLookup
CustomerContentLookup
CustomerContentSearch
Help
ItemLookup
ItemSearch
ListLookup
ListSearch
SellerListingLookup
SellerListingSearch
SellerLookup
SimilarityLookup
TagLookup
TransactionLookup
VehiclePartLookup
VehiclePartSearch
VehicleSearch
Multiple operations and batch requests are also supported, but not well tested. Beware of bugs.
Remote shopping-cart functionality is also implemented. This adds the following operations:
CartCreate
CartAdd
CartModify
CartClear
CartGet
Changes in 0.6.0:
1. Requests to AWS can now be signed in order to authenticate them. Amazon plans to make the signing of requests mandatory as of 15th August 2009, so it is recommended to start doing so now.
To have your requests automatically signed by Ruby/AWS, simply add the 'secret_key_id' parameter to your ~/.amazonrc configuration file. Its value should, rather predictably, be your secret access key, which can be retrieved here:
https://aws-portal.amazon.com/gp/aws/developer/account/index.html?ie=UTF8&acy
You needn't be concerned about Amazon's warnings not to show your secret key to anyone else, because it will be used only for signing requests, prior to sending them. The key itself will not be sent over the network to Amazon, even in encrypted form.
In order to incorporate the new functionality, minor changes had to be made to the way the AWS request URLs are encoded. This change means that previous requests cached by earlier versions of Ruby/AWS will not be found in the cache. This is a minor, one-time inconvenience, and it just means that the requests will be performed and cached again.
2. When Amazon's AWS servers check whether the correct signature has been applied to a request, they recalculate the signature based on the data in the request and check for a match with the signature supplied by Ruby/AWS.
This introduces a complicating factor, namely the treatment of non-ASCII characters in the request, such as accented letters. When recalculating the signature, Amazon will use the UTF-8 representation of any such characters. This will cause a signature mismatch if you used a different encoding, such as ISO-8859-1 (a.k.a. Latin-1), when you supplied values for your request parameters.
Ruby/AWS can't (reliably) dynamically determine which character encoding your strings use, so this information can now be supplied via the ~/.amazonrc configuration file, using the 'encoding' parameter. This should be set to whichever encoding you use. If left unset, it defaults to UTF-8. An exception will be raised if you attempt to use an invalid (i.e. unknown) encoding.
Currently, the encoding you use makes no difference unless your requests are being signed, but because signing will soon be mandatory, I recommend you explicitly state which encoding you intend to use.
You may also change the encoding in use at any time by assigning to the @encoding instance variable of your Request object.
3. The robustness of the software has been improved by handling the following additional exceptions while communicating with the AWS servers: Errno::ECONNREFUSED, Errno::ECONNABORTED, Errno::ETIMEDOUT and Timeout::Error. Users have reported that all of these occur from time to time, although only Windows platforms seem to suffer from Errno::ECONNABORTED.
4. The version of the AWS API used is now 2009-03-31, the latest at the time of writing.
Changes in 0.5.1:
1. Catch Errno::EPIPE on server connections (Errno::ECONNRESET was already caught). This can occur when the connection times out due to lack of use. Running Ruby in debug mode will print the error message text when such an exception is caught.
2. The version of the AWS API used is now 2009-02-01, the latest at the time of writing.
3. The sequence numbering of shopping cart items incorrectly started from 2 instead of 1, but didn't cause a problem in practice.
Changes in 0.5.0:
1. The configuration files (/etc/amazonrc and typically ~/.amazonrc) are now locale-specific. Global and locale-specific settings can now be placed in their own sections.
For example:
Old style .amazonrc:
associate = 'caliban-21'
locale = 'uk'
cache = false
key_id = '0Y44V8FAFNM119C6XYZ2'
New style .amazonrc:
[global]
locale = 'uk'
cache = false
key_id = '0Y44V8FAFNM119C6XYZ2'
[uk]
associate = 'calibanorg-21'
[us]
associate = 'calibanorg-20'
The old style of configuration is still supported.
2. ItemLookup.new and SellerListingLookup.new no longer take a third parameter, b_parameters. Instead, the new Operation#batch method can be used to create batch operations.
Operation#batch can batch multiple operations of any class, not just ItemLookup and SellerListingLookup. The only requirement if that all batched operations must be of the same class.
If you want to send multiple operations of different classes as a single request, you must still use the MultipleOperation class.
3. VehiclePartLookup, VehiclePartSearch and VehicleSearch operations (which were added in the 2008-08-19 revision of the AWS API, are now supported. However, VehiclePartLookup is the only one of these that currently supports pagination.
4. The list of allowable search indices for ItemSearch operations has been updated in accordance with the latest AWS documentation.
5. Parameter checking for ItemSearch operations no longer occurs. It was impractical to keep the list of valid parameters concurrent with AWS. Related constants have therefore also been removed.
6. The version of the AWS API used is now 2009-01-06, the latest at the time of writing.
The configuration file now supports a new global parameter for requesting a different version of the API.
For example:
api = '2008-08-19'
7. While testing the ability to request a specific version of the AWS API, I encountered a new kind of AWS error, the internal error, which is reported using a different XML construct to that used for all other error conditions.
I triggered one of these internal errors when I attempted an operation, a VehicleSearch, that did not yet exist in the older version of the API that I requested.
This type of error now throws a generic Amazon::AWS::Error::AWSError exception.
It's reasonable to assume that there are other conditions that would cause an internal AWS error to occur. These, too, will be raised as an exception.
Unfortunately, AWS supplies no information on the cause of such internal errors, so Ruby/AWS is unable to pass on any clues to the user.
Changes in 0.4.4:
It's now possible to have Ruby/AWS use a user configuration file with a name other than .amazonrc. This is achieved by defining $AMAZONRCFILE. If left undefined, the default of .amazonrc is used.
Locations other than $HOME were not being checked for .amazonrc. This bug has now been fixed.
Changes in 0.4.3:
$AMAZONRCDIR is now searched for .amazonrc before $HOME and the other directories. This allows a user-defined location to be used for the user configuration file.
There is a new top-level class of exception for Ruby/AWS, Amazon::AmazonError.
Most non-operational exceptions, such as Amazon::AWS::HTTPError, Amazon::Config::ConfigError, Amazon::AWS::Search::Request::AccessKeyIdError, Amazon::AWS::Search::Request::LocaleError and Amazon::AWS::ShoppingCart::CartError are now immediate subclasses of AmazonError. Previously, they were subclasses of StandardError.
Amazon::AWS::Error::AWSError was previously a class that generated exceptions, but it's now simply a container class derived from AmazonError. All operational exceptions -- the ones whose class is dynamically created when AWS returns an error -- are now subclasses of AWSError. Previously, they were immediate subclasses of StandardError.
This has the advantage of allowing all of the exceptions resulting from operational errors to be caught by rescuing just the container class, AWSError.
Changes in 0.4.2:
The version of the Amazon AWS API requested when performing operations is now 2008-08-19. This is the latest at the time of writing.
The exception class Amazon::Config::ConfigError was mysteriously not defined.
Amazon::Config.new now accepts an optional argument, config_str, which may contain the string equivalent of a config file's contents. When config_str is not nil (nil is the default), this string is read instead of /etc/amazonrc and ~/.amazonrc. This addition is really just to aid unit-testing of the Amazon::Config class, as Amazon::Config.new never needs to be called by user code.
Config file lines may now contain leading whitespace.
The Amazon::AWS::MAX_PAGES constant has gone, replaced by the PAGINATION hash. Only ItemSearch should use ItemPage to page through results up to MAX_PAGES when ALL_PAGES has been requested, but the same approach was attempted for all types of operation.
Each operation has its own pagination parameter and its own maximum number of pages that can be fetched. This is now stored in the Amazon::AWS::PAGINATION hash.
Note that ItemLookup has three possible pagination parameters: OfferPage, VariationPage and ReviewPage. Ruby/AWS uses OfferPage for the purposes of ALL_PAGES.
Operations that do not explicitly provide a pagination parameter (or, at least, those for which there isn't one listed in the AWS Developer's Guide) use ItemPage and pagination up to page 400. This is likely to throw an exception, as such operations almost certainly don't support multiple results pages.
Changes in 0.4.1:
The exception class Amazon::AWS::HTTPError was not defined.
Extra locations besides $HOME are now scanned for .amazonrc (to assist Windows users). The full order is:
%HOME%
%HOMEDRIVE% + %HOMEPATH%
%USERPROFILE%
Changes in 0.4.0:
A new method, Amazon::AWS::ShoppingCart::Cart#cart_get, has been added, to allow the retrieval of an existing shopping-cart from AWS. This is necessary when the original Cart object no longer exists.
The version of the Amazon AWS API requested when performing operations is now 2008-06-26. This is the latest at the time of writing.
Minor bug fixes.
Changes in 0.3.3:
YAML.aws_load has been removed. Its functionality is available directly from Amazon::AWS::AWSObject.yaml_load and it wasn't logical or necessary to duplicate that in the YAML class itself. There was no corresponding Marshal.aws_load method, but if there had been, that, too, would have been removed.
Ruby/AWS is now finally available as a RubyGems package.The current release can be found here::
http://www.caliban.org/files/ruby/ruby-aws-x.x.x.gem
Changes in 0.3.2:
Serialisation, e.g. with Marshal and YAML, has been a problem until now.
This is because subclasses of Amazon::AWS::AWSObject are created as needed when XML responses from AWS are parsed. Whilst there is no problem dumping objects instantiated from such classes, the difficulty arises when later loading and attempting to reinstantiate them in a new process, because the dynamic classes from which they were spawned no longer exist.
The solution to the problem comes in the form of the new methods Amazon::AWS::AWSObject.load and Amazon::AWS::AWSObject.yaml_load. Use these as
alternatives to Marshal.load and YAML.load, respectively.
Changes in 0.3.1:
This release mostly features refinements to the support for remote shopping-carts.
The 'Save For Later' area of remote shopping-carts is now implemented.
Cart#cart_modify now takes an extra parameter, save_for_later. If true, items are moved from the active to the Save For Later area of the cart. If false, they are moved in the opposite direction.
In both cases, the quantity parameter is ignored, because attempting to pass it through to AWS results in an error, even though the AWS documentation claims this can be done to move partial quantities from one area of the cart to the other.
Cart#include? now also returns true if the item being queried is in the Save For Later area of the cart. Previously, only the active area was inspected.
New methods, Cart#active? and Cart#saved_for_later? (alias Cart#saved?), return whether or not an item is present in a particular area of the cart. If the item is present, its CartItemId is returned; otherwise 'false'.
A bug that caused shopping-cart transactions to use the cache if one was requested has been fixed. Shopping-carts should never use the cache under any circumstances.
Request objects can now have their @cache attribute assigned to. A Cache object may be directly assigned to it, or you may assign the value 'true'. If @cache is set to 'true', a Cache object will automatically be assigned to it the next time @cache is referenced. This is most useful when one wishes to switch from using no cache to using one, or vice versa.
Cache#flush_expired invariably threw an exception. This bug has been fixed.
Geolocation of users by host and IP address now raises an Amazon::Locale::GeoError exception if the host or IP address is unresolvable.
There's a new Ruby/AWS mailing-list for discussion of the development and usage of this library:
http://www.caliban.org/mailman/listinfo/ruby-aws
Changes in 0.3.0:
Remote shopping carts are now implemented. See the Amazon::AWS::ShoppingCart module and the Amazon::AWS::ShoppingCart::Cart class.
Basically, this adds Cart.new, Cart#cart_create, Cart#cart_add, Cart#cart_modify and Cart#cart_clear. There's also Cart#each for iterating over the items in a cart.
The version of the Amazon AWS API requested when performing operations is now 2008-04-07. This is the latest at the time of writing.
A new iterator method, AWSObject#each, yields each |property, value| of the AWSObject.
The AWSObject and AWSArray classes have received a few new helper methods that should make AWSObject and single element AWSArray objects behave more akin to strings when they are being compared with strings, matched against regexes, etc.
When searches are performed, greater efforts are now made to determine whether Amazon returned any errors. In particular, batch operations and MultipleOperations may return errors at different locations in the XML tree than normal operations.
A bug that materialised only when using an HTTP proxy has been fixed.
Changes in 0.2.0:
Many more types of operation are now supported. In fact, everything except shopping cart operations is now supported.
Symbols can now be used instead of Strings as parameters when instantiating operation and response group objects.
Image objects can now retrieve their images and optionally overlay them with percentage discount icons.
Compatibility fixes for Ruby 1.9.
Dozens of other fixes and minor improvements.
Changes in 0.1.0:
This version features a completely rewritten XML parser, which dynamically creates classes based on XML returned by AWS. This makes Ruby/AWS highly future-proof.
Multiple operations are now implemented.
Numerous fixes and small improvements have been made.
Large scale code clean-up has been performed.
Much more documentation has been added.
|
|---|