消息服务的Message如何操作？

描述

本接口用于发送消息到指定的消息队列，普通消息发送到消息队列随即可被消费者消费。但是如果生产者发送一个消息不想马上被消费者消费（典型的使用场景为定期任务），生产者在发送消息时设置DelaySeconds参数就可以达到此目标。发送带DelaySeconds参数值大于0的消息初始状态为Delayed，此时消息不能被消费者消费，只有等DelaySeconds时间后消息变成Active状态后才可消费。

[backcolor=transparent]Tip：
发送消息时指定DelaySeconds参数的优先级高于延时消息队列的DelaySeconds属性，即两个DelaySeconds属性设置的值不同时以发送消息时指定的值为准。

Request


Request的构造主要由以下几个部分组成：

• 
  请求行

  
  POST /$queueName/messages HTTP/1.1

• 
  特有Request Header

  
  无，请参考公共请求头

• 
  Request Body

  
  Request Body为XML格式，其中包含创建Message的属性。

参数名称	说明	参数值
MessageBody	必选，消息正文	UTF-8字符集
DelaySeconds	可选，DelaySeconds指定的秒数延后可被消费，单位为秒	0-604800秒（7天）范围内某个整数值，默认值为0
Priority	可选，指定消息的优先级权值。优先级越高的消息，越容易更早被消费	取值范围1~16（其中1为最高优先级），默认优先级为8

Response


返回消息由返回状态行，HTTP头和消息体三部分组成。

• 
  HTTP Status Code

  
  HTTP/1.1 201 Created

• 
  特有Response Header

  
  无，请参考公共返回头

• 
  Response Body

  
  返回的结果为XML格式，返回Message的MessageId和MessageBodyMD5子元素。

参数名称	说明
MessageId	消息编号，在一个Queue唯一、
MessageBodyMD5	消息正文的MD5值

Special Error

错误代码	错误消息	状态码
QueueNotExist	The queue name you provided is not exist.	404
MalformedXML	The XML you provided was not well-formed.	400
InvalidArgument	The value of Element should between Low and High seconds/bytes.	400

[backcolor=transparent]请求示例：
[backcolor=transparent]


ReceiveMessage



描述

本接口用于消费者消费消息队列的消息，ReceiveMessage操作会将取得的消息状态变成Inactive，Inactive的时间长度由Queue属性VisibilityTimeout指定（详见CreateQueue接口）。 消费者在VisibilityTimeout时间内消费成功后需要调用DeleteMessage接口删除该消息，否则该消息将会被重新置为Active，此消息又可被消费者重新消费。

Request


Request的构造主要由以下几个部分组成：

• 
  请求行

  
  GET /$queueName/messages?waitseconds=10 HTTP/1.1

• 
  特有URI参数

参数名称	说明	选项
waitseconds	本次ReceiveMessage请求最长的Polling等待时间①，单位为秒	可选

[backcolor=transparent]说明:

① 如果ReceiveMessage请求附带waitseconds参数,则在Queue无消息时,此次ReceiveMessage请求进入到Polling等待时长为waitseconds；如果未设置waitseconds，则默认使用所属Queue的PollingWaitSeconds属性(参见CreateQueue接口)。

• 
  特有Request Header

  
  无，请参考公共请求头

• 
  Request Body

  
  无

Response


返回消息由返回状态行，HTTP头和消息体三部分组成。

• 
  HTTP Status Code

  
  HTTP/1.1 200 OK

• 
  特有Response Header

  
  无，请参考公共返回头

• 
  Response Body

  
  返回的结果为XML格式，返回Message消息正文及消息属性。

参数名称	说明
MessageId	消息编号，在一个Queue中唯一
ReceiptHandle	本次获取消息产生的临时句柄，用于删除和修改处于Inactive消息，NextVisibleTime之前有效。
MessageBody	消息正文
MessageBodyMD5	消息正文的MD5值
EnqueueTime	消息发送到队列的时间，从1970年1月1日0点整开始的毫秒数
NextVisibleTime	下次可被再次消费的时间，从1970年1月1日0点整开始的毫秒数
FirstDequeueTime	第一次被消费的时间，从1970年1月1日0点整开始的毫秒数
DequeueCount	总共被消费的次数
Priority	消息的优先级权值

Special Error

错误代码	错误消息	状态码
QueueNotExist	The queue name you provided is not exist.	404
MessageNotExist	Message not exist.	404

[backcolor=transparent]
[backcolor=transparent]请求示例：
[backcolor=transparent]


DeleteMessage



描述


