使用示例

最近更新时间:2023-08-11 10:04:47

为了帮助用户快速使用云消息服务(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"
}