PUT on MessageQueue

Description

The PUT on MessageQueue action does one of the following:

Sends a message to the specified queue
Sets the visibility timeout for the specified queue (see Visibility Timeout for more information about this setting)

Sending a Message to the Queue

To send a message, you must append "/back" to the queue URL (see the example below). You specify the content of the message in the body of the HTTP request, and the content can be any string that does not exceed 256 KB.

Important

The following list shows the binary characters (in Unicode) allowed in your message, according to http://www.w3.org/TR/REC-xml/#charsets. If you send any binary characters not included in the list, your request will be rejected.

#x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]

Setting the Visibility Timeout for the Queue

To set the visibility timeout, you must include the VisibilityTimeout parameter, but don't append "/back" to the queue URL. If you do, the request succeeds, but the visibility timeout isn't set.

Request Parameters

The following table lists the special request parameters the action uses (in addition to the common request headers listed in Common REST Headers).

Name Description Required

Name	Description	Required
The message text	The message to send, which you provide as the HTTP body (see the example below). Make sure to append "`/back`" to the queue URL when sending a message. Type: String Constraints: Maximum size of 256 KB. See the important note above for a list of allowed characters. Condition: Required when sending a message	Conditional
`VisibilityTimeout`	The duration (in seconds) that messages are hidden from subsequent GET on MessageQueue requests. See Visibility Timeout for more information. Do not append "`/back`" to the URL when setting the visibility timeout. Type: Integer from 0 to 86400 (maximum 24 hours) Condition: Required when setting the visibility timeout	Conditional

The message text

The message to send, which you provide as the HTTP body (see the example below). Make sure to append "/back" to the queue URL when sending a message.

Type: String

Constraints: Maximum size of 256 KB. See the important note above for a list of allowed characters.

Condition: Required when sending a message

Conditional

VisibilityTimeout

The duration (in seconds) that messages are hidden from subsequent GET on MessageQueue requests. See Visibility Timeout for more information. Do not append "/back" to the URL when setting the visibility timeout.

Type: Integer from 0 to 86400 (maximum 24 hours)

Condition: Required when setting the visibility timeout

Conditional

Response Elements

The following table lists the response elements the action returns (in addition to the common response elements listed in The Structure of a Response).

Name Description

Name	Description
`MessageId`	An element containing the message ID of the message sent to the queue. You use this value when performing actions on that message. This element is returned only if you're using the action to send a message to the queue. Type: String Ancestor: `SendMessageResponse`

MessageId

An element containing the message ID of the message sent to the queue. You use this value when performing actions on that message. This element is returned only if you're using the action to send a message to the queue.

Type: String

Ancestor: SendMessageResponse

Special Errors

The following table lists the special errors the action returns (in addition to the common errors listed in Common Errors).

Error	Description	HTTP Status Code
InvalidMessageContents	The message contains characters outside the allowed set.	400

Examples

	Important
	When specifying a queue when using the REST API, make sure to omit `http://queue.amazon.aws.com` from the queue URL and provide only what's left (`/A29E9WXPHGOG29/queue1` in the following examples).

Sending a Message to the Queue

The following example REST request sends a message containing "This is the text of my message." to the queue. Note the presence of "/back" after the queue URL in the first line.

PUT /A29E9WXPHGOG29/queue1/back HTTP/1.1
Host: queue.amazonaws.com
Authorization: [AWS authentication string]
Date: Mon, 21 May 2007 21:12:00 GMT
Content-Type: text/plain
AWS-Version: 2007-05-01

This is the text of my message.

See SendMessage for sample response information.

Setting the Visibility Timeout for the Queue

The following example REST request sets the visibility timeout for the queue to 60 seconds. Note the absence of "/back" after the queue URL.

PUT /A29E9WXPHGOG29/queue1?VisibilityTimeout=60 HTTP/1.1
Host: queue.amazonaws.com
Authorization: [AWS authentication string]
Date: Mon, 21 May 2007 21:12:00 GMT
Content-Type: text/plain
AWS-Version: 2007-05-01

The following example shows the response.

<SetVisibilityTimeoutResponse>
     <ResponseStatus>
      <StatusCode>Success</StatusCode>
      <RequestId>cb919c0a-9bce-4afe-9b48-9bdf2412bb67</RequestId>
    </ResponseStatus>
</SetVisibilityTimeoutResponse>