文档首页/ 分布式消息服务Kafka版/ API参考（联盟区域）/ API V2（推荐）/ 消息管理/ 查询消息
更新时间：2025-12-24 GMT+08:00
在线调试
CLI示例
查看PDF
分享

查询消息

功能介绍

Kafka实例支持两种消息查询方式，具体查询范围及结果如下：

  • 按创建时间查询：若已知消息的创建时间段，可通过该方式查询，将返回消息列表及对应偏移量，但不包含消息具体内容。

  • 按偏移量查询：若已知目标消息所属Topic的分区及具体偏移量，可通过该方式查询，将返回消息列表及完整的消息内容。

URI

GET /v2/{project_id}/instances/{instance_id}/messages

表1 路径参数

参数

是否必选

参数类型

描述

project_id

是

String

参数解释：

项目ID，获取方式请参见获取项目ID。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

instance_id

是

String

参数解释：

实例ID。获取方法如下：调用“查询所有实例列表”接口，从响应体中获取实例ID。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。
表2 Query参数

参数

是否必选

参数类型

描述

topic

是

String

参数解释：

Topic名称。

约束限制：

Topic名称必须以字母开头且只支持大小写字母、中横线、下划线以及数字。

取值范围：

不涉及。

默认取值：

不涉及。

asc

否

Boolean

参数解释：

是否按照时间排序。

约束限制：

不涉及。

取值范围：

  • true：按照时间排序。

  • false：不按照时间排序。

默认取值：

不涉及。

start_time

否

String

参数解释：

开始时间。

Unix毫秒时间戳。

约束限制：

按创建时间查询时，为必选参数。

取值范围：

不涉及。

默认取值：

不涉及。

end_time

否

String

参数解释：

结束时间。

Unix毫秒时间戳。

约束限制：

按创建时间查询时，为必选参数。

取值范围：

不涉及。

默认取值：

不涉及。

limit

否

String

参数解释：

每一页显示的消息数量。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

offset

否

String

参数解释：

页数。

约束限制：

不涉及。

取值范围：

不涉及。

默认取值：

不涉及。

download

否

Boolean

参数解释：

是否下载消息到本地。

约束限制：

不涉及。

取值范围：

  • true：下载。

  • false：不下载。

默认取值：

不涉及。

message_offset

否

String

参数解释：

消息偏移量。

约束限制：

按偏移量查询时，为必选参数。

若start_time、end_time参数不为空，该参数无效。

取值范围：

不涉及。

默认取值：

不涉及。

partition

否

String

参数解释：

分区。

约束限制：

按偏移量查询时，为必选参数。

若start_time、end_time参数不为空，该参数无效。

取值范围：

不涉及。

默认取值：

不涉及。

keyword

否

String

参数解释：

设置查询消息的关键词。

约束限制：

不涉及。

取值范围：

0~50字符。

默认取值：

不涉及。

key

否

String

参数解释：

设置消息的KEY，查询结果为包含KEY的所有消息。

约束限制：

由于查询资源和性能限制，最大搜索10000条消息且所有消息总大小不超过200MB，最多返回包含KEY的前10条消息。

取值范围：

不涉及。

默认取值：

不涉及。

include

否

String

参数解释：

设置消息正文中包含的关键词，查询结果为包含此关键词的消息。

约束限制：

多个关键字用%2C隔开，%2C是“,”的URL编码形式。

取值范围：

include与exclude的关键词总数不得超过20个。

默认取值：

不涉及。

exclude

否

String

参数解释：

设置消息正文中需要排除的关键词，查询结果为不包含此关键词的消息。

约束限制：

多个关键字用%2C隔开，%2C是“,”的URL编码形式。

取值范围：

include与exclude的关键词总数不得超过20个。

默认取值：

不涉及。

请求参数

无

响应参数

状态码：200

表3 响应Body参数

参数

参数类型

描述

messages

Array of MessagesEntity objects

参数解释：

消息列表。

total

Long

参数解释：

消息总条数。

取值范围：

不涉及。

size

Long

参数解释：

每页消息条数。

取值范围：

不涉及。
表4 MessagesEntity

参数

参数类型

描述

topic

String

参数解释：

Topic名称。

取值范围：

不涉及。

partition

Integer

参数解释：

消息所在的分区。

取值范围：

不涉及。

key

String

参数解释：

消息key。

取值范围：

不涉及。

value

String

参数解释：

消息内容。

取值范围：

不涉及。

size

Integer

参数解释：

消息大小。

取值范围：

不涉及。

timestamp

Long

参数解释：

生产消息的时间。 格式为Unix时间戳。单位为毫秒。

取值范围：

不涉及。

huge_message

Boolean

参数解释：

大数据标识。

取值范围：

不涉及。

message_offset

Long

参数解释：

消息偏移量。

取值范围：

不涉及。

message_id

String

参数解释：

消息ID。

取值范围：

不涉及。

app_id

String

参数解释：

应用ID。

取值范围：

不涉及。

tag

String

参数解释：

消息标签。

取值范围：

不涉及。

状态码：400

表5 响应Body参数

参数

参数类型

描述

error_code

String

错误码。

error_msg

String

错误描述。

状态码：403

表6 响应Body参数

参数

参数类型

描述

error_code

String

错误码。

error_msg

String

错误描述。

请求示例

  • 查询消息偏移量。

    GET https://{endpoint}/v2/{project_id}/instances/{instance_id}/messages?asc=false&end_time=1608609032042&limit=10&offset=0&start_time=1608608432042&topic=topic-test

  • 查询消息内容。

    GET https://{endpoint}/v2/{project_id}/instances/{instance_id}/messages?download=false&message_offset=0&partition=0&topic=topic-test

响应示例

状态码：200

查询成功。

{
  "messages" : [ {
    "topic" : "topic-test",
    "partition" : 0,
    "value" : "hello world",
    "size" : 21,
    "timestamp" : 1607598463502,
    "huge_message" : false,
    "message_offset" : 4,
    "message_id" : "",
    "app_id" : "",
    "tag" : ""
  } ],
  "total" : 1,
  "size" : 1
}

状态码

状态码

描述

200

查询成功。

400

参数无效。

403

鉴权失败。

错误码

请参见错误码。

父主题： 消息管理