Notification Handling Using Amazon SQS

Your application can use the Amazon Simple Queue Service (Amazon SQS) to handle Mechanical Turk notifications. By using Amazon SQS, your notifications are guaranteed to be delivered at least once. For more information about guaranteed delivery of notifications, see Guaranteed Delivery. For more information about, see Amazon SQS.

Creating an SQS Queue

You must create an Amazon SQS queue before using the SQS transport type in notification-related calls. Mechanical Turk does not create an Amazon SQS queue for you. An SQS queue can be created through the Amazon SQS API or by using the AWS Console. For more information, see the Amazon SQS documentation.

Configuring an SQS Queue

Your Amazon SQS queue permissions must be configured to allow a Mechanical Turk system account to call the sqs:SendMessage' action on your queue. Whether you use the management console UI or the API to configure permissions, consider the following:

• You must add a permission that enables the account principal 'arn:aws:iam::755651556756:user/MTurk-SQS' to call SendMessage on your queue.

• Your SendMessage permission must add an action of 'aws:SecureTransport' set to 'true'.

  Mechanical Turk always uses the secure transport; this ensures that you only enable the level of access that will actually be used.

• You must not provide any additional permissions to this account to ensure that you only allow the access that will actually be used.

• You should consider disallowing all other access to your queue from other accounts.

  This makes it easy for you to be sure that available messages were sent by Mechanical Turk.

  If you enable SendMessage for other accounts to this queue, or if you plan to send messages to this queue from your AWS account, you should check the sending identity for every message that you receive from the queue. You can do this by requesting the SenderId attribute in your call to ReceiveMessage. This value will be AIDAIXO4EZE6RHVSXIN4E. Amazon SQS provides this value as a strong guarantee of the authenticated identity of the sender, so if it matches, you can be sure the message came from Mechanical Turk.

  For more information, see the Amazon SQS Developer Guide and Amazon SQS API Reference.

Amazon SQS Policy Document Example

The following example policy document only creates the SendMessage permission for the Mechanical Turk account. You can add additional restrictions, such as setting the aws:SecureTransport value. For more information about policy documents, see the Amazon SQS Developer Guide.

{
 "Version": "2008-10-17",
 "Id": "arn:aws:sqs:us-east-1:<customer_account_id>:<customer_queue_name>/MTurkOnlyPolicy",
 "Statement": [
  {
   "Sid": "MTurkOnlyPolicy",
   "Effect": "Allow",
   "Principal": {
    "AWS": "arn:aws:iam::755651556756:user/MTurk-SQS"
   },
   "Action": "SQS:SendMessage",
   "Resource": "arn:aws:sqs:us-east-1:<customer_account_id>:<customer_queue_name>"
  }
 ]
}

Configuring Permissions Using the AWS Console

To configure permissions in the AWS Console:

1. Sign in to the AWS Management Console and open the Amazon SQS console at https://console.aws.amazon.com/sqs/.

2. Select your queue, and then select Permissions.

3. Click Edit Policy Document.

4. Enter a policy document similar to the example.

Configuring Permissions Using the Amazon SQS API

Call the Amazon SQS SetQueueAttributes action with the Attribute.Name parameter set to Policy. You can call SetQueueAttributes with a policy document similar to the example policy document. Do not use the Amazon SQS AddPermission action for configuring permissions on this queue. If you programmatically create a queue and apply a policy document to it, you must ensure the 'Resource' value in the policy document is updated with the correct queue name.

Testing Your Queue

To test your permissions, call the Mechanical Turk SendTestEventNotification operation with a Transport of 'SQS' and your queue URL as the Destination.

Guaranteed Delivery

Using Amazon SQS provides a guaranteed at-least-once delivery of each message. Mechanical Turk ensures that it calls SendMessage at least once for each message. SQS then provides guarantees regarding message persistence and message delivery.

Rarely, the same message may show up twice in the queue. This is an attribute of Amazon SQS's nature as a distributed system.

If you take action on your queue that prevents Mechanical Turk from publishing to it, we cannot guarantee delivery of the messages that would have been sent to your queue. For instance, such actions may include:

• Modifying the permissions on your queue in a way that prevents our account from calling SendMessage successfully.

• Deleting or disabling your queue.

SQS Message Ordering

You should expect that messages may arrive out of order. For information about message ordering behavior, see the SQS documentation.

Multiple SQS Queues

You may use a different queue for each HITType that you configure with notifications.

Mechanical Turk does not provide the ability to route events within a HITType to different queues. For example, you might prefer to have AssignmentSubmitted events for a HITType delivered to a different queue than HITReviewable events for that same HITType. Mechanical Turk will publish both events to the same queue. You can split the events into different queues by running an SQS client that pulls the messages and republishes them to different queues depending on the event type.

SQS Message Payload

The body of each SQS message is a JSON-encoded structure that provides support for multiple events in each message.

The JSON-encoded structure contains the following:

• EventDocVersion: This is the requested version that is passed in the call to SetHITTypeNotification, such as '2006-05-05'. For a requested version, Mechanical Turk will not change the structure or definition of the output payload structure in a way that is not backward-compatible.

• EventDocId: A unique identifier for the Mechanical Turk. In rare cases, you may receive two different SQS messages for the same event, which can be detected by tracking the EventDocId values you have already seen.

• CustomerId: Your customerId.

• Events: A list of Event structures, described next.

The Event structure contains the following:

• EventType: A value corresponding to the EventType value in the notification specification data structure.

• EventTimestamp: A dateTime in the Coordinated Universal Time time zone, such as 2005-01-31T23:59:59Z.

• HITTypeId: The HIT type ID for the event.

• HITId: The HIT ID for the event.

• AssignmentId: The assignment ID for the event, if applicable.

Double Delivery

Amazon SQS already provides a 'MessageId' value that enables double-delivery detection in the typical SQS case. However, when receiving messages from Mechanical Turk, we recommend that you use the EventDocId value for double-delivery detection. This will cover an additional scenario in which you may see the same EventDocId in two messages with distinct MessageIds.

Most messages are safe to process twice, since they represent independent one-way state changes. Consider whether detection of repeated messages is important for your application. You may be able to simply process the message and ignore it if it appears to have been applied already.