tencent cloud

消息队列 MQTT 版

动态与公告
新功能发布记录
产品简介
TDMQ 产品系列介绍与选型
什么是消息队列 MQTT 版
应用场景
技术架构
产品系列
MQTT 协议兼容说明
开源对比
高可用
产品约束与使用配额
基本概念
开服地域
购买指南
计费概述
续费说明
查看消费明细
欠费说明
退费说明
快速入门
入门流程指引
准备工作
公网接入
VPC 网络接入
用户指南
使用流程指引
配置账号权限
新建集群
管理 Topic
连接集群
查询消息
管理客户端
管理集群
查看监控和配置告警
数据集成
集成数据到云函数 SCF
集成数据到 CKafka
集成数据到 RocketMQ
开发指南
MQTT 5 高级特性
数据面 HTTP 接口说明
配置自定义域名
配置 SQL 过滤
配置点对点订阅
MQTT over QUIC
管理客户端订阅
消息增强规则
实践教程
MQTT 客户端开发注意事项
可观测能力
Topic 与通配符订阅
API 参考
History
Introduction
API Category
Making API Requests
Cluster APIs
Topic APIs
Authorization Policy APIs
User APIs
Client APIs
Message Enhancement Rule APIs
Message APIs
Data Types
Error Codes
SDK 参考
接入点格式
Java SDK
C SDK
Javascript/Node.JS/小程序
Go SDK
iOS SDK
JavaScript SDK
Dart SDK
Python SDK
.NET
安全与合规
权限管理
常见问题
相关协议
隐私协议
数据处理和安全协议
消息队列 MQTT 版服务等级协议
联系我们
文档消息队列 MQTT 版开发指南数据面 HTTP 接口说明动态修改客户端 Keep Alive 时间

动态修改客户端 Keep Alive 时间

PDF
聚焦模式
字号
最后更新时间： 2026-01-30 15:23:29

概述

本接口用于动态调整在线 MQTT 客户端的 Keep Alive（心跳保活）时间。调用此接口后，服务端将在不中断客户端连接的情况下，立即生效新的Keep Alive 时间。

使用方法

curl --verbose --request POST -H "Authorization: Basic base64(username:password)" http://mqtt.cloud.tencent.com/keep-alive?client-id=${client-id}&interval=${seconds}

认证方式

目前支持 Basic HTTP Authentication 和基于 X509 证书的“一机一证”两种认证方式，暂未支持基于 JWT 的认证方式。

Basic HTTP Authentication

进行基本认证过程中的参数如下：
请求的HTTP头字段会包含Authorization字段，形式如下： Authorization: Basic <credentials>
<credentials> = username:password 的 Base64 编码。
username 会参与 ACL 授权。

BYOC（基于 X.509 证书认证）

客户端信任的根证书：CA.crt
客户端证书链文件：client.chain.crt
客户端私钥文件：client.pkcs8.key

请求参数

参数名
是否必填
类型
说明
client-id
是
String
客户端 ID
interval
是
Integer
新的 Keep Alive 时间，取值范围为30 ~ 1200（单位：秒）
注意：
在调用本接口时，有以下限制：
不支持修改当前 Keep Alive 为 0 的会话：如果客户端连接时设置的 Keep Alive 为 0，则无法通过此接口修改。
不支持将 Keep Alive 修改为 0：不允许将现有连接的 Keep Alive 时间动态调整为 0。

响应参数

参数名
类型
说明
success
Boolean
请求处理结果。true 表示修改指令下发成功。
keepalive
Integer
修改后的 Keep Alive 时间值（秒）。

请求示例

示例 1

使用 Basic Authentication
curl --request POST \\
  --header "Authorization: Basic c2Vpcm9saTIyMjo5NEZWUmpTejBOR0dXVmFU" \\
  "http://mqtt.cloud.tencent.com/keep-alive?client-id=curl-x&interval=120"

示例 2

使用 BYOC 证书认证
curl --tlsv1.2 \\
  --cacert CA.crt \\
  --cert client.chain.crt \\
  --key client.pkcs8.key \\
  --verbose \\
  --request POST \\
  "https://mqtt.cloud.tencent.com/keep-alive?client-id=curl-x&interval=120"

响应示例

响应成功示例

{
  "success": true,
  "keepalive": 120
}

返回的 Status Code 说明：

1. 支持 HTTP Method：POST。
2. 支持 HTTP/HTTPS。
3. 通过 HTTP Basic Authentication 或 BYOC 实现认证， 参见 Basic Authentication。
4. 认证、授权：用户名和密码必须合法，且该账户必须有 CONNECT 权限。
5. HTTP 响应：
HTTP Status Code（状态码）
描述
200
请求正常。
401
认证失败，用户名或者密码不正确。
403
鉴权失败，缺少 CONNECT 权限。
429
流控，Too Many Requests。



上一篇: 查询客户端在线状态下一篇: 配置自定义域名

帮助和支持

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

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

文档反馈