Receiving a Message

Last updated: 2019-07-05 12:25:07

PDF

1. API Description

This API (ReceiveMessage) is used to consume a message in the queue. The ReceiveMessage operation will change the status of the received message into "inactive". The duration of "inactive" status is determined by the queue attribute visibilityTimeout (Refer to CreateQueue API for details). The consumer needs to delete the message using (batch)DeleteMessage API after the message has been successfully consumed within visibilityTimeout. Otherwise the message will return to "active" status and can be consumed by consumers again.

Domain for public network API request:cmq-queue-region.api.qcloud.com

Domain for private network API request:cmq-queue-region.api.tencentyun.com

At any time (including alpha test), any downstream traffic generated when using public network domain will incur traffic fee. It is strongly recommended that users on Tencent Cloud use private network domain, as it will not incur any traffic fee.

  • The "region" should be replaced by a specific region: gz (Guangzhou), sh (Shanghai), bj (Beijing). The "region" value in the common parameter should be kept consistent with that in the domain. In case of inconsistency, the one in the domain should prevail. The request should be sent to the region specified by the domain.
  • Requests for accessing via public network domain support both HTTP and HTTPS. Requests for accessing via private network only support HTTP.
  • Some of the input parameters are optional, so the default values are not required.
  • All output parameters will be returned to the user when the request is successful; otherwise, at least code, message, and requestId will be returned.

2. Input Parameters

The following request parameter list only provides API request parameters. For other parameters, refer to Common Request Parameters.

Parameter Name Required Type Description
queueName Yes String Queue name. This is unique under the same account in one region. The name of queue is a string with no more than 64 characters. It must start with letter, and the rest may contain letters, numbers and dashes (-).
pollingWaitSeconds No Int Long-polling waiting time for this request. Value range is 0-30 seconds. If not configured, the value of the queue attribute pollingWaitSeconds will be used by default.

3. Output Parameters

Parameter Name Type Description
code Int 0: Succeeded, others: Error. For detailed errors, please refer to the table below.
message String Error message.
requestId String ID of the request generated by server. When there is an internal error on the server, users can submit this ID to backend to locate the problem.
msgBody String Body of the message consumed this time.
msgId String Unique ID of the message consumed this time.
receiptHandle String Unique receipt handle that is returned each time a message is consumed. This is used to delete the message. Only the receipt handle that was generated when consuming the message for the previous time can be used to delete the message.
enqueueTime Int Time to wait for a message to enter the queue after it has been created. A Unix timestamp will be returned (accurate to second).
firstDequeueTime Int The time when the message was consumed for the first time. A Unix timestamp will be returned (accurate to second).
nextVisibleTime Int The time when the message becomes visible again (i.e. can be consume again). A Unix timestamp will be returned (accurate to second).
dequeueCount Int How many times the message has been consumed.
Error Code Module Error Code Error Message Description
7000 10200 no message No message in the queue. Strictly speaking, this is not considered an error. Users can simply ignore it and continue to receive messages.
6070 10690 too many unacked(inactive messages or delayed messages) There are too many invisible or delayed messages in the queue, in which case users are advised to wait for a moment before consuming.

Note: The error codes listed in the above table are specific to the API. If the error code you are looking for is not here, you may find it in the Common Error Codes.

4. Example

Input:

 https://domain/v2/index.php?Action=ReceiveMessage
 &queueName=test-queue-123
 &<Common request parameters>

Output:

{
"code" : 0,
"message" : "",
"requestId":"14534664555",
"msgBody":"helloworld1",
"msgId":"123345346",
"receiptHandle": "283748239349283",
"enqueueTime": 1462351990,
"firstDequeueTime": 1462352990,
"nextVisibleTime": 1462352999,
"dequeueCount": 2
}