Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
179 lines (119 sloc) 9.5 KB
== Overview of Libraries For Amazon Web Services (ruby-aws)
Libraries for Amazon Web Services (ruby-aws) is a set of libraries and tools designed to make it easier for you to build solutions leveraging Amazon Web Services like Amazon Mechanical Turk. The goals of the libraries are:
* To abstract you from the "muck" of using web services
* To simplify using the various Amazon Mechanical Turk APIs
* To allow you to focus more on solving the business problem and less on managing technical details
Before getting started, you should first review the getting started and developer guides for the Amazon Mechanical Turk web service APIs at http://developer.amazonwebservices.com/connect/entry.jspa?externalID=671&categoryID=28. They provide excellent background information on the various concepts of Amazon Mechanical Turk.
== Table of Contents
1. Features and Benefits
2. Prerequisites
3. Installing the Libraries For Amazon Web Services
4. Using the Amazon Mechanical Turk Developer Sandbox for Testing
5. Running the Hello World Sample Application
6. Running the Simple Survey Sample Application
7. Running the Best Image Sample Application
8. Running the Web Site Categorization Sample Application
9. Running the Reviewer Sample Application
10. Comments, Questions, or Feedback
== Features and Benefits
The Libraries for Amazon Web Services offers you the following features and benefits:
* Access Amazon Mechanical Turk web services through easy-to-use Ruby APIs
* Increase productivity by avoiding web service "muck" like authentication, forming SOAP requests, XML parsing, etc.
* Bulk load HITs via a Question Template File, an Input File, and a HIT Properties File.
* Significantly reduce the amount of coding necessary to manage your HIT design and input data.
* Output submitted results to a file.
* Results can be easily viewed in a text editor and can be parsed for integration to your backend system or into another HIT workflow.
== Prerequisites
To use the Libraries and successfully run the samples, you must meet these prerequisites:
* You must have an Amazon Web Services (AWS) account. You can sign up at the AWS web site: http://aws.amazon.com.
* You must have an Amazon Mechanical Turk Requester account. Be sure to use the same e-mail address and password you used when creating your Amazon Web Services account. You can sign up at the Requester web site: http://requester.mturk.com.
* You must have Ruby 1.8.3 or later. You can download Ruby at the following web site: http://www.ruby-lang.org.
* You must have RubyGems (http://rubyforge.org/projects/rubygems) installed and configured correctly for your Ruby installation. Review the installation instructions at this link: http://docs.rubygems.org.
(Note: If installing RubyGems for the first time, you may need to restart your console to pick up environment changes. To execute code that is dependent on Ruby Gems, the command to execute is: "ruby -rubygems program_that_uses_gems". The "-rubygems" command line parameter should be a default parameter that is always included. To do this, Ruby can utilize the "RUBYOPT" environment label that should be set to "RUBYOPT=-rubygems". Please refer to documentation specific to your OS on defining environment labels.)
== Installing the Libraries for Amazon Web Services
The installation of the Libraries and other required components is simple and requires minimal configuration.
1. Execute the following command:
gem install ruby-aws
(Note: Some Unix-based systems may require root access to install Ruby libraries. You may need to execute the above command as the following:
sudo gem install ruby-aws
and enter in the password to successfully install the Gem)
2. Installation of the ruby-aws gem will prompt to install the following dependent gems if not already installed:
* Hoe (http://seattlerb.rubyforge.org/hoe)
* Highline (http://rubyforge.org/projects/highline)
3. (Optional) Download and expand the corresponding tarball/zip file from the project homepage (http://rubyforge.org/projects/ruby-aws) to an installation
directory. This will provide you access to the source files, test files and sample code.
4. Configure the Libraries to use your Amazon Web Services authentication credentials by executing the following command:
ruby-aws
5. Verify your installation by running the automated tests by executing the following command in the installation path:
rake test
== Using the Amazon Mechanical Turk Developer Sandbox for Testing
By default, the Libraries are configured to work against the Developer Sandbox (http://sandbox.mturk.com). The Developer Sandbox is a simulated environment that allows developers to test their Amazon Mechanical Turk solutions for free.
HITs by default will be created in the Developer Sandbox environment. To view these created HITs, go to the Developer Sandbox worker site (http://workersandbox.mturk.com).
To configure the Libraries to work against the Production site (http://www.mturk.com) pass :Host => :Production to MechanicalTurkRequester.new
Note: When creating HITs on the Production site, you will need to have a funded Amazon Mechanical Turk account. Visit the following link to fund your account: http://requester.mturk.com/mturk/youraccount.
== Running the Hello World Sample Application
With this sample application, you create a HIT that asks a simple question, "What is the weather like right now in Seattle, WA?"
To run this sample, navigate to the following directory:
/samples/helloworld
And run the following command:
ruby MTurkHellWorld.rb
Your HIT has been successfully loaded. You can visit the Developer Sandbox worker site http://workersandbox.mturk.com to view the HIT.
== Running the Simple Survey Sample Application
With this sample application, you create a HIT that conducts a quick survey on a worker's political party preferences.
The following concepts are covered:
* Loading the QuestionForm from a file
* Using a locale qualification
To run this sample, navigate to the following directory:
/samples/simple_survey
And run the following command:
ruby SimpleSurvey.rb
Take note of the HIT ID that is created in this sample. You will need it later when running the sample to retrieve the results.
Your HIT has been successfully loaded. You can visit the Developer Sandbox worker site http://workersandbox.mturk.com to view the HIT.
== Running the Best Image Sample Application
With this sample application, you create a HIT that asks a worker to choose the best image of three given a set of criteria.
The following concepts are covered:
* Using the <FormattedContent> functionality in QuestionForm
* Loading the QuestionForm from a file
* Loading the HIT properties from a file
* Using a basic system qualification
To run this sample, navigate to the following directory:
/samples/best_image
And run the following command:
ruby BestImage.rb
Your HIT has been successfully loaded. You can visit the Developer Sandbox worker site http://workersandbox.mturk.com to view the HIT.
== Running the Web Site Categorization Sample Application
With this sample application, you create HITs asking workers to categorize web sites.
The following concepts are covered:
* Loading HITs in bulk using an input file
* Loading HITs using only files
To run this sample, navigate to the following directory:
/samples/site_category
And run the following command:
ruby SiteCategory.rb
Your HITs have been successfully loaded. You can visit the Developer Sandbox worker site http://workersandbox.mturk.com to view the HIT.
== Running the Reviewer Sample Application
With this sample application, you retrieve and approve the results of your HITs that have been submitted.
The following concepts are covered:
* Retrieving results for a HIT
* Outputting results for several HITs to a file
* Approving assignments
To run this sample and demonstrate retrieving the results of one HIT:
* Take note of the HIT ID that was created by the "Simple Survey" sample application.
* Make sure that the HIT has been completed and results have been submitted.
To run this sample, navigate to the following directory:
/samples/reviewer
And run the following command:
ruby Reviewer.rb --review [HIT ID of Simple Survey HIT created earlier i.e. SYSZH6HTMKFG2ZDECWS0]
Additionally, the Reviewer Sample Application can also retrieve the results of several HITs using the .success file generated when performing a bulk HIT creation operation. To run this sample and demonstrate retrieving the results of a bulk HIT load operation:
* Make sure that all the HITs of the Web Site Categorization sample application have been completed and results have been submitted.
Run the following command:
ruby Reviewer.rb --results --input [full path to hits.success file created in site_category sample] --output output.txt
You have successfully retrieved the results of your HITs that you loaded in bulk.
== Regenerating the Gem package
The distributable contains a Rakefile to allow a Gem to be regenerated.
To regenerate the Gem package, run the following command from the root of the installation directory:
rake gem
== Comments, Questions or Feedback
If you have any comments, questions, or feedback concerning the Libraries for Amazon Web Services, please visit our Rubyforge project page:
http://rubyforge.org/projects/ruby-aws
If you have any comments, questions, or feedback concerning the Mechanical Turk service in general, please visit the Amazon Mechanical Turk discussion forums at: http://developer.amazonwebservices.com/connect/forum.jspa?forumID=11