文档中心

日志服务

请输入

消费组管理

ConsumerHeartbeat

调用 ConsumerHeartbeat 接口向日志服务发送消费组中的一个消费者的心跳信息。

使用说明

此接口用于向日志服务服务端上报消费组中的一个消费者的心跳信息，表示该消费者为在线状态。服务端接收到此请求后，会根据此消费组的消费者数量、订阅日志主题的分区数量，为该消费者均衡分配日志分区，并返回指定消费者所负责消费的日志分区（Shards）信息。

每个活跃的消费者都应定期上报心跳信息，上报时间间隔不得超过心跳过期时间（HeartbeatTTL），否则服务端会将其视为下线。

此接口的调用频率限制为 20 次/s，超出频率限制会报错 ExceedQPSLimit。

请求说明

请求方式：POST

请求地址：https://{tls-endpoint}/ConsumerHeartbeat

请求参数

下表仅列出该接口特有的请求参数和部分公共参数。更多信息请见公共参数。

Body

参数	类型	是否必选	示例值	描述
ProjectID	String	是	c7******	消费组所属的日志项目的 ID。
ConsumerGroupName	String	是	my-consumer-group	消费组名称。
ConsumerName	String	是	consumer-0	指定消费组中的新消费者名称。命名规则请参考资源命名规则。

返回参数

下表仅列出本接口特有的返回参数。更多信息请参见返回结构。

参数	类型	示例值	描述
Shards	Array of ConsumeShard	{ "TopicID": "e6********", "ShardID": 1 }	服务端为指定消费者分配的日志分区列表。

ConsumeShard

参数	类型	示例值	描述
ShardID	Integer	0	日志分区 ID。
TopicID	String	c7******	日志主题 ID。

请求示例

POST https://{tls-endpoint}/ConsumerHeartbeat HTTP/1.1​
Content-Type: application/json​
{​
    "ProjectID": "c7************",​
    "ConsumerGroupName": "my-consumer-group",​
    "ConsumerName": "consumer-0"​
}​

返回示例

HTTP/1.1 200 OK​
Content-Type: application/json; charset=utf-8 ​
{​
    "Shards": [​
        {​
            "TopicID": "e6********",​
            "ShardID": 0​
        },​
        {​
            "TopicID": "e6********",​
            "ShardID": 1​
        }​
    ]​
}​

错误码

下表为您列举了该接口与业务逻辑相关的错误码。公共错误码请参见公共错误码文档。

HTTP 状态码	错误码	错误信息	说明
400	InvalidArgument	Invalid argument key %s, value %s, please check argument.	参数不合法。
500	InternalServerError	We encountered an unexpected server error, please try again later.	服务器内部错误。

最近更新时间：2025.10.14 14:20:53

这个页面对您有帮助吗？

有用

无用