pauly4it / laraturk

Provides a Laravel 5 package to communicate with the Amazon Mechanical Turk API. This is no longer actively maintained.

LaraTurk

Provides a Laravel 5 package to communicate with the Amazon Mechanical Turk API.

Resources

Mechanical Turk Production Websites:

• Mechanical Turk Site: https://www.mturk.com/mturk/welcome
• Requestor Site: https://requester.mturk.com/

Mechanical Turk Sandbox Websites:

• Requestor Sandbox: https://requestersandbox.mturk.com/
• Worker Sandbox: https://workersandbox.mturk.com/mturk/welcome

Amazon Mechanical Turk Documentation:

• Requestor Documentation: http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMechanicalTurkRequester/Welcome.html
• API Documentation: http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/Welcome.html

Installation

Install by adding laraturk to your composer.json file:

require : {
    "pauly4it/laraturk": "dev-master"
}

or with a composer command:

composer require "pauly4it/laraturk": "dev-master"

After installation, add the provider to your config/app.php providers:

For Laravel 5.0:

	'Pauly4it\LaraTurk\LaraTurkServiceProvider',

For Laravel 5.1+:

	'Pauly4it\LaraTurk\LaraTurkServiceProvider::class',

and the facade to config/app.php aliases:

For Laravel 5.0:

	'LaraTurk' => 'Pauly4it\LaraTurk\Facades\LaraTurk',

For Laravel 5.1+:

	'LaraTurk' => 'Pauly4it\LaraTurk\Facades\LaraTurk::class',

Configuring LaraTurk

First publish the config file:

php artisan vendor:publish

This will create a laraturk.php config file. There you can define default values of parameters used in all functions.

If you will only be creating one type of HIT, you should specify all the default values in the config file.

You will also need to set two environment variables which the laraturk.php config file uses: AWS_ROOT_ACCESS_KEY_ID and AWS_ROOT_SECRET_ACCESS_KEY. If these are not set and you try to use LaraTurk, LaraTurk will throw a LaraTurkException.

Usage

For all functions (except getAccountBalance), you will pass the function an array of paramaters. If you have defaults set in the config file, then the parameters you pass will override the defaults (for the keys you assign). For most of the implemented functions, refer to AWS documentation for required and optional parameters and the format of those parameters. A few parameters require different formats in LaraTurk compared to official documentation. Please see the "Special Parameter Formats" section below for those.

You must signup on the Mechanical Turk Requester site using your AWS root account email. If you plan on using the Mechanical Turk sandbox (highly recommended), you must also create a separate sandbox Requester account using your AWS root account email.

Responses

All API calls to Amazon Mechanical Turk return an XML response. LaraTurk converts the XML to an array. Thus, for all LaraTurk calls, the returned object will be an array.

For example, the Mechanical Turk API documentation shows the following XML as a response for creating a HIT:

<CreateHITResponse>
  <OperationRequest>
    <RequestId>ece2785b-6292-4b12-a60e-4c34847a7916</RequestId>
  </OperationRequest>
  <HIT>
    <Request>
      <IsValid>True</IsValid>
    </Request>
    <HITId>GBHZVQX3EHXZ2AYDY2T0</HITId>
    <HITTypeId>NYVZTQ1QVKJZXCYZCZVZ</HITTypeId>
  </HIT>
</CreateHITResponse>

The returned array from LaraTurk will then look like so:

[
   "OperationRequest" => [
       "RequestId" => "ece2785b-6292-4b12-a60e-4c34847a7916"
   ],
   "HIT"              => [
       "Request"   => [
           "IsValid" => "True"
       ],
       "HITId"     => "GBHZVQX3EHXZ2AYDY2T0",
       "HITTypeId" => "NYVZTQ1QVKJZXCYZCZVZ"
   ]
]

Examples

Here are a couple examples of usage:

Create HIT with HITLayoutID and HITTypeID

This assumes a HIT Layout has been created on the Requester site and a HIT Type has been registered.

$params = [
	'HITTypeID' => '',
	'HITLayoutId' => '',
	'HITLayoutParameter' => [
		[
		'Name' => 'image_title',
		'Value' => 'Some image'
		],
		[
			'Name' => 'description',
			'Value' => 'None'
		]
	],
	'LifetimeInSeconds' => 300,
	'MaxAssignments' => 3
];

$turk = new LaraTurk;
$response = $turk->forceExpireHIT($params);

The $response object is in the form of:

[
   "OperationRequest" => [
       "RequestId" => "ece2785b-6292-4b12-a60e-4c34847a7916"
   ],
   "HIT"              => [
       "Request"   => [
           "IsValid" => "True"
       ],
       "HITId"     => "GBHZVQX3EHXZ2AYDY2T0",
       "HITTypeId" => "NYVZTQ1QVKJZXCYZCZVZ"
   ]
]

ForceExpireHIT