本接口用于删除已经被消费过的消息，消费者需将上次消费后得到的ReceiptHandle 作为参数来定位要删除的消息。本操作只有在NextVisibleTime时刻之前执行才能成功；如果过了NextVisibleTime时刻，消息重新变回Active状态，ReceiptHandle就会失效，删除失败，需重新消费获取新的ReceiptHandle。

Request


Request的构造主要由以下几个部分组成：

• 
  请求行

  
  DELETE/$queueName/messages?receiptHandle=<receiptHandle> HTTP/1.1

• 
  特有URI参数

参数名称	说明	选项
ReceiptHandle	上次消费后返回的消息ReceiptHandle，详见本文ReceiveMessage接口	Required

• 特有Request Header 无，请参考共同Request头
• Request Body 无

Response


返回消息由返回状态行，HTTP头和消息体三部分组成。

• 
  HTTP Status Code

  
  HTTP/1.1 204 NoContent

• 
  特有Response Header

  
  无，请参考公共返回头

• 
  Response Body

  
  无

Special Error

错误代码	错误消息	状态码
QueueNotExist	The queue name you provided is not exist.	404
InvalidArgument	The value of Element should between Low and High seconds/bytes.	400
ReceiptHandleError	The receipt handle you provide is not valid.	400

[backcolor=transparent]
[backcolor=transparent]请求示例：
[backcolor=transparent]


PeekMessage



描述


本接口用于消费者查看消息，PeekMessage与ReceiveMessage不同，PeekMessage并不会改变消息的状态，即被PeekMessage获取消息后消息仍然处于Active状态，仍然可被查看或消费；而后者操作成功后消息进入Inactive，在VisibilityTimeout的时间内不可被查看和消费。

Request


Request的构造主要由以下几个部分组成：

• 
  请求行

  
  GET /$queueName/messages?peekonly=true HTTP/1.1

• 
  URI参数

  
  peekonely=true表示这次请求只是去查看队列顶部的消息并不会引起消息的状态改变

• 
  特有Request Header

  
  无，请参考共同Request头

• 
  Request Body

  
  无

Response


返回消息由返回状态行，HTTP头和消息体三部分组成。

• 
  HTTP Status Code

  
  HTTP/1.1 200 OK

• 
  特有Response Header

  
  无，请参考公共返回头

• 
  Response Body

  
  返回的结果为XML格式，返回Message消息正文及消息属性。

参数名称	说明
MessageId	消息编号，在一个Queue唯一
MessageBody	消息正文
MessageBodyMD5	消息正文的MD5值
EnqueueTime	消息发送到队列的时间，从1970年1月1日0点整开始的毫秒数
FirstDequeueTime	第一次被消费的时间，从1970年1月1日0点整开始的毫秒数，如果DequeueCount为0，则与消息的EnqueueTime相同
DequeueCount	总共被消费的次数
Priority	消息的优先级权值

Special Error

错误代码	错误消息	状态码
QueueNotExist	The queue name you provided is not exist.	404
MessageNotExist	Message not exist.	404

[backcolor=transparent]
[backcolor=transparent]请求示例：
[backcolor=transparent]


ChangeMessageVisibility



描述


本接口用于修改被消费过并且还处于的Inactive的消息到下次可被消费的时间，成功修改消息的VisibilityTimeout后，返回新的ReceiptHandle。

Request


Request的构造主要由以下几个部分组成：

• 
  请求行

  
  PUT /$queueName/messages?receiptHandle=<receiptHandle>&visibilityTimeout=<visibilitytimeout> HTTP/1.1

• 
  URI参数

参数名称	说明	选项
ReceiptHandle	上次消费后返回的消息ReceiptHandle，详见ReceiveMessage接口	Required
VisibilityTimeout	从现在到下次可被用来消费的时间间隔，单位为秒	Required

• 
  特有Request Header

  
  无，请参考共同Request头

• 
  Request Body

  
  无

Response


返回消息由返回状态行，HTTP头和消息体三部分组成。

• 
  HTTP Status Code

  
  HTTP/1.1 200 OK

• 
  特有Response Header

  
  无，请参考公共返回头

• 
  Response Body

参数名称	说明
ReceiptHandle	本次修改消息VisibilityTimeout时间返回的临时句柄，用于删除和修改处于Inactive消息，在NextVisibleTime时刻之前有效。
NextVisibleTime	下次可被再次消费的时间，从1970年1月1日0点整开始的毫秒数。

Special Error

错误代码	错误消息	状态码
QueueNotExist	The queue name you provided is not exist.	404
InvalidArgument	The value of Element should between Low and High seconds/bytes.	400
MessageNotExist	Message not exist.	404

[backcolor=transparent]
[backcolor=transparent]请求示例：
[backcolor=transparent]