使用示例

为了帮助用户快速使用云消息服务（CMQ）API，这里给出一个使用示例，能够引导用户使用 API 完整地创建队列、发送消息、消费消息、删除消息并删除队列。

注意：

以下示例中的参数，仅作为参考，实际以系统返回的值为准。为了方便说明，对消息的操作都是以单次操作为例，批量接口（如 批量发送消息、批量删除消息 等）也同样可用。

请参照下面说明将域名中的 {$region} 替换成相应地域：

• 外网接口请求域名：https://cmq-queue-{$region}.api.qcloud.com
• 内网接口请求域名：http://cmq-queue-{$region}.api.tencentyun.com

说明：

{$region} 需用具体地域替换：gz（广州），sh（上海），bj（北京），shjr（上海金融），szjr（深圳金融），hk（中国香港），cd（成都），ca(北美)，usw（美西），sg（新加坡）。公共参数中的 region 值要与域名的 region 值保持一致，如果出现不一致的情况，以域名的 region 值为准，将请求发往域名 region 所指定的地域。

队列模型

以内网为例（外网操作时，需将域名中的 tencentyun 替换成 qcloud)，请求域名的构成规则形如 cmq-queue-{$region}.api.tencentyun.com/v2/index.php ，其中 {$region} 字段需用具体地域替换：gz（广州），sh（上海），bj（北京），shjr（上海金融），szjr（深圳金融），hk（中国香港），cd（成都），ca（北美），usw（美西），sg（新加坡）。公共参数 中的 region 值要与域名的 region 值保持一致，如果出现不一致的情况，以域名的 region 值为准，将请求发往域名 region 所制定的地域。
Signature 参数的生成规则详见 签名方法。

创建队列

创建队列前，请仔细参阅 创建队列接口 说明，结合自身业务，调整队列的属性值。
如果我们在广州地域创建一个队列，并且预期业务消息比生产快一点，需要的具体请求参数见下表：

参数名称	描述	示例取值
queueName	队列名字，在单个地域同一个账号下必须唯一。 队列名称是一个不超过64个字符的字符串，必须以字母为首字符，剩余部分可以包含字母、数字和横划线(-)。	test-queue-1
pollingWaitSeconds	消息接收长轮询等待时间。取值范围0 - 30秒，默认值为0。	30

综上，结合公共请求参数和接口请求参数，最终得到的请求形式如下：

http://cmq-queue-gz.api.tencentyun.com/v2/index.php?
Action=CreateQueue
&Region=gz
&Timestamp=1465750149
&Nonce=46364
&SecretId=AKIDxxxxugEY
&Signature=5umi9gUWpTTyk18V2g%2FYi56hqls%3D
&queueName=test-queue-1
&pollingWaitSeconds=30 

返回结果：

{
"code" : 0,
"message" : "",
"requestId":"14534664555",
"queueId":"queue-ajksdfasdowe"
}

此时我们已创建了一个队列，可以进行管理队列和发送消费消息等操作。

发送消息

发送消息前，请仔细参阅 发送消息接口 说明。
如果我们向上例创建的 test-queue-1 队列中发送消息，需要的具体请求参数见下表：

参数名称	描述	示例取值
queueName	队列名字，在单个地域同一个账号下必须唯一。队列名称是一个不超过64个字符的字符串，必须以字母为首字符，剩余部分可以包含字母、数字和横划线(-)。	test-queue-1
msgBody	消息正文。大小至少1Byte，最大长度受限于设置的队列消息最大长度属性。	This'is test message (url 编码后变成This%27is+test+message)

请求：

http://cmq-queue-gz.api.tencentyun.com/v2/index.php?
Action=SendMessage
&Region=gz
&Timestamp=1465750149
&Nonce=46365
&SecretId=AKIDxxxxugEY
&Signature=5umi9gUWagTTyk18V2g%2FYi56hqls%3D
&queueName=test-queue-1
&msgBody=This%27is+test+message

返回结果：

{
"code" : 0,
"message" : "",
"requestId":"145346456555",
"msgId":"123345346"
}

消费消息

消费消息前，请仔细参阅 消费消息接口 说明。根据业务自身特点，可以选择指定 pollingWaitSeconds 的值。
如果我们从上例创建的 test-queue-1 队列中消费消息，需要的具体请求参数见下表：

参数名称	描述	示例取值
queueName	队列名字，在单个地域同一个账号下必须唯一。队列名称是一个不超过64个字符的字符串，必须以字母为首字符，剩余部分可以包含字母、数字和横划线(-)。	test-queue-1
pollingWaitSeconds	本次请求的长轮询等待时间。取值范围0 - 30秒，默认值为0。	10

请求：

http://cmq-queue-gz.api.tencentyun.com/v2/index.php?
Action=ReceiveMessage
&Region=gz
&Timestamp=1465750150
&Nonce=46368
&SecretId=AKIDxxxxugEY
&Signature=5umi9gUaagTTyk18V2g%2FYi56hqls%3D
&queueName=test-queue-1
&pollingWaitSeconds=10

返回结果：

{
"code" : 0,
"message" : "",
"requestId":"145346635355",
"msgBody":"This is test message",
"msgId":"123345346",
"receiptHandle": "283748239349283",
"enqueueTime": 1462351990,
"firstDequeueTime": 1462352990,
"nextVisibleTime": 1462352999,
"dequeueCount": 1
}

删除消息

一般来说，消息被消费一次就应该删除掉，除非业务有重复消费的需求。删除消息前，请仔细参阅 删除消息接口 说明。
接上例，如果我们消费了 test-queue-1 队列的一条消息，并在消费完之后要将其删除掉，一定要在 nextVisibleTime 的时间之前进行删除操作，否则 receiptHandle 会失效，导致删除失败。需要的具体请求参数见下表：

参数名称	描述	示例取值
queueName	队列名字，在单个地域同一个账号下必须唯一。队列名称是一个不超过 64 个字符的字符串，必须以字母为首字符，剩余部分可以包含字母、数字和横划线(-)。	test-queue-1
receiptHandle	每次消费返回唯一的消息句柄，用于删除消息。当且仅当消息上次被消费时产生的句柄能用于删除本条消息。	"283748239349283" （上例中的 receiptHandle）

请求：

http://cmq-queue-gz.api.tencentyun.com/v2/index.php?
Action=DeleteMessage
&Region=gz
&Timestamp=1465750151
&Nonce=46369
&SecretId=AKIDxxxxugEY
&Signature=5umi9gUaagTasdfk18V2g%2FYi56hqls%3D
&queueName=test-queue-1
&receiptHandle=283748239349283

返回结果：

{
"code" : 0,
"message" : "",
"requestId":"14534454555"
}

删除队列

删除队列前，请仔细参阅 删除队列接口 说明。当队列不再被使用，需要对其进行删除。需要的具体请求参数见下表：

参数名称	描述	取值
queueName	队列名字，在单个地域同一个账号下必须唯一。队列名称是一个不超过64个字符的字符串，首字符必须为字母，剩余部分可以包含字母、数字和横划线(-)。	test-queue-1

请求：

http://cmq-queue-gz.api.tencentyun.com/v2/index.php?
Action=DeleteQueue
&Region=gz
&Timestamp=1465750152
&Nonce=46370
&SecretId=AKIDxxxxugEY
&Signature=5umi9gUaagTasasdl18V2g%2FYi56hqls%3D
&queueName=test-queue-1

返回结果：

{
"code" : 0,
"message" : "",
"requestId":"14534454555"
}