The API response is only a true/false response, so if a LaraTurkException is not thrown, then the request succeeded.

$turk = new LaraTurk;
$response = $turk->forceExpireHIT(['HITId' => '3AQGTY5GMKYZ11S8P0G0J0DRP0MU70']);

The $response object is in the form of:

[
   "OperationRequest" => [
       "RequestId" => "ece2785b-6292-4b12-a60e-4c34847a7916"
   ],
   "ForceExpireHITResult" => [
       "Request"   => [
           "IsValid" => "True"
       ]
   ]
]

Special Parameter Formats

Reward

Set the Reward parameter like so:

$params['Reward'] = [
	'Amount' => 0.07,
	'CurrencyCode' => 'USD',
	'FormattedPrice' => '$0.07' // optional parameter
];

Layout Parameters

Set the HITLayoutParameter parameter like so:

$params['HITLayoutParameter'] = [
	[
		'Name' => 'image_title',
		'Value' => 'Some image'
	],
	[
		'Name' => 'description',
		'Value' => 'None'
	]
];

These correspond to the parameters you defined in your HIT Layout template.

Qualification Requirements

Set the QualificationRequirement parameter like so:

$params['QualificationRequirement'] = [
	[
        'QualificationTypeId' => '00000000000000000071', // Worker locale qualification
        'Comparator' => 'In',
        'LocaleValue' => [
            [
                'Country' => 'US'
            ],
            [
                'Country' => 'CA'
            ]
        ] // located in the US or Canada
    ],
    [
        'QualificationTypeId' => '00000000000000000040', // Worker approved hits qualification
        'Comparator' => 'GreaterThanOrEqualTo',
        'IntegerValue' => '1000'
    ],
    [
        'QualificationTypeId' => '000000000000000000L0', // Worker approval percentage qualification
        'Comparator' => 'GreaterThanOrEqualTo',
        'IntegerValue' => '98'
    ]
];

This qualification would require the worker to be located in the US or Canada, have completed at least 1000 HITs, and have at least a 98% assignment approval percentage to be able to accept your HIT.

Notifications

Set the Notification parameter like so:

$params['Notification'] = [
	[
		'Destination' => '[email protected]',
		'Transport' => 'Email',
		'Version' => '2006-05-05',
		'EventType' => [
			'HITReviewable',
			'HITExpired'
		]
	],
	[
		'Destination' => '[email protected]',
		'Transport' => 'Email',
		'Version' => '2006-05-05',
		'EventType' => [
			'AssignmentAccepted'
		]
	]
];

Currently implemented features and associated functions

HITs

• CreateHIT with HIT Type ID and HIT Layout ID => createHITByTypeIdAndByLayoutId()
• CreateHIT with HIT Layout ID => createHITByLayoutId()
• ChangeHITTypeOfHIT => changeHITTypeOfHIT()
• ExtendHIT => extendHIT()
• ForceExpireHIT => forceExpireHIT()
• DisableHIT => disableHIT()
• DisposeHIT => disposeHIT()
• SetHITAsReviewing => setHITAsReviewing()
• GetReviewableHITs => getReviewableHITs()
• SearchHITs => searchHITs()
• GetHIT => getHIT()
• RegisterHITType => registerHITType()

Assignments

• GetAssignmentsForHIT => getAssignmentsForHIT()
• GetAssignment => getAssignment()
• ApproveAssignment => approveAssignment()
• RejectAssignment => rejectAssignment()
• ApproveRejectedAssignment => approveRejectedAssignment()
• GrantBonus => grantBonus()
• GetBonusPayments => getBonusPayments()

Notifications

• SetHITTypeNotification => setHITTypeNotification()
• SendTestEventNotification => sendTestEventNotification()

Workers

• BlockWorker => blockWorker()
• UnblockWorker => unblockWorker()
• GetBlockedWorkers => getBlockedWorkers()
• GetRequesterWorkerStatistic => getRequesterWorkerStatistic()
• GetFileUploadURL => getFileUploadURL()
• NotifyWorkers => notifyWorkers()

Requester Account

• GetAccountBalance => getAccountBalance()
• GetRequesterStatistic => getRequesterStatistic()

Notes:

• Creating a HIT using a QuestionForm parameter is not currently supported. You must create a HIT Layout within Mechanical Turk (for both production and sandbox modes) and get the HITLayoutID.
• Creating a HIT with an AssignmentReviewPolicy and/or a HITReviewPolicy is not yet supported.

Exceptions

If a required parameter is not found in the parameters passed or if the API call returns an error for any reason, LaraTurk will throw a LaraTurkException. This exception works just like the base Exception class in Laravel, but also includes an additional getErrors() function that will return the error array returned from the API call.

For example, if the API call returns an error because the AWS credentials were invalid and you catch the exception:

...
catch(LaraTurkException $e)
{
	// your code here
}

Calling $e->getMessage() would return:

