动态与公告

产品动态

公告

产品简介

产品概述

产品功能

产品优势

应用场景

使用限制

基本概念

购买指南

计费概述

购买方式

价格总览

欠费说明

退费说明

快速入门

队列模型快速入门

主题模型快速入门

操作指南

队列服务

主题订阅

访问管理 CAM

标签管理

配置告警

消息查询与轨迹

实践教程

消息去重

选择 Push 还是 Pull

案例分享

在线图片处理案例

起点文学网案例

开发指南

HTTP Endpoint 订阅

通用参考

API 文档

API 列表

CMQ API2.0 切换至 TDMQ CMQ 版 API3.0指引

SDK 文档

HTTP 数据流 SDK

HTTP 控制流 SDK

SDK 参数配置说明

常见问题

功能类

操作类

服务等级协议

联系我们

词汇表

批量删除消息

PDF

聚焦模式

字号

最后更新时间： 2026-02-03 15:48:27

接口描述
本接口（BatchDeleteMessage）用于批量（目前一次最多删除16条）删除已经被消费过的消息，消费者需将上次消费后得到的 ReceiptHandle 作为参数来定位要删除的消息。
本操作只有在 NextVisibleTime 之前执行才能成功；如果过了 NextVisibleTime，消息重新变回 Active 状态，ReceiptHandle 就会失效，删除失败，需重新消费获取新的 ReceiptHandle。并发消费时，如果消息被其中一个消费者删除了，其他的消费者再也无法获取得到被删除的消息。
公网/内网接口请求域名，在 TDMQ CMQ 版控制台 的队列服务 > API 请求地址处复制。CMQ 的 API 调用地址示例如下：
公网地址：https://cmq-gz.publicXXX.tencenttdmq.com
内网地址：http://gz.mqadapter.cmq.tencentyun.com
注意：
不同地域的 API 调用地址 URL 会有所变化。
任何时候（包括内测期间），如果使用外网域名产生公网下行流量，都会收取流量费用。 所以强烈建议服务在腾讯云上的用户使用内网域名，内网不会产生流量费用。
输入参数
以下请求参数列表仅列出了接口请求参数，其它参数请参见 公共请求参数 页面。
参数名称
是否必选
类型
描述
queueName
是
String
队列名字，在单个地域同一下唯一账号。 队列名称是一个不超过64个字符的字符串，必须以字母为首字符，剩余部分可以包含字母、数字和横划线(-)。
receiptHandle.n
是
String
上次消费消息时返回的消息句柄。为方便用户使用，n 从0开始或者从1开始都可以，但必须连续，例如删除两条消息，可以是（receiptHandle.0,receiptHandle.1），或者（receiptHandle.1, receiptHandle.2）。
输出参数
参数名称
类型
描述
code
Int
0：表示成功，4420：达到最大 QPS 限制，4440：队列不存在，6010：删除消息部分失败，6020：删除消息全部失败，其他返回值的含义可以参考 公共错误码。
message
String
错误提示信息。
requestId
String
服务器生成的请求 ID。出现服务器内部错误时，用户可提交此 ID 给后台定位问题。
errorList
Array
无法成功删除的错误列表。每个元素列出了消息无法成功被删除的错误及原因。
errorList 定义如下：
参数名称
类型
描述
code
Int
0：表示成功，others：错误，详情请参见 公共错误码。
message
String
错误提示信息。
receiptHandle
String
对应删除失败的消息句柄。
错误码
详情请参见 公共错误码。
示例
输入：
 https://domain/v2/index.php?Action=BatchDeleteMessage
 &queueName=test-queue-123
 &receiptHandle.1=3423452345
 &receiptHandle.1=4364564575
 &<<a href="">公共请求参数</a>>

输出（全部成功时）：
{
"code" : 0,
"message" : "",
"requestId":"14534664555"
}
输出（部分失败时）：
{
"code" : 6010,
"message" : "delete message partially failed",
"requestId":"14534664555",
"errorList":
[
{
"code" : 4430,
"message" : "invalid receiptHandle",
"receiptHandle":"4364564575"
}
]
}
﻿

帮助和支持

本页内容是否解决了您的问题？

您也可以联系销售或提交工单以寻求帮助。

填写满意度调查问卷，共创更好文档体验。

文档反馈

tencent cloud

消息队列 CMQ 版

批量删除消息

接口描述

输入参数

输出参数

错误码

示例

帮助和支持

参数名称	是否必选	类型	描述
queueName	是	String	队列名字，在单个地域同一下唯一账号。队列名称是一个不超过64个字符的字符串，必须以字母为首字符，剩余部分可以包含字母、数字和横划线(-)。
receiptHandle.n	是	String	上次消费消息时返回的消息句柄。为方便用户使用，n 从0开始或者从1开始都可以，但必须连续，例如删除两条消息，可以是（receiptHandle.0,receiptHandle.1），或者（receiptHandle.1, receiptHandle.2）。