SDK Admin 接口与云 API 对应关系

最近更新时间:2026-02-27 15:56:36

我的收藏
TDMQ Pulsar 支持通过 SDK Admin 接口和云 API 两种方式进行管理。由于云产品的多租户特性,部分 SDK Admin 原生接口在云端被限制或收敛,建议优先使用对应的云 API 进行操作。

鉴权规则说明

目前 TDMQ Pulsar 沿用社区版的鉴权体系,权限控制分为三个层级:
Tenant(租户)层级:仅 superUser 可创建/删除。
Namespace(命名空间)层级:需 adminRole 或 superUser 权限,才支持创建/删除/修改 Namespace 策略。
Topic(主题)层级:普通生产/消费仅需 Namespace 读写权限;其他较敏感接口,需要角色拥有 Tenant 或 Namespace 的权限才支持调用管理操作。

接口对照表

Tenant 层级

Tenant 绝大多数接口需要 SuperUser 权限,否则调用会出现类似如下报错:
code: 401 reason: This operation requires super-user access
由于租户资源由云平台统一托管,SDK 中的 Tenant(租户)管理接口均不支持调用,请参考下表了解对应关系:
admin 接口名
admin 接口是否支持
说明
云API接口
createTenant
不支持
创建租户
不支持
deleteTenant
不支持
删除租户
不支持

Namespace 层级

Namespace 绝大多数接口需要 superUser 或 adminRole 权限,否则调用会出现类似如下报错:
code: 401 reason: Unauthorized to validateTenantOperation for originalPrincipal [null] and clientAppId [<role>] about operation [LIST_NAMESPACES] on tenant
Namespace(命名空间)是资源隔离的核心单元,部分原生 SDK 接口(如策略配置)需使用云 API 作为替代,具体对照如下:
admin 接口名
admin 接口是否支持
说明
云 API 接口
getTenantNamespaces
不支持
获取当前租户下的所有命名空间
getPolicies
不支持
获取当前命名空间属性
createNamespace
不支持
创建命名空间
deleteNamespace
不支持
删除当前命名空间
setNamespaceMessageTTL
不支持
更新当前命名空间 topic 消息的自动到期时间
getNamespaceMessageTTL
不支持
获取当前命名空间 topic 消息的自动到期时间
setRetention
不支持
更新当前命名空间 topic 消息的保留时间
getRetention
不支持
获取当前命名空间 topic 消息的保留时间

Topic 层级

Topic 部分接口需要 superUser 或 adminRole 权限,否则调用会出现如下报错:
403 reason: Unauthorized to validateNamespaceOperation for operation [CREATE_TOPIC] on namespace [<namespace>]
3.0 社区版本的社区代码 topic 各个 admin 接口权限汇总如下:
switch (operation) {
case LOOKUP:
case GET_STATS:
case GET_METADATA:
// 需要生产或消费权限
return canLookupAsync(topicName, role, authData);
case PRODUCE:
// 需要生产权限
return canProduceAsync(topicName, role, authData);
case GET_SUBSCRIPTIONS:
case CONSUME:
case SUBSCRIBE:
case UNSUBSCRIBE:
case SKIP:
case EXPIRE_MESSAGES:
case PEEK_MESSAGES:
case RESET_CURSOR:
case GET_BACKLOG_SIZE:
case SET_REPLICATED_SUBSCRIPTION_STATUS:
case GET_REPLICATED_SUBSCRIPTION_STATUS:
// 需要消费权限
return canConsumeAsync(topicName, role, authData, authData.getSubscription());
case TERMINATE:
case COMPACT:
case OFFLOAD:
case UNLOAD:
case TRIM_TOPIC:
case DELETE_METADATA:
case UPDATE_METADATA:
case ADD_BUNDLE_RANGE:
case GET_BUNDLE_RANGE:
case DELETE_BUNDLE_RANGE:
// 需要更高权限即 adminRole/superUser 权限
return CompletableFuture.completedFuture(false);
default:
return FutureUtil.failedFuture(new IllegalStateException("TopicOperation [" + operation.name() + "] is not supported."));
}
Topic 层级的大部分生产/消费类接口可直接使用 SDK,但涉及元数据管理或敏感操作的接口需参照下表:
admin 接口名
admin 接口是否支持
说明
云 API 接口
createPartitionedTopic
不支持
创建分区主题
CreateTopic
deletePartitionedTopic
不支持
删除分区主题
getPartitionedTopicList
支持,需要 consume 权限
获取当前命名空间下的所有分区主题
lookup
支持,需要 produce 或 consume 权限
获取当前 topic 所在的 broker 地址
不支持
getPartitionedStats
支持,需要 produce 或 consume 权限
获取当前 topic 的状态
getInternalStats
支持,需要 produce 或 consume 权限
获取当前 topic 的底层状态(bookie 相关)
getSubscriptions
支持,需要 consume 权限
获取当前 topic 下的订阅信息
createSubscription
支持,需要 consume 权限
在当前 topic 下创建订阅
deleteSubscription
支持,需要 consume 权限
删除 topic 下的订阅
skipMessages
支持,需要 consume 权限
当前订阅跳过 readPosition 位点后指定数量的消息
不支持
expireTopicMessages
支持,需要 consume 权限
当前订阅将生产早于指定时间的消息设置为 ack
不支持
getMessageByID
支持,需要 consume 权限
获取指定消息 id 的消息
resetCursor
支持,需要 consume 权限
当前订阅重新推送指定时间之后生产的消息
unloadTopic
不支持
重载主题,触发客户端重连,并重新推送未确认的消息
不支持