AWS credentials rejected.

Calling $e->getErrors() would return:

"Error" => [
   "Code"    => "AWS.NotAuthorized",
   "Message" => "The identity contained in the request is not authorized to use this AWSAccessKeyId (5934433916915 s)"
]

Repository

https://github.com/pauly4it/laraturk

Questions, Problems, Bugs

If you need any help with this package or find a bug, please submit an issue.

Contributing

Feel free to submit a pull request! Please add a detailed description to help me understand your change. Thanks!

License

The LaraTurk package is licensed under the MIT license.

laraturk's Issues

Changes to app/config.php

the config/app.php changes look like

Pauly4it\LaraTurk\Facades\LaraTurk::class

in the latest version of laravel... documentation and tests should reflect that if possible.

Thanks for the clean code!!

-FT

psr-4

Hi there, I am using laravel 7, calling composer updating I got some errors
"
Deprecation Notice: Class Pauly4it\LaraTurk\LaraturkException located in ./vendor/pauly4it/laraturk/src/LaraTurkException.php does not comply with psr-4 autoloading standard. It will not autoload anymore in Composer v2.0. in phar:///usr/local/bin/composer/src/Composer/Autoload/ClassMapGenerator.php:201
Deprecation Notice: Class Pauly4it\LaraTurk\Facades\Laraturk located in ./vendor/pauly4it/laraturk/src/Facades/LaraTurk.php does not comply with psr-4 autoloading standard. It will not autoload anymore in Composer v2.0. in phar:///usr/local/bin/composer/src/Composer/Autoload/ClassMapGenerator.php:201
"

But I fixed them by editing composer.json

"autoload": {
"files": [
"vendor/pauly4it/laraturk/src/LaraTurkException.php",
"vendor/pauly4it/laraturk/src/Facades/LaraTurk.php"
],
"psr-4": {
"App\": "app/",
"vendor\": "vendor"
},
"classmap": [
"database/seeds",
"vendor/pauly4it/laraturk/src",
"database/factories"
]
},

Call to undefined method Pauly4it\LaraTurk\Facades\Laraturk::forceExpireHIT()

I must be doing something really stupid but any idea why I keep getting this error?

Call to undefined method Pauly4it\LaraTurk\Facades\Laraturk::forceExpireHIT()

It's under use LaraTurk;

Your requirements could not be resolved to an installable set of packages.

Your requirements could not be resolved to an installable set of packages.

Problem 1
- Installation request for pauly4it/laraturk dev-master -> satisfiable by pauly4it/laraturk[dev-master].
- pauly4it/laraturk dev-master requires guzzlehttp/guzzle ~5 -> satisfiable by guzzlehttp/guzzle[5.0.0, 5.0.1, 5.0.2, 5.0.3, 5.1.0, 5.2.0, 5.3.0, 5.3.1, 5.3.x-dev] but these conflict with your requirements or minimum-stability.

I need "guzzlehttp/guzzle": "^6.3", for geocoder-laravel so it is installed

Basic end to end example in documentation

Thanks for the clean codebase and project. I am still working through getting this started.

It would be super helpful if you could walk through the basic workflow of creating a HIT with some reasonable items, and the minimal follow through to get data back out of mturk.

I am learning mturk through your code, so that kind of overview would be very helpful and I think would substantially increase adoption.

At least I am using your codebase over several other comparable ones, precisely because you bothered to invest in a solid starting README.

Thanks for that.
-FT

Not an issue, just a thanks

Thanks for writing this. I'll be playing with it over the coming weeks and it's great to have this as a starting point.

Multiple Events in Notifications parameter return error

I am trying to set HITType Notification. Here is a Notification Parameter

$turk = new MechanicalTurk();
$notifParams['HITTypeId'] = $hitTypeId;
$notifParams['Notification'] = [
[
  'Destination' => env('SNS_ARN_DESTINATION'),
  'Transport' => 'SNS',
  'Version' => '2014-08-15',
  'EventType' => [
    'HITReviewable',
    'HITExpired'
    ]
  ]
];


$result = $turk->setHITTypeNotification($notifParams);
return response()->json($result);

I get following LaraTurk Exception:

at MechanicalTurk->determineError(array('OperationRequest' => array('RequestId' => 'f525a016-5c48-4cc9-bf'), 'SetHITTypeNotificationResult' => array('Request' => array('IsValid' => 'False', 'Errors' => array('Error' => array('Code' => 'AWS.InvalidEnumeratedParameter', 'Message' => 'The value "element "Notification" occurs more than once." you specified for enumeration is invalid. (152182346 s)', 'Data' => array(array('Key' => 'Parameter', 'Value' => 'enumeration'), array('Key' => 'Value', 'Value' => 'element "Notification" occurs more than once.'))))))), 'SetHITTypeNotificationResult')
in MechanicalTurk.php (line 1207)