README

提供用于与亚马逊机械工人API通信的Laravel 5包。

资源

机械工人生产网站

机械工人网站：https://www.mturk.com/mturk/welcome
请求者网站：https://requester.mturk.com/

机械工人沙盒网站

请求者沙盒：https://requestersandbox.mturk.com/
工人沙盒：https://workersandbox.mturk.com/mturk/welcome

亚马逊机械工人文档

请求者文档：http://docs.aws.amazon.com/AWSMechanicalTurk/latest/AWSMechanicalTurkRequester/Welcome.html
API文档：http://docs.aws.amazon.com/AWSMechTurk/latest/AWSMturkAPI/Welcome.html

安装

通过将laraturk添加到您的composer.json文件中安装

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

或使用composer命令

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

安装后，将提供者添加到config/app.php providers中

For Laravel 5.0:

	'Pauly4it\LaraTurk\LaraTurkServiceProvider',

For Laravel 5.1+:

	'Pauly4it\LaraTurk\LaraTurkServiceProvider::class',

并将外观添加到config/app.php aliases中

For Laravel 5.0:

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

For Laravel 5.1+:

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

配置LaraTurk

首先发布配置文件

php artisan vendor:publish

这将创建一个laraturk.php配置文件。在那里您可以定义所有函数中使用的参数的默认值。

如果您只创建一种HIT，您应该在配置文件中指定所有默认值。

您还需要设置两个环境变量，laraturk.php配置文件使用这两个变量：AWS_ROOT_ACCESS_KEY_ID 和 AWS_ROOT_SECRET_ACCESS_KEY。如果没有设置这些变量，并且您尝试使用LaraTurk，LaraTurk将抛出LaraTurkException。

使用方法

对于所有函数（除了getAccountBalance），您将传递一个参数数组给函数。如果您在配置文件中设置了默认值，那么您传递的参数将覆盖默认值（对于您分配的键）。对于大多数已实现的功能，请参考AWS文档以获取所需和可选参数及其格式。一些参数在LaraTurk中与官方文档相比需要不同的格式。请参阅下面的“特殊参数格式”部分。

您必须使用您的AWS根账户电子邮件在机械工人请求者网站上注册。如果您计划使用机械工人沙盒（强烈推荐），您还必须使用您的AWS根账户电子邮件创建一个单独的沙盒请求者账户。

响应

所有对亚马逊机械工人的API调用都返回一个XML响应。LaraTurk将XML转换为数组。因此，对于所有LaraTurk调用，返回的对象都将是一个数组。

例如，机械工人API文档显示了以下XML作为创建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>

LaraTurk返回的数组将如下所示

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

示例

这里有一些使用示例

使用HITLayoutID和HITTypeID创建HIT

这假设请求者网站上已经创建了一个HIT布局，并且已经注册了一个HIT类型。

$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);

$response对象的形式是

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

ForceExpireHIT

API响应只是一个真/假响应，因此如果没有抛出LaraTurkException，则请求成功。

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

$response对象的形式是

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

特殊参数格式

奖励

设置Reward参数如下

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

布局参数

设置HITLayoutParameter参数如下

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

这些对应于您在HIT布局模板中定义的参数。

资格要求

设置 QualificationRequirement 参数如下

$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'
    ]
];

这个资格要求工人必须位于美国或加拿大，完成至少1000个HIT，并且至少有98%的任务批准率，才能接受您的HIT。

通知

设置 Notification 参数如下

$params['Notification'] = [
	[
		'Destination' => 'example@example.com',
		'Transport' => 'Email',
		'Version' => '2006-05-05',
		'EventType' => [
			'HITReviewable',
			'HITExpired'
		]
	],
	[
		'Destination' => 'foo@bar.com',
		'Transport' => 'Email',
		'Version' => '2006-05-05',
		'EventType' => [
			'AssignmentAccepted'
		]
	]
];

目前实现的功能及其相关功能

HITs

创建HIT 使用HIT类型ID和HIT布局ID => createHITByTypeIdAndByLayoutId()
创建HIT 使用HIT布局ID => createHITByLayoutId()
更改HIT类型 => changeHITTypeOfHIT()
延长HIT => extendHIT()
强制过期HIT => forceExpireHIT()
禁用HIT => disableHIT()
丢弃HIT => disposeHIT()
将HIT设置为评审状态 => setHITAsReviewing()
获取可评审的HIT => getReviewableHITs()
搜索HIT => searchHITs()
获取HIT => getHIT()
注册HIT类型 => registerHITType()

任务

获取HIT的任务 => getAssignmentsForHIT()
获取任务 => getAssignment()
批准任务 => approveAssignment()
拒绝任务 => rejectAssignment()
批准被拒绝的任务 => approveRejectedAssignment()
发放奖金 => grantBonus()
获取奖金支付 => getBonusPayments()

通知

设置HIT类型通知 => setHITTypeNotification()
发送测试事件通知 => sendTestEventNotification()

工人

屏蔽工人 => blockWorker()
解屏工人 => unblockWorker()
获取被屏蔽的工人 => getBlockedWorkers()
GetRequesterWorkerStatistic => getRequesterWorkerStatistic()
GetFileUploadURL => getFileUploadURL()
NotifyWorkers => notifyWorkers()

请求者账户

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

注意

使用QuestionForm参数创建HIT目前不支持。您必须在Mechanical Turk中创建一个HIT布局（适用于生产和沙盒模式）并获取HITLayoutID。
使用包含AssignmentReviewPolicy和/或HITReviewPolicy的HIT目前还不支持。

异常

如果在传递的参数中找不到必需的参数，或者API调用因任何原因返回错误，LaraTurk将抛出LaraTurkException。这个异常就像Laravel中的基本Exception类一样工作，但还包括一个额外的getErrors()函数，该函数将返回API调用返回的错误数组。

例如，如果API调用返回错误，因为AWS凭证无效，并且你捕获了异常

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

调用$e->getMessage()会返回

AWS credentials rejected.

调用$e->getErrors()会返回

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

仓库

https://github.com/pauly4it/laraturk

问题、问题、错误

如果您需要任何关于此包的帮助或发现错误，请提交问题。

贡献

请随意提交拉取请求！请添加详细描述以帮助我理解您的更改。谢谢！

许可证

LaraTurk包根据MIT许可证授权。

pauly4it / laraturk

维护者

详细信息