NAME

Net::Amazon::MechanicalTurk - Amazon Mechanical Turk SDK for Perl

VERSION

Version 1.02

CONFIGURATION

Configuring your access keys and web service urls.

MechanicalTurk needs access keys for authentication. If you do not specify all of the relevant attributes, The file mturk.properties is read from your home directory for this information.

Run the command:

    perl -MNet::Amazon::MechanicalTurk::Configurer -e configure

to help you create this file.

SYNOPSIS

Module for MechanicalTurk API.

    use Net::Amazon::MechanicalTurk;

    # Create a new MechTurk client
    my $mturk = Net::Amazon::MechanicalTurk->new();


    # Create a new MechTurk client without using mturk.properties
    my $mturk = Net::Amazon::MechanicalTurk->new(
        serviceUrl     => 'https://mechanicalturk.sandbox.amazonaws.com/?Service=AWSMechanicalTurkRequester',
        serviceVersion => '2007-06-21',
        accessKey      => '1AAAAA1A1AAAAA11AA11',
        secretKey      => '1aAaAAAAAAAA+aAaAaaaaaaAAA/AAAAAA1a1aAaa'
    );


    # Get your balance
    my $balance = $mturk->GetAccountBalance->{AvailableBalance}[0]{Amount}[0];
    print "Your balance is $balance\n";


    # CreateHIT
    my $question = "Tell me something interesting.";

    my $questionXml = <<END_XML;
    <?xml version="1.0" encoding="UTF-8"?>
    <QuestionForm xmlns="http://mechanicalturk.amazonaws.com/AWSMechanicalTurkDataSchemas/2005-10-01/QuestionForm.xsd">
      <Question>
        <QuestionIdentifier>1</QuestionIdentifier>
        <QuestionContent>
          <Text>$question</Text>
        </QuestionContent>
        <AnswerSpecification>
          <FreeTextAnswer/>
        </AnswerSpecification>
      </Question>
    </QuestionForm>
    END_XML

    my $result = $mturk->CreateHIT(
        Title       => 'Answer a question',
        Description => 'Test HIT from Perl',
        Keywords    => 'hello, world',
        Reward => {
            CurrencyCode => 'USD',
            Amount       => 0.01
        },
        RequesterAnnotation         => 'Test Hit',
        AssignmentDurationInSeconds => 60 * 60,
        AutoApprovalDelayInSeconds  => 60 * 60 * 10,
        MaxAssignments              => 1,
        LifetimeInSeconds           => 60 * 60,
        Question                    => $questionXml
    );

    printf "Created HIT:\n";
    printf "HITId:     %s\n", $result->{HITId}[0];
    printf "HITTypeId: %s\n", $result->{HITTypeId}[0];


    # Approve all submitted assignments
    my $hits = $mturk->GetReviewableHITsAll;
    while (my $hit = $hits->next) {
        my $hitId = $hit->{HITId}[0];
        my $assignments = $mturk->GetAssignmentsForHITAll(
            HITId => $hitId,
            AssignmentStatus => 'Submitted'
        );
        while (my $assignment = $assignments->next) {
            my $assignmentId = $assignment->{AssignmentId}[0];
            $mturk->ApproveAssignment( AssignmentId => $assignmentId );
        }
    }

ERROR HANDLING

Most methods indicate an error condition through die or Carp::croak. This is similar to throwing an exception in other languages. To catch an error, use eval:

    eval {
        $mturk->callSomeMethod();
    };
    if ($@) { # catch an error
       warn "The following error occurred: ", $@, "\n";

       # You can access the error code through the last response object.
       print "Error Code: ", $mturk->response->errorCode, "\n";

       # You can also access the last request made.
       print "Error while calling operation, ",
             $mturk->request->{Operation}, "\n";
    }

WEB SERVICE METHODS

All of the operations listed in the MechanicalTurk API may be called on a MechanicalTurk instance. To see a list of those operations and what parameters they take see the following URL:

       http://docs.amazonwebservices.com/AWSMechanicalTurkRequester/2007-06-21/

WEB SERVICE RESULTS

The MechanicalTurk web service returns XML for a request. This module will parse the XML into a generic perl data structure consisting of hashes and arrays. This data structure is then looked through to find a result. A result is the first child element under the root element whose element name is not OperationRequest. The XML returned by the webservice contains information rarely used. (If you ever need this extra information it is available through the response attribute on the MechanicalTurk instance.)

Although the results are normal data structures, they also have methods added to them through the package

Net::Amazon::MechanicalTurk::DataStructure.

This package provides a few methods, however the most useful one during development is toString. The toString method will help you figure out how to access the information you need from the result. Here is an example of the result as returned by GetAccountBalance.

    my $result = $mturk->GetAccountBalance;
    print $result->toString, "\n";
    printf "Available Balance: %s\n", $result->{AvailableBalance}[0]{Amount}[0];

    <<Net::Amazon::MechanicalTurk::DataStructure>>
    [AvailableBalance]
      [0]
        [Amount]
          [0] 10000.00
        [CurrencyCode]
          [0] USD
        [FormattedPrice]
          [0] $10,000.00
    [OnHoldBalance]
      [0]
        [Amount]
          [0] 0.00
        [CurrencyCode]
          [0] USD
        [FormattedPrice]
          [0] $0.00
    [Request]
      [0]
        [IsValid]
          [0] True

    Available Balance: 10000.00

Implementation Note: Hash values always contain arrays, even when the WSDL/XSD specifies that child element of another element only occurs once. This perl module does not use the WSDL or XSD for reading or generating XML and does not know if a child element should occur once or many times. It treats the XML as if the element could always occur more than once. It could have been written to condense a single occurence in an array to 1 scalar item, however this would require API users to test if a value is a SCALAR or an ARRAY.

ITERATING METHODS

Some of the MechanicalTurk operations, such as GetAssignmentsForHIT are limited in the number of results returned. These methods have the parameters PageSize and PageNumber, which can be used to go through an entire list of results.

Instead of writing the code to iterate through all of the results using pages, you can make a call to that method with the word 'All' appended to the method name. An object will be returned, which has a method called next, which will return the next item in the results or undef when there are no more results.

Example using an iterator for the GetAssignmentsForHIT operation:

    my $assignments = $mturk->GetAssignmentsForHITAll(
        HITId => $hitId,
        AssignmentStatus => 'Submitted'
    );
    while (my $assignment = $assignments->next) {
        my $assignmentId = $assignment->{AssignmentId}[0];
        $mturk->ApproveAssignment( AssignmentId => $assignmentId );
    }

EXTENDED METHODS

Methods which provide additional functionaliy on top of Mechanical Turk

Extra methods are available through a dynamic extension mechanism. Modules under Net::Amazon::MechanicalTurk::Command add extra functionality to the MechanicalTurk client.

Explanation:

If you were to call the method listOperations, the module Net::Amazon::MechanicalTurk::Command::ListOperations would be loaded and the method listOperations would be added to the MechanicalTurk client.

See the perldocs for those commands:

Net::Amazon::MechanicalTurk::Command::LoadHITs.

Net::Amazon::MechanicalTurk::Command::UpdateHITs.

Net::Amazon::MechanicalTurk::Command::RetrieveResults.

Net::Amazon::MechanicalTurk::Command::GetAvailableBalance.

Net::Amazon::MechanicalTurk::Command::GetHITTypeURL.

Net::Amazon::MechanicalTurk::Command::AddRetry.

Net::Amazon::MechanicalTurk::Command::DeleteHIT.

Net::Amazon::MechanicalTurk::Command::ParseAssignmentAnswer.

ATTRIBUTE METHODS

accessKey or access_key

Get or set the access key used for authentication.

secretKey or secret_key

Get or set the secret key used for signing web service requests.

serviceUrl or service_url

Get or set the endpoint for the webservice. If this url contains the query parameters, Version and/or Service. Then the values for serviceVersion and serviceName will also be set.

serviceName or service_name

Get or set the service name of the web service.

serviceVersion or service_version

Get or set the version of the web service.

requesterUrl or requester_url

Get or set the URL for the requester website. This is only used for display purposes.

workerUrl or worker_url

Get or set the URL for the worker website. This is only used for display purposes.

response

Get the last response from a web service call. This will be of type Net::Amazon::MechanicalTurk::Response.

request

Get the last request used for a web service call. This will be a hash of all the parameters sent to the transport.

filterChain

Get the filterChain used for intercepting web service calls. This is for advanced use cases and internal use. This attribute will be of type Net::Amazon::MechanicalTurk::FilterChain.

transport

Get or set the transport used for sending web service requests.

The default transport is of type Net::Amazon::MechanicalTurk::Transport::RESTTransport.

Hint: You can get to the underlying LWP::UserAgent through the RESTTransport to set connection timeouts.

$mturk->transport->userAgent->timeout(10);

Constructor

init: Initialize a new MechanicalTurk client

Utility Methods

isProduction: Tests whether or not the current serviceUrl is for production.
isSandbox: Tests whether or not the current serviceUrl is for the MechanicalTurk sandbox environment.

Getters/Setters

serviceUrl: serviceUrl determines which host the client communicates with. Can be given a full Url, or can be set to one of the named urls: * Sanbox * Production
transport: transport is the object that handles actual comunications with the service. Pass in an initialized transport or parameters to be passed to Net::Amazon::MechanicalTurk::Transport->create.

Mechanical Turk API calls

iterator: iterator retrieves a Net::Amazon:MechanicalTurk::PagedResultsIterator for the requested operation and parameters
call: call simply invokes the requested operation with the provided parameters and returns the result

BUGS

Please report any bugs or feature requests through the Amazon Web Services Developer Connection.

<http://developer.amazonwebservices.com/connect/forum.jspa?forumID=11>

SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Net::Amazon::MechanicalTurk

You can also look for information at:

<http://requester.mturk.com/mturk/welcome>
<http://developer.amazonwebservices.com/connect/forum.jspa?forumID=11>

COPYRIGHT & LICENSE

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.