跳转到内容
Alibaba Cloud AI Agent Handbook 已开源，汇集50+工程师的一手实践经验点此了解
最新版
企业版 NACOS
MCP
博客
电子书
下载
控制台样例
专家答疑
中文

运维SDK

Nacos 的运维 SDK（或称 Nacos Maintainer SDK）是一个针对 Nacos 配置中心、服务注册中心、AI 管理中心等功能 运维 场景的 Java SDK。旨在为 Nacos 的运维人员或部分特殊应用场景（如 网关类应用、控制台类应用）提供稳定易用的运维能力，方便运维人员或特殊应用访问 Nacos，进行配置、服务和 AI 资源的管理操作。

因为Nacos 的 运维SDK的定位，Nacos的运维SDK会提供大范围的数据获取API，因此Nacos的运维SDK需要使用较高权限的身份进行登录后才能使用，以防止存在数据泄漏的隐患。

如果您的使用场景不是运维人员操作或特殊应用场景（如网关类应用，控制台类应用），请使用Nacos Client （如Nacos Java Client, Nacos Go Client等)。

目前 Nacos 的 运维SDK只支持Java SDK，后续会支持更多语言的SDK。

Nacos的运维SDK基于Nacos Admin API实现，相同的能力可以通过对应的Nacos Admin API进行操作。

1. 引用概述

1.1. Java 版本依赖

Nacos 的 Java SDK需要 JDK 1.8 及以上版本的Java运行环境。

1.2. Maven 坐标

<!-- 3.0.0 及以上版本支持 -->
<dependency>
    <groupId>com.alibaba.nacos</groupId>
    <artifactId>nacos-maintainer-client</artifactId>
    <version>${nacos.client.version}</version>
</dependency>

本文推荐使用 3.3.0 正式版，将 ${nacos.client.version} 设置为 3.3.0，以使用本文的 MCP 和 Agent 管理接口。

Maintainer SDK 与 Client SDK 使用相同的 JSON 适配层。Jackson 2/3 依赖、自动选择与手动指定方式见 JSON 适配与 Jackson 2/3 接入。

2. 初始化SDK

Nacos 初始化SDK时需要使用对应的工厂 Factory 类进行不同模块的创建：

Properties properties = new Properties();
// 指定Nacos-Server的地址
properties.setProperty("serverAddr","localhost:8848");


// 设置Nacos的管理员用户密码
properties.setProperty("username","nacos");
properties.setProperty("password","{your_admin_password}");


// 初始化配置中心的Nacos Maintainer Service
ConfigMaintainerService configMaintainerService = ConfigMaintainerFactory.createConfigMaintainerService(properties);


// 初始化注册中心的Nacos Maintainer Service
NamingMaintainerService namingMaintainerService = NamingMaintainerFactory.createNamingMaintainerService(properties);


// 初始化 AI 模块的 Nacos Maintainer Service
AiMaintainerService aiMaintainerService = AiMaintainerFactory.createAiMaintainerService(properties);

请将示例中的账号和密码替换为实际值，账号需具备对应操作的权限，参见配置访问凭据。

AI 管理接口位于 com.alibaba.nacos.maintainer.client.ai 包，通过以下入口获取：

入口接口用途
aiMaintainerService.mcp()McpMaintainerServiceMCP 定义与版本生命周期。
aiMaintainerService.agent()AgentMaintainerServiceAgent 定义、版本及运行端点管理。
aiMaintainerService.a2a()A2aMaintainerService旧 A2A 管理兼容接口。
aiMaintainerService.prompt()PromptMaintainerServicePrompt 管理。
aiMaintainerService.skill()SkillMaintainerServiceSkill 管理。
aiMaintainerService.agentSpec()AgentSpecMaintainerServiceAgentSpec 管理。
aiMaintainerService.pipeline()PipelineMaintainerService发布流水线执行查询。

MCP 和 A2A 方法也可以直接通过 aiMaintainerService 调用。调用 AI 管理接口时，不传 namespaceId 的重载使用默认命名空间 public。版本状态和发布流程见 AI 资源生命周期管理。

3. 配置中心运维 API

3.1. 获取配置

描述

从 Nacos 获取配置。

ConfigDetailInfo getConfig(String dataId) throws NacosException;


ConfigDetailInfo getConfig(String dataId, String groupName) throws NacosException;


ConfigDetailInfo getConfig(String dataId, String groupName, String namespaceId) throws NacosException;

请求参数

参数名参数类型描述
dataIdstring配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、”_”），不超过 256 字节。
groupNamestring配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、”_”），不超过128字节。
namespaceIdstring配置所属的命名空间ID。

返回值

参数类型描述
ConfigDetailInfo配置的具体信息

具体ConfigDetailInfo的内容如下：

参数名参数类型描述
idlong配置在实际存储介质中的ID，没有业务含义，仅作为配置在存储介质中的唯一标识。一般为唯一自增ID。
namespaceIdstring配置所属的命名空间ID。
groupNamestring配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、”_”），不超过128字节。
dataIdstring配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、”_”），不超过 256 字节。
md5string配置内容的md5值。
typestring配置的类型，如properties、json、yaml等，主要用于标记和展示。
appNamestring配置所属的应用名称。
createTimelong配置的创建时间，为时间戳，单位为毫秒。
modifyTimelong配置的最新更新时间，为时间戳，单位为毫秒。
contentstring配置内容。
schemastring配置的 schema 文本，未设置时为 null。
descstring配置的描述信息。
encryptedDataKeystring配置的加密密钥，当使用配置的加密功能时，该字段才有值。
createUserstring创建此配置的用户名。
createIpstring创建此配置的来源IP。
configTagsstring此配置的标签，多个标签用逗号,分隔。

请求示例

try {
    // 以下3种调用均会获得 `public`命名空间下，groupName为`DEFAULT_GROUP`，dataId为`maintain.client.test`的配置信息。
    ConfigDetailInfo configDetailInfo = configMaintainerService.getConfig("maintain.client.test");
    configDetailInfo = configMaintainerService.getConfig("maintain.client.test", Constants.DEFAULT_GROUP);
    configDetailInfo = configMaintainerService.getConfig("maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

读取配置超时或网络异常，抛出 NacosException 异常。

3.2. 发布配置

描述

用于发布 Nacos 配置，以便通过自动化手段降低运维成本。

boolean publishConfig(String dataId, String content) throws NacosException;


boolean publishConfig(String dataId, String groupName, String content) throws NacosException;


boolean publishConfig(String dataId, String groupName, String namespaceId, String content) throws NacosException;


boolean publishConfig(String dataId, String groupName, String namespaceId, String content, String desc) throws NacosException;


boolean publishConfig(String dataId, String groupName, String namespaceId, String content, String desc, String type) throws NacosException;


boolean publishConfig(String dataId, String groupName, String namespaceId, String content, String appName, String srcUser, String configTags, String desc, String type) throws NacosException;

请求参数

参数名参数类型描述
dataIdstring配置 ID。只允许英文字符和 4 种特殊字符（“.”、“:”、“-”、“_”），不超过 256 字节。
groupNamestring配置分组。只允许英文字符和 4 种特殊字符（“.”、“:”、“-”、“_”），不超过 128 字节。
namespaceIdstring配置所属的命名空间ID。
contentstring配置内容，受服务端 maxContent 及容量检查中的配置大小限制约束。
descstring配置的描述内容。
typestring配置类型，见 com.alibaba.nacos.api.config.ConfigType，默认为TEXT
appNamestring配置所属的应用名称。
srcUserstring创建此配置的用户名，即代理此用户进行配置发布，此配置的createUser将为此用户，若传入空字串，则表示当前登录的用户名作为createUser。
configTagsstring此配置的标签，多个标签用逗号,分隔。

返回参数

参数类型描述
boolean是否发布成功

请求示例

try {
// 以下调用均会在 `public`命名空间下，创建groupName为`DEFAULT_GROUP`，dataId为`maintain.client.test`的配置, 配置内容为`testContent`。
    boolean result = configMaintainerService.publishConfig("maintain.client.test", "testContent");
    result = configMaintainerService.publishConfig("maintain.client.test", Constants.DEFAULT_GROUP, "testContent");
    result = configMaintainerService.publishConfig("maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID, "testContent");
    result = configMaintainerService.publishConfig("maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID, "testContent", "test");
    result = configMaintainerService.publishConfig("maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID, "testContent", "test", "TEXT");
    result = configMaintainerService.publishConfig("maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID, "testContent", "testApp", null, "testTag", "test", "TEXT");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

读取配置超时或网络异常，抛出 NacosException 异常。

3.3. 删除配置

描述

用于删除 Nacos 配置，以便通过自动化手段降低运维成本。

boolean deleteConfig(String dataId) throws NacosException;


boolean deleteConfig(String dataId, String groupName) throws NacosException;


boolean deleteConfig(String dataId, String groupName, String namespaceId) throws NacosException;

请求参数

参数名参数类型描述
dataIdstring配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、”_”），不超过 256 字节。
groupNamestring配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、”_”），不超过128字节。
namespaceIdstring配置所属的命名空间ID。

返回参数

参数类型描述
boolean是否删除成功

请求示例

try {
    // 以下3种调用均会删除 `public`命名空间下，groupName为`DEFAULT_GROUP`，dataId为`maintain.client.test`的配置信息。
    boolean result =  configMaintainerService.deleteConfig("maintain.client.test");
    result = configMaintainerService.deleteConfig("maintain.client.test", Constants.DEFAULT_GROUP);
    result = configMaintainerService.deleteConfig("maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

读取配置超时或网络异常，抛出 NacosException 异常。

3.4. 批量删除配置

描述

用于批量删除 Nacos 配置，以便通过自动化手段降低运维成本。

boolean deleteConfigs(List<Long> ids) throws NacosException;


boolean deleteConfigs(List<Long> ids, String namespaceId) throws NacosException;

请求参数

参数名参数类型描述
idsList<Long>待删除配置的ID列表，此ID为配置在实际存储介质中的ID，需要从获取配置或获取配置列表API中的id字段获取。
namespaceIdstring配置所属的命名空间 ID；省略时使用默认命名空间 public。

返回值

参数类型描述
boolean是否删除成功

请求示例

try {
    ConfigDetailInfo configDetailInfo = configMaintainerService.getConfig("maintain.client.test");
    boolean result = configMaintainerService.deleteConfigs(Collections.singletonList(configDetailInfo.getId()));
    // 指定命名空间时，可改用：
    // boolean result = configMaintainerService.deleteConfigs(Collections.singletonList(configDetailInfo.getId()), Constants.DEFAULT_NAMESPACE_ID);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

读取配置超时或网络异常，抛出 NacosException 异常。

3.5. 获取配置列表

描述

可以通过此API，获取获取满足条件的配置列表，不支持模糊查询，若需要进行模糊查询，请使用搜索配置列表API。

Page<ConfigBasicInfo> listConfigs(String namespaceId) throws NacosException;


Page<ConfigBasicInfo> listConfigs(String dataId, String groupName, String namespaceId) throws NacosException;


Page<ConfigBasicInfo> listConfigs(String dataId, String groupName, String namespaceId, String type) throws NacosException;


Page<ConfigBasicInfo> listConfigs(String dataId, String groupName, String namespaceId, String type, String configTags, String appName) throws NacosException;


Page<ConfigBasicInfo> listConfigs(String dataId, String groupName, String namespaceId, String type, String configTags, String appName, int pageNo, int pageSize) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring配置所属的命名空间ID。
dataIdstring配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、”_”），不超过 256 字节, 默认为""，不为空时则只会匹配dataId为此值的配置。
groupNamestring配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、”_”），不超过128字节，默认为""，不为空时则只会匹配groupName为此值的配置。
typestring配置类型，见 com.alibaba.nacos.api.config.ConfigType，默认为""，不为空时则只会匹配类型为此值的配置。
configTagsstring此配置的标签，多个标签用逗号,分隔，默认为""，不为空时则只会匹配标签为此值的配置。
appNamestring配置所属的应用名称，默认为""，不为空时则只会匹配应用名为此值的配置。
pageNoint配置列表的分页页码，默认为1。
pageSizeint配置列表的分页大小，默认为100。

返回参数

参数类型描述
Page<ConfigBasicInfo>配置列表的分页结果

具体Page及ConfigBasicInfo的内容如下：

参数名参数类型描述
totalCountint符合该条件下的配置总数。
pageNumberint当前页码。
pagesAvailableint分页的总页数。
pageItemsList<ConfigBasicInfo>当前页的配置列表。
参数名参数类型描述
idlong配置在实际存储介质中的ID，没有业务含义，仅作为配置在存储介质中的唯一标识。一般为唯一自增ID。
namespaceIdstring配置所属的命名空间ID。
groupNamestring配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、”_”），不超过128字节。
dataIdstring配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、”_”），不超过 256 字节。
md5string配置内容的md5值。
typestring配置的类型，如properties、json、yaml等，主要用于标记和展示。
appNamestring配置所属的应用名称。
createTimelong配置的创建时间，为时间戳，单位为毫秒。
modifyTimelong配置的最新更新时间，为时间戳，单位为毫秒。

请求示例

try {
    // 获取`public`命名空间下所有配置的第一页（最大100个）。
    Page<ConfigBasicInfo> result = configMaintainerService.listConfigs(Constants.DEFAULT_NAMESPACE_ID);
    // 获取`public`命名空间下配置分组为`DEFAULT_GROUP`的所有配置的第一页（最大100个）。
    result = configMaintainerService.listConfigs("", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID);
    // 获取`public`命名空间下类型为`JSON`的所有配置的第一页（最大100个）。
    result = configMaintainerService.listConfigs("", "", Constants.DEFAULT_NAMESPACE_ID, "JSON");
    // 获取`public`命名空间下带有标签为`testTag1`且配置所属应用为`testApp`的所有配置的第一页（最大100个）。
    result = configMaintainerService.listConfigs("", "", Constants.DEFAULT_NAMESPACE_ID, "", "testTag1", "testApp");
    // 获取`public`命名空间下所有配置的第一页（最大10个）。
    result = configMaintainerService.listConfigs("", "", Constants.DEFAULT_NAMESPACE_ID, "", "", "", 1, 10);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

读取配置超时或网络异常，抛出 NacosException 异常。

3.6. 搜索配置列表

描述

可以通过此API，获取获取满足条件的配置列表，支持模糊查询，若需要进行精确查询，请使用查询配置列表API。

Page<ConfigBasicInfo> searchConfigs(String dataId, String groupName, String namespaceId) throws NacosException;


Page<ConfigBasicInfo> searchConfigs(String dataId, String groupName, String namespaceId, String type) throws NacosException;


Page<ConfigBasicInfo> searchConfigs(String dataId, String groupName, String namespaceId, String configDetail, String type) throws NacosException;


Page<ConfigBasicInfo> searchConfigs(String dataId, String groupName, String namespaceId, String configDetail, String type, String configTags, String appName) throws NacosException;


Page<ConfigBasicInfo> searchConfigs(String dataId, String groupName, String namespaceId, String configDetail, String type, String configTags, String appName, int pageNo, int pageSize) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring配置所属的命名空间ID。
dataIdstring配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、”_”），不超过 256 字节, 默认为""，不为空时则只会匹配所有dataId包含此值的配置。
groupNamestring配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、”_”），不超过128字节，默认为""，不为空时则只会匹配groupName包含此值的配置。
typestring配置类型，见 com.alibaba.nacos.api.config.ConfigType，默认为""，不为空时则只会匹配类型为此值的配置。
configDetailstring配置的内容，默认为""，不为空时则只会匹配配置内容包含此值的配置。
configTagsstring此配置的标签，多个标签用逗号,分隔，默认为""，不为空时则只会匹配标签为此值的配置。
appNamestring配置所属的应用名称，默认为""，不为空时则只会匹配应用名为此值的配置。
pageNoint配置列表的分页页码，默认为1。
pageSizeint配置列表的分页大小，默认为100。

返回参数

参数类型描述
Page<ConfigBasicInfo>配置列表的分页结果

具体Page及ConfigBasicInfo的内容如下：

参数名参数类型描述
totalCountint符合该条件下的配置总数。
pageNumberint当前页码。
pagesAvailableint分页的总页数。
pageItemsList<ConfigBasicInfo>当前页的配置列表。
参数名参数类型描述
idlong配置在实际存储介质中的ID，没有业务含义，仅作为配置在存储介质中的唯一标识。一般为唯一自增ID。
namespaceIdstring配置所属的命名空间ID。
groupNamestring配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、”_”），不超过128字节。
dataIdstring配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、”_”），不超过 256 字节。
md5string配置内容的md5值。
typestring配置的类型，如properties、json、yaml等，主要用于标记和展示。
appNamestring配置所属的应用名称。
createTimelong配置的创建时间，为时间戳，单位为毫秒。
modifyTimelong配置的最新更新时间，为时间戳，单位为毫秒。

请求示例

try {
    // 获取`public`命名空间下配置分组包含`test`字符的所有配置的第一页（最大100个）。
    Page<ConfigBasicInfo> result = configMaintainerService.searchConfigs("", "test", Constants.DEFAULT_NAMESPACE_ID);
    // 获取`public`命名空间下类型为`JSON`的所有配置的第一页（最大100个）。
    result = configMaintainerService.searchConfigs("", "", Constants.DEFAULT_NAMESPACE_ID, "JSON");
    // 获取`public`命名空间下配置内容包含`test`字符的所有配置的第一页（最大100个）。
    result = configMaintainerService.searchConfigs("", "", Constants.DEFAULT_NAMESPACE_ID, "test", "");
    // 获取`public`命名空间下标签为`testTag1`且配置所属应用为`testApp`的所有配置的第一页（最大100个）。
    result = configMaintainerService.searchConfigs("", "", Constants.DEFAULT_NAMESPACE_ID, "", "", "testTag1", "testApp");
    // 获取`public`命名空间下所有配置的第一页（最大10个）。
    result = configMaintainerService.searchConfigs("", "", Constants.DEFAULT_NAMESPACE_ID, "", "", "", "", 1, 10);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

读取配置超时或网络异常，抛出 NacosException 异常。

3.7. 克隆配置

描述

通过此API，可以将所指定的配置克隆到另一个命名空间下，克隆时可以指定新的groupName及dataId.

Map<String, Object> cloneConfig(String namespaceId, List<ConfigCloneInfo> cloneInfos, String srcUser, SameConfigPolicy policy) throws NacosException;


Map<String, Object> cloneConfig(String sourceNamespaceId, String targetNamespaceId, List<ConfigCloneInfo> cloneInfos, String srcUser, SameConfigPolicy policy) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring配置来源及克隆目标的命名空间 ID；省略时使用默认命名空间 public。
sourceNamespaceIdstring配置来源命名空间 ID；省略时使用默认命名空间 public。
targetNamespaceIdstring克隆目标命名空间 ID；省略时使用默认命名空间 public。
cloneInfosList<ConfigCloneInfo>需要克隆的配置列表
srcUserstring克隆此配置的用户名，即代理此用户进行配置克隆，克隆的配置的createUser将为此用户，若传入空字串，则表示当前登录的用户名作为createUser。
policySameConfigPolicy克隆配置时出现冲突后的处理策略，默认为ABORT，可选值为ABORT(终止）,SKIP（跳过）,OVERWRITE（覆盖）。

其中ConfigCloneInfo中的参数详情为：

参数名参数类型描述
configIdlong配置在实际存储介质中的ID，没有业务含义，仅作为配置在存储介质中的唯一标识。一般为唯一自增ID。
targetGroupNamestring目标配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、”_”），不超过128字节，为空时则使用配置当前的分组。
targetDataIdstring目标配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、”_”），不超过 256 字节，为空时则使用配置当前的 ID。

返回参数

参数类型描述
Map<String, Object>克隆配置的结果，根据policy的不同，可能返回成功的数量，失败的数量，跳过的数量，或覆盖的数量

请求示例

try {
    // 将配置ID为1的配置克隆到`clone-test`命名空间下，克隆策略为`ABORT`，即如果目标命名空间下有同名配置，则克隆失败。
    ConfigCloneInfo configCloneInfo = new ConfigCloneInfo();
    configCloneInfo.setConfigId(1L);
    Map<String, Object> result = configMaintainerService.cloneConfig("clone-test", Collections.singletonList(configCloneInfo), "", SameConfigPolicy.ABORT);
    // 将 public 命名空间中的配置克隆到 clone-test 命名空间。
    // result = configMaintainerService.cloneConfig(Constants.DEFAULT_NAMESPACE_ID, "clone-test", Collections.singletonList(configCloneInfo), "", SameConfigPolicy.ABORT);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

读取配置超时或网络异常，抛出 NacosException 异常。

3.8. 获取命名空间下所有配置列表

描述

通过此接口，可以获取指定命名空间下所有的配置列表。

List<ConfigBasicInfo> getConfigListByNamespace(String namespaceId) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring配置所属的命名空间ID

返回参数

参数类型描述
List<ConfigBasicInfo>配置列表的分页结果

具体ConfigBasicInfo的内容如下：

参数名参数类型描述
idlong配置在实际存储介质中的ID，没有业务含义，仅作为配置在存储介质中的唯一标识。一般为唯一自增ID。
namespaceIdstring配置所属的命名空间ID。
groupNamestring配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、”_”），不超过128字节。
dataIdstring配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、”_”），不超过 256 字节。
md5string配置内容的md5值。
typestring配置的类型，如properties、json、yaml等，主要用于标记和展示。
appNamestring配置所属的应用名称。
createTimelong配置的创建时间，为时间戳，单位为毫秒。
modifyTimelong配置的最新更新时间，为时间戳，单位为毫秒。

请求示例

try {
    List<ConfigBasicInfo> result = configMaintainerService.getConfigListByNamespace(Constants.DEFAULT_NAMESPACE_ID);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

读取配置超时或网络异常，抛出 NacosException 异常。

3.9. 获取配置订阅者列表

描述

通过此接口，可以获取某个配置的订阅者列表。若希望获取某个配置订阅者订阅了哪些配置，请使用获取某个订阅者订阅的所有配置列表。

ConfigListenerInfo getListeners(String dataId, String groupName) throws NacosException;


ConfigListenerInfo getListeners(String dataId, String groupName, String namespaceId, boolean aggregation) throws NacosException;

请求参数

参数名参数类型描述
groupNamestring配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、”_”），不超过128字节。
dataIdstring配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、”_”），不超过 256 字节。
namespaceIdstring配置所属的命名空间ID。
aggregationboolean是否聚合查询，默认为true，为false时仅查询请求所在节点的订阅者列表，为true时查询整个集群中此配置的订阅者列表。

返回参数

参数类型描述
ConfigListenerInfo配置的订阅者信息

其中ConfigListenerInfo的内容如下：

参数名参数类型描述
queryTypestring此接口固定返回config
listenersStatusMap<String, List<String>>订阅者列表，key为订阅者的IP，value为此订阅者订阅到的配置的md5值

请求示例

try {
    // 以下两种调用，均获取`public`命名空间ID，`DEFAULT_GROUP`分组，`maintain.client.test`配置的全集群的订阅者列表。
    ConfigListenerInfo result = configMaintainerService.getListeners("maintain.client.test", Constants.DEFAULT_GROUP);
    result = configMaintainerService.getListeners("maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID, true);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

读取配置超时或网络异常，抛出 NacosException 异常。

3.10. 获取某个订阅者订阅的所有配置列表

描述

通过此接口，可以获取某个配置订阅者所订阅的配置列表。若希望查询配置的订阅者列表，请使用获取配置订阅者列表。

ConfigListenerInfo getAllSubClientConfigByIp(String ip, boolean all, String namespaceId, boolean aggregation) throws NacosException;

请求参数

参数名参数类型描述
ipstring配置订阅者的IP
allboolean是否查询所有相同IP的订阅者所订阅的配置列表，默认为false，为false时仅返回第一个匹配到ip的订阅者订阅的配置列表，为true时返回所有匹配到ip的订阅者订阅的配置列表。
namespaceIdstring配置所属的命名空间ID。
aggregationboolean是否聚合查询，默认为true，为false时仅查询请求所在节点的订阅者列表，为true时查询整个集群中此配置的订阅者列表。

返回参数

参数类型描述
ConfigListenerInfo配置的订阅者信息

其中ConfigListenerInfo的内容如下：

参数名参数类型描述
queryTypestring此接口固定返回ip
listenersStatusMap<String, List<String>>订阅者列表，key为订阅的配置的dataId+groupName+namespaceId，value为此订阅者订阅到的配置的md5值

请求示例

try {
    ConfigListenerInfo result = configMaintainerService.getAllSubClientConfigByIp("127.0.0.1", false, Constants.DEFAULT_NAMESPACE_ID, true);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

读取配置超时或网络异常，抛出 NacosException 异常。

3.11. 发布Beta灰度配置

描述

用于灰度发布 Nacos 配置，方便修改配置时进行测试，降低因配置错误导致的应用故障范围。

boolean publishBetaConfig(String dataId, String groupName, String namespaceId, String content, String appName, String srcUser, String configTags, String desc, String type, String betaIps) throws NacosException;

请求参数

参数名参数类型描述
dataIdstring配置 ID。只允许英文字符和 4 种特殊字符（“.”、“:”、“-”、“_”），不超过 256 字节。
groupNamestring配置分组。只允许英文字符和 4 种特殊字符（“.”、“:”、“-”、“_”），不超过 128 字节。
namespaceIdstring配置所属的命名空间ID。
contentstring配置内容，受服务端 maxContent 及容量检查中的配置大小限制约束。
descstring配置的描述内容。
typestring配置类型，见 com.alibaba.nacos.api.config.ConfigType，默认为TEXT
appNamestring配置所属的应用名称。
srcUserstring创建此配置的用户名，即代理此用户进行配置发布，此配置的createUser将为此用户，若传入空字串，则表示当前登录的用户名作为createUser。
configTagsstring此配置的标签，多个标签用逗号,分隔。
betaIpsstring配置的灰度IP列表，多个IP用逗号,分隔。

返回参数

参数类型描述
boolean是否发布成功

请求示例

try {
    // 对`127.0.0.1`这个ip进行`maintain.client.test`配置的Beta灰度。
    boolean result = configMaintainerService.publishBetaConfig("maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID, "testBeta", "testApp", "", "testTag1", "test", "TEXT", "127.0.0.1");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

读取配置超时或网络异常，抛出 NacosException 异常。

3.12. 停止配置Beta灰度

描述

停止指定配置的Beta配置

boolean stopBeta(String dataId, String groupName) throws NacosException;


boolean stopBeta(String dataId, String groupName, String namespaceId) throws NacosException;

请求参数

参数名参数类型描述
dataIdstring配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、”_”），不超过 256 字节。
groupNamestring配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、”_”），不超过128字节。
namespaceIdstring配置所属的命名空间ID。

返回参数

参数类型描述
boolean是否停止Beta灰度成功

请求示例

try {
    // 对`127.0.0.1`这个ip进行`maintain.client.test`配置的Beta灰度。
    boolean result = configMaintainerService.publishBetaConfig("maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID, "testBeta", "testApp", "", "testTag1", "test", "TEXT", "127.0.0.1");
    // 停止`maintain.client.test`配置的Beta灰度
    result = configMaintainerService.stopBeta("maintain.client.test", Constants.DEFAULT_GROUP);
    result = configMaintainerService.stopBeta("maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

读取配置超时或网络异常，抛出 NacosException 异常。

3.13. 查询Beta灰度的配置

描述

查询指定配置的Beta配置

ConfigGrayInfo queryBeta(String dataId, String groupName) throws NacosException;


ConfigGrayInfo queryBeta(String dataId, String groupName, String namespaceId) throws NacosException;

请求参数

参数名参数类型描述
dataIdstring配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、”_”），不超过 256 字节。
groupNamestring配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、”_”），不超过128字节。
namespaceIdstring配置所属的命名空间ID。

返回参数

参数类型描述
ConfigGrayInfo灰度配置的信息

其中ConfigGrayInfo的内容如下：

参数名参数类型描述
idlong配置在实际存储介质中的ID，没有业务含义，仅作为配置在存储介质中的唯一标识。一般为唯一自增ID。
namespaceIdstring配置所属的命名空间ID。
groupNamestring配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、”_”），不超过128字节。
dataIdstring配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、”_”），不超过 256 字节。
md5string配置内容的md5值。
typestring配置的类型，如properties、json、yaml等，主要用于标记和展示。
appNamestring配置所属的应用名称。
createTimelong配置的创建时间，为时间戳，单位为毫秒。
modifyTimelong配置的最新更新时间，为时间戳，单位为毫秒。
contentstring配置内容。
schemastring灰度配置的此字段为 null。
descstring配置的描述信息。
encryptedDataKeystring配置的加密密钥，当使用配置的加密功能时，该字段才有值。
createUserstring创建此配置的用户名。
createIpstring创建此配置的来源IP。
configTagsstring此配置的标签，多个标签用逗号,分隔。
grayNamestring灰度名称，固定为beta
grayRulestring灰度的规则，格式为json,其中的expr为灰度的ip列表

请求示例

try {
    // 对`127.0.0.1`这个ip进行`maintain.client.test`配置的Beta灰度。
    boolean publishResult = configMaintainerService.publishBetaConfig("maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID, "testBeta", "testApp", "", "testTag1", "test", "TEXT", "127.0.0.1");
    // 查询`maintain.client.test`配置的Beta灰度
    ConfigGrayInfo result = configMaintainerService.queryBeta("maintain.client.test", Constants.DEFAULT_GROUP);
    result = configMaintainerService.queryBeta("maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID);}
catch (NacosException e) {
    e.printStackTrace();
}

异常说明

读取配置超时或网络异常，抛出 NacosException 异常。

3.14. 获取配置历史历史版本列表

描述

获取指定配置的历史版本列表

Page<ConfigHistoryBasicInfo> listConfigHistory(String dataId, String groupName, String namespaceId, int pageNo, int pageSize) throws NacosException;

请求参数

参数名参数类型描述
dataIdstring配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、”_”），不超过 256 字节。
groupNamestring配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、”_”），不超过128字节。
namespaceIdstring配置所属的命名空间ID。
pageNoint配置历史版本列表的分页页码，默认为1。
pageSizeint配置历史版本列表的分页大小，默认为100。

返回参数

参数类型描述
Page<ConfigHistoryBasicInfo>配置历史版本列表的分页结果

其中Page及ConfigHistoryBasicInfo的内容如下：

参数名参数类型描述
totalCountint符合该条件下的配置历史版本总数。
pageNumberint当前页码。
pagesAvailableint分页的总页数。
pageItemsList<ConfigHistoryBasicInfo>当前页的配置历史版本列表。
参数名参数类型描述
idlong配置历史版本的ID，没有业务含义，仅作为配置历史版本在存储介质中的唯一标识。一般为唯一自增ID。
namespaceIdstring配置所属的命名空间ID。
groupNamestring配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、”_”），不超过128字节。
dataIdstring配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、”_”），不超过 256 字节。
md5string配置内容的md5值。
typestring配置的类型，如properties、json、yaml等，主要用于标记和展示。
appNamestring配置所属的应用名称。
createTimelong配置的创建时间，为时间戳，单位为毫秒。
modifyTimelong配置的最新更新时间，为时间戳，单位为毫秒。
srcUserstring操作此版本的用户名。
srcIpstring操作此版本的来源IP。
opTypestring此历史版本的操作类型，I为创建，U为更新，D为删除
publishTypestring此历史版本的发布类型，formal为正式发布，gray为灰度发布

请求示例

try {
    // 查询`maintain.client.test`配置的历史版本列表。
    Page<ConfigHistoryBasicInfo> configHistoryBasicInfoPage = configMaintainerService.listConfigHistory("maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID, 1, 10);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

读取配置超时或网络异常，抛出 NacosException 异常。

3.15. 获取配置历史历史版本详情

描述

通过此API，可以查询某一配置的某一个历史版本详情。

ConfigHistoryDetailInfo getConfigHistoryInfo(String dataId, String groupName, String namespaceId, Long nid) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring配置所属的命名空间ID。
groupNamestring配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、”_”），不超过128字节。
dataIdstring配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、”_”），不超过 256 字节。
nidlong目标历史版本在的Id， 通过获取配置历史历史版本列表接口获取。

返回参数

参数类型描述
ConfigHistoryDetailInfo配置历史版本的详细信息

其中ConfigHistoryDetailInfo的内容如下：

参数名参数类型描述
idlong配置历史版本的ID，没有业务含义，仅作为配置历史版本在存储介质中的唯一标识。一般为唯一自增ID。
namespaceIdstring配置所属的命名空间ID。
groupNamestring配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、”_”），不超过128字节。
dataIdstring配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、”_”），不超过 256 字节。
md5string配置内容的md5值。
typestring配置的类型，如properties、json、yaml等，主要用于标记和展示。
appNamestring配置所属的应用名称。
createTimelong配置的创建时间，为时间戳，单位为毫秒。
modifyTimelong配置的最新更新时间，为时间戳，单位为毫秒。
contentstring配置历史版本的内容。
schemastring该历史版本的 schema 文本，未设置时为 null。
encryptedDataKeystring配置解密的密钥，仅当配置为加密配置时返回。
grayNamestring配置历史版本的灰度发布名称，当此次历史版本为灰度发布时存在，一般为beta
extInfostring历史版本的扩展信息，目前存储灰度发布时的发布规则，如灰度的ip地址列表，格式为json。

请求示例

try {
    // 查询`maintain.client.test`配置的历史版本列表。
    Page<ConfigHistoryBasicInfo> configHistoryBasicInfoPage = configMaintainerService.listConfigHistory("maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID, 1, 10);
    Long nid = configHistoryBasicInfoPage.getPageItems().get(0).getId();
    // 查询`maintain.client.test`配置的历史版本列表中第一个历史版本的详细信息。
    ConfigHistoryDetailInfo result = configMaintainerService.getConfigHistoryInfo("maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID, nid);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

读取配置超时或网络异常，抛出 NacosException 异常。

3.16. 查询配置上一版本信息详情

描述

获取指定配置的上一历史版本的信息详情

ConfigHistoryDetailInfo getPreviousConfigHistoryInfo(String dataId, String groupName, String namespaceId, Long id) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring配置所属的命名空间ID。
groupNamestring配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、”_”），不超过128字节。
dataIdstring配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、”_”），不超过 256 字节。
idlong配置在实际存储介质中的ID，通过获取配置 获取

返回参数

参数类型描述
ConfigHistoryDetailInfo配置历史版本的详细信息

其中ConfigHistoryDetailInfo的内容如下：

参数名参数类型描述
idlong配置历史版本的ID，没有业务含义，仅作为配置历史版本在存储介质中的唯一标识。一般为唯一自增ID。
namespaceIdstring配置所属的命名空间ID。
groupNamestring配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、”_”），不超过128字节。
dataIdstring配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、”_”），不超过 256 字节。
md5string配置内容的md5值。
typestring配置的类型，如properties、json、yaml等，主要用于标记和展示。
appNamestring配置所属的应用名称。
createTimelong配置的创建时间，为时间戳，单位为毫秒。
modifyTimelong配置的最新更新时间，为时间戳，单位为毫秒。
contentstring配置历史版本的内容。
schemastring该历史版本的 schema 文本，未设置时为 null。
encryptedDataKeystring配置解密的密钥，仅当配置为加密配置时返回。
grayNamestring配置历史版本的灰度发布名称，当此次历史版本为灰度发布时存在，一般为beta
extInfostring历史版本的扩展信息，目前存储灰度发布时的发布规则，如灰度的ip地址列表，格式为json。

请求示例

try {
    // 获取`maintain.client.test`配置的ID。
    Long id = configMaintainerService.getConfig("maintain.client.test").getId();
    // 获取`maintain.client.test`配置的上一历史版本的详细信息。
    ConfigHistoryDetailInfo result = configMaintainerService.getPreviousConfigHistoryInfo("maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID, id);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

读取配置超时或网络异常，抛出 NacosException 异常。

3.17. 触发Nacos Server从存储介质中dump数据到磁盘缓存中

描述

手动触发从存储中加载所有配置数据到Nacos Server本地缓存。

String updateLocalCacheFromStore() throws NacosException;

请求参数

无

返回参数

参数类型描述
String触发dump操作的返回信息

请求示例

try {
    configMaintainerService.updateLocalCacheFromStore();
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

读取配置超时或网络异常，抛出 NacosException 异常。

3.18. 设置配置中心日志级别

描述

动态设置指定模块的日志级别

String setLogLevel(String logName, String logLevel) throws NacosException;

请求参数

参数名参数类型描述
logNamestring日志模块名称，如config-server, config-dump等
logLevelstring日志级别（如INFO、DEBUG）

返回参数

参数类型描述
String设置日志级别的结果信息

请求示例

try {
    configMaintainerService.setLogLevel("config-server", "DEBUG");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

读取配置超时或网络异常，抛出 NacosException 异常。

3.19. 更新配置的元数据

描述

更新配置的元数据，如配置的描述和标签信息

boolean updateConfigMetadata(String dataId, String groupName, String namespaceId, String description, String configTags) throws NacosException;

请求参数

参数名参数类型描述
dataIdstring配置 ID。只允许英字符和 4 种特殊字符（”.”、”:”、”-”、”_”），不超过 256 字节。
groupNamestring配置分组。只允许英字符和 4 种特殊字符（”.”、”:”、”-”、”_”），不超过 128 字节。
namespaceIdstring配置所属的命名空间ID。
descriptionstring配置的描述信息
configTagsstring此配置的标签，多个标签用逗号,分隔。

返回参数

参数类型描述
boolean是否更新成功

请求示例

try {
    configMaintainerService.updateConfigMetadata("maintain.client.test", "DEFAULT_GROUP", "public", "this is a description", "tag1,tag2");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

读取配置超时或网络异常，抛出 NacosException 异常。

3.20. 按详情搜索配置列表

描述

按 dataId、groupName、namespaceId、搜索模式、配置详情、类型、标签、应用名等条件分页搜索配置列表。

Page<ConfigBasicInfo> searchConfigByDetails(String dataId, String groupName, String namespaceId, String search,
        String configDetail, String type, String configTags, String appName, int pageNo, int pageSize) throws NacosException;

请求参数

参数名参数类型描述
dataIdstring配置 ID，支持模糊或精确（由 search 决定）。
groupNamestring配置分组。
namespaceIdstring配置所属的命名空间ID。
searchstring搜索模式：accurate 精确 或 blur 模糊。
configDetailstring配置详情过滤（可选）。
typestring配置类型（可选）。
configTagsstring配置标签，多个用逗号分隔（可选）。
appNamestring配置所属应用名（可选）。
pageNoint页码，从 1 开始。
pageSizeint每页条数。

返回参数

参数类型描述
Page<ConfigBasicInfo>分页配置列表。

请求示例

try {
    Page<ConfigBasicInfo> result = configMaintainerService.searchConfigByDetails(
            "maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID,
            "blur", null, null, null, null, 1, 100);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

读取配置超时或网络异常，抛出 NacosException 异常。

4. 服务发现运维API

4.1. 创建服务

描述

创建一个新的空服务，默认为持久化服务。

String createService(String serviceName) throws NacosException;


String createService(String groupName, String serviceName) throws NacosException;


String createService(String namespaceId, String groupName, String serviceName) throws NacosException;


String createService(String namespaceId, String groupName, String serviceName, boolean ephemeral) throws NacosException;


String createService(String namespaceId, String groupName, String serviceName, boolean ephemeral, float protectThreshold) throws NacosException;


String createService(Service service) throws NacosException;

请求参数

参数名参数类型描述
serviceName(Service.name)string服务的名称
groupName(Service.groupName)string服务的分组名称
namespaceId(Service.namespaceId)string服务所属的命名空间ID
ephemeral(Service.ephemeral)boolean是否临时服务，默认为false
protectThreshold(Service.protectThreshold)float服务的防护阈值，默认为0.0
Service.metadataMap<String,String>服务的元数据
Service.selectorSelector服务的实例选择器，默认为None

返回参数

参数类型描述
String创建服务的结果描述

请求示例

try {
    // 以下请求均创建一个名为`maintain.client.test`的持久化服务。
    String result = namingMaintainerService.createService("maintain.client.test");
    result = namingMaintainerService.createService(Constants.DEFAULT_GROUP, "maintain.client.test");
    result = namingMaintainerService.createService(Constants.DEFAULT_NAMESPACE_ID, Constants.DEFAULT_GROUP, "maintain.client.test");
    result = namingMaintainerService.createService(Constants.DEFAULT_NAMESPACE_ID, Constants.DEFAULT_GROUP, "maintain.client.test", false);
    result = namingMaintainerService.createService(Constants.DEFAULT_NAMESPACE_ID, Constants.DEFAULT_GROUP, "maintain.client.test", false, 0.0f);
    Service service = new Service();
    service.setName("maintain.client.test");
    service.setGroupName(Constants.DEFAULT_GROUP);
    service.setNamespaceId(Constants.DEFAULT_NAMESPACE_ID);
    result = namingMaintainerService.createService(service);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.2. 更新服务

描述

更新服务信息，包括保护阈值、元数据、实例选择器等，服务的名称，分组，命名空间及持久化信息无法修改。

String updateService(String serviceName, Map<String, String> newMetadata, float newProtectThreshold, Selector newSelector) throws NacosException;


String updateService(String groupName, String serviceName, Map<String, String> newMetadata, float newProtectThreshold, Selector newSelector) throws NacosException;


String updateService(String namespaceId, String groupName, String serviceName, Map<String, String> newMetadata, float newProtectThreshold, Selector newSelector) throws NacosException;


String updateService(String namespaceId, String groupName, String serviceName, boolean ephemeral, Map<String, String> newMetadata, float newProtectThreshold, Selector newSelector) throws NacosException;


String updateService(Service service) throws NacosException;

请求参数

参数名参数类型描述
serviceName(Service.name)string服务的名称
groupName(Service.groupName)string服务的分组名称
namespaceId(Service.namespaceId)string服务所属的命名空间ID
ephemeral(Service.ephemeral)boolean是否临时服务，默认为false
newProtectThreshold(Service.protectThreshold)float服务的防护阈值，默认为0.0
newMetadata(Service.metadata)Map<String,String>服务的元数据
newSelector(Service.selector)Selector服务的实例选择器，默认为None

返回参数

参数类型描述
String更新服务的结果描述

请求示例

try {
    // 以下请求均对名为`maintain.client.test`的持久化服务进行更新
    String result = namingMaintainerService.updateService("maintain.client.test", new HashMap<>(), 0.0f, new NoneSelector());
    result = namingMaintainerService.updateService(Constants.DEFAULT_GROUP, "maintain.client.test", new HashMap<>(), 0.0f, new NoneSelector());
    result = namingMaintainerService.updateService(Constants.DEFAULT_NAMESPACE_ID, Constants.DEFAULT_GROUP, "maintain.client.test", new HashMap<>(), 0.0f, new NoneSelector());
    result = namingMaintainerService.updateService(Constants.DEFAULT_NAMESPACE_ID, Constants.DEFAULT_GROUP, "maintain.client.test", false, new HashMap<>(), 0.0f, new NoneSelector());
    Service service = new Service();
    service.setName("maintain.client.test");
    service.setGroupName(Constants.DEFAULT_GROUP);
    service.setNamespaceId(Constants.DEFAULT_NAMESPACE_ID);
    result = namingMaintainerService.updateService(service);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.3. 删除服务

描述

删除服务，仅在服务下不存在实例时可以进行删除。若删除的服务已经不存在，则也会返回删除成功。

String removeService(String serviceName) throws NacosException;


String removeService(String groupName, String serviceName) throws NacosException;


String removeService(String namespaceId, String groupName, String serviceName) throws NacosException;


String removeService(Service service) throws NacosException;

请求参数

参数名参数类型描述
serviceName(Service.name)string服务的名称
groupName(Service.groupName)string服务的分组名称
namespaceId(Service.namespaceId)string服务所属的命名空间ID

返回参数

参数类型描述
String删除服务的结果描述

请求示例

try {
    // 以下请求均删除一个名为`maintain.client.test`的服务。
    String result = namingMaintainerService.removeService("maintain.client.test");
    result = namingMaintainerService.removeService(Constants.DEFAULT_GROUP, "maintain.client.test");
    result = namingMaintainerService.removeService(Constants.DEFAULT_NAMESPACE_ID, Constants.DEFAULT_GROUP, "maintain.client.test");
    Service service = new Service();
    service.setName("maintain.client.test");
    service.setGroupName(Constants.DEFAULT_GROUP);
    service.setNamespaceId(Constants.DEFAULT_NAMESPACE_ID);
    result = namingMaintainerService.removeService(service);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.4. 查询服务详情

描述

查询服务详情，返回服务的元数据、保护阈值、实例选择器以及服务下的逻辑集群Cluster的元数据等。

ServiceDetailInfo getServiceDetail(String serviceName) throws NacosException;


ServiceDetailInfo getServiceDetail(String groupName, String serviceName) throws NacosException;


ServiceDetailInfo getServiceDetail(String namespaceId, String groupName, String serviceName) throws NacosException;


ServiceDetailInfo getServiceDetail(Service service) throws NacosException;

请求参数

参数名参数类型描述
serviceName(Service.name)string服务的名称
groupName(Service.groupName)string服务的分组名称
namespaceId(Service.namespaceId)string服务所属的命名空间ID

返回参数

参数类型描述
ServiceDetailInfo服务的详细信息

其中ServiceDetailInfo中的详细内容有：

参数名参数类型描述
namespaceIdstring服务的命名空间ID
groupNamestring服务的分组名称
serviceNamestring服务的名称
ephemeralboolean服务的持久化属性
protectThresholdfloat服务的保护阈值
selectorSelector服务的实例选择器
metadataMap<String,String>服务的元数据
clusterMapMap<String, ClusterInfo>服务下的逻辑集群信息Map，其中key为逻辑集群名称，value为详细信息
clusterMap.${key}.clusterNamestring逻辑集群的名称
clusterMap.${key}.healthyCheckPortint逻辑集群的健康检查断藕
clusterMap.${key}.useInstancePortForCheckboolean逻辑集群是否使用实例信息的端口进行健康检查
clusterMap.${key}.healthCheckerAbstractHealthChecker逻辑集群的健康检查类型
clusterMap.${key}.metadataMap<String,String>逻辑集群的元数据

请求示例

try {
    // 以下请求均获取一个名为`maintain.client.test`的服务详情信息。
    ServiceDetailInfo result = namingMaintainerService.getServiceDetail("maintain.client.test");
    result = namingMaintainerService.getServiceDetail(Constants.DEFAULT_GROUP, "maintain.client.test");
    result = namingMaintainerService.getServiceDetail(Constants.DEFAULT_NAMESPACE_ID, Constants.DEFAULT_GROUP, "maintain.client.test");
    Service service = new Service();
    service.setName("maintain.client.test");
    service.setNamespaceId(Constants.DEFAULT_NAMESPACE_ID);
    service.setGroupName(Constants.DEFAULT_GROUP);
result = namingMaintainerService.getServiceDetail(service);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.5. 查询服务列表

描述

获取满足条件的服务列表。通过该接口获得的服务列表不带有实例信息，若需要获取服务下的实例列表及实例信息，请使用查询服务实例列表

Page<ServiceView> listServices(String namespaceId) throws NacosException;


Page<ServiceView> listServices(String namespaceId, String groupNameParam, String serviceNameParam) throws NacosException;


Page<ServiceView> listServices(String namespaceId, String groupNameParam, String serviceNameParam, boolean ignoreEmptyService, int pageNo, int pageSize) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring服务所属的命名空间ID
groupNameParamstring服务的分组名称模版，支持使用*进行前缀后缀的模糊匹配，为空时获取所有分组。
serviceNameParamstring服务的名称模版，支持使用*进行前缀后缀的模糊匹配，为空时获取所有服务。
ignoreEmptyServiceboolean是否忽略空服务，默认为true，为true将不返回空服务。
pageNoint分页页码，默认为1。
pageSizeint分页每页大小，默认为100。

返回参数

参数类型描述
Page<ServiceView>满足条件服务列表的分页结果

具体Page及ServiceView的内容如下：

参数名参数类型描述
totalCountint符合该条件下的服务总数。
pageNumberint当前页码。
pagesAvailableint分页的总页数。
pageItemsList<ServiceView>当前页的服务列表。
参数名参数类型描述
namestring服务的名称
groupNamestring服务的分组名称
clusterCountint服务下逻辑集群的个数
ipCountint服务下的实例总数
healthyInstanceCountint服务下的健康实例总数
triggerFlagboolean是否触发了阈值保护

请求示例

try {
    // 以下请求均获取所有服务列表(最多前100个)。
    Page<ServiceView> result = namingMaintainerService.listServices(Constants.DEFAULT_NAMESPACE_ID);
    result = namingMaintainerService.listServices(Constants.DEFAULT_NAMESPACE_ID, "", "");
    result = namingMaintainerService.listServices(Constants.DEFAULT_NAMESPACE_ID, "", "", true, 1, 100);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.6. 查询服务列表（携带实例信息）

描述

获取满足条件的服务列表。通过该接口获得的服务列表会带有实例信息。

Page<ServiceDetailInfo> listServicesWithDetail(String namespaceId) throws NacosException;


Page<ServiceDetailInfo> listServicesWithDetail(String namespaceId, String groupNameParam, String serviceNameParam) throws NacosException;


Page<ServiceDetailInfo> listServicesWithDetail(String namespaceId, String groupNameParam, String serviceNameParam, int pageNo, int pageSize) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring服务所属的命名空间ID
groupNameParamstring服务的分组名称模版，支持使用*进行前缀后缀的模糊匹配，为空时获取所有分组。
serviceNameParamstring服务的名称模版，支持使用*进行前缀后缀的模糊匹配，为空时获取所有服务。
pageNoint分页页码，默认为1。
pageSizeint分页每页大小，默认为100。

返回参数

参数类型描述
Page<ServiceDetailInfo>满足条件服务列表的分页结果

具体Page及ServiceDetailInfo的内容如下：

参数名参数类型描述
totalCountint符合该条件下的服务总数。
pageNumberint当前页码。
pagesAvailableint分页的总页数。
pageItemsList<ServiceDetailInfo>当前页的服务列表。
参数名参数类型描述
namespaceIdstring服务的命名空间ID
groupNamestring服务的分组名称
serviceNamestring服务的名称
ephemeralboolean服务的持久化属性
protectThresholdfloat服务的保护阈值
selectorSelector服务的实例选择器
metadataMap<String,String>服务的元数据
clusterMapMap<String, ClusterInfo>服务下的逻辑集群信息Map，其中key为逻辑集群名称，value为详细信息
clusterMap.${key}.clusterNamestring逻辑集群的名称
clusterMap.${key}.healthyCheckPortint逻辑集群的健康检查断藕
clusterMap.${key}.useInstancePortForCheckboolean逻辑集群是否使用实例信息的端口进行健康检查
clusterMap.${key}.healthCheckerAbstractHealthChecker逻辑集群的健康检查类型
clusterMap.${key}.metadataMap<String,String>逻辑集群的元数据

请求示例

try {
    // 以下请求均获取所有服务列表(最多前100个)。
    Page<ServiceDetailInfo> result = namingMaintainerService.listServicesWithDetail(Constants.DEFAULT_NAMESPACE_ID);
    result = namingMaintainerService.listServicesWithDetail(Constants.DEFAULT_NAMESPACE_ID, "", "");
    result = namingMaintainerService.listServicesWithDetail(Constants.DEFAULT_NAMESPACE_ID, "", "", 1, 10);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.7. 查询服务的订阅者列表

描述

查询指定服务的订阅者列表。

Page<SubscriberInfo> getSubscribers(String serviceName) throws NacosException;


Page<SubscriberInfo> getSubscribers(String groupName, String serviceName) throws NacosException;


Page<SubscriberInfo> getSubscribers(String namespaceId, String groupName, String serviceName) throws NacosException;


Page<SubscriberInfo> getSubscribers(String namespaceId, String groupName, String serviceName, int pageNo, int pageSize) throws NacosException;


Page<SubscriberInfo> getSubscribers(String namespaceId, String groupName, String serviceName, int pageNo, int pageSize, boolean aggregation) throws NacosException;


Page<SubscriberInfo> getSubscribers(Service service, int pageNo, int pageSize, boolean aggregation) throws NacosException;

请求参数

参数名参数类型描述
serviceName(Service.name)string服务的名称
groupName(Service.groupName)string服务的分组名称
namespaceId(Service.namespaceId)string服务所属的命名空间ID
pageNoint分页页码，默认为1。
pageSizeint分页每页大小，默认为100。
aggregationboolean是否聚合查询，默认为false，为false时仅查询请求所在节点的订阅者列表，为true时查询整个集群中此配置的订阅者列表。

返回参数

参数类型描述
Page<SubscriberInfo>订阅者列表的分页结果

请求示例

try {
    // 以下请求均获取服务`maintain.client.test`的所有订阅者列表(最多前100个)。
    Page<SubscriberInfo> result = namingMaintainerService.getSubscribers("maintain.client.test");
    result = namingMaintainerService.getSubscribers(Constants.DEFAULT_GROUP, "maintain.client.test");
    result = namingMaintainerService.getSubscribers(Constants.DEFAULT_NAMESPACE_ID, Constants.DEFAULT_GROUP, "maintain.client.test");
    result = namingMaintainerService.getSubscribers(Constants.DEFAULT_NAMESPACE_ID, Constants.DEFAULT_GROUP, "maintain.client.test", 1, 100);
    result = namingMaintainerService.getSubscribers(Constants.DEFAULT_NAMESPACE_ID, Constants.DEFAULT_GROUP, "maintain.client.test", 1, 100, false);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.8. 查询支持的服务实例选择器列表

描述

通过此接口获取支持的服务实例选择器列表，仅返回实例选择器的名称列表。

List<String> listSelectorTypes() throws NacosException;

请求参数

无

返回参数

参数类型描述
List<String>实例选择器的名称列表

请求示例

try {
    List<String> result = namingMaintainerService.listSelectorTypes();
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.9. 注册实例

描述

通过该接口注册一个服务的实例，默认注册为持久化实例。

String registerInstance(String serviceName, String ip, int port) throws NacosException;


String registerInstance(String groupName, String serviceName, String ip, int port) throws NacosException;


String registerInstance(String namespaceId, String groupName, String serviceName, String ip, int port) throws NacosException;


String registerInstance(String serviceName, String ip, int port, String clusterName) throws NacosException;


String registerInstance(String groupName, String serviceName, String ip, int port, String clusterName) throws NacosException;


String registerInstance(String namespaceId, String groupName, String serviceName, String ip, int port, String clusterName) throws NacosException;


String registerInstance(String serviceName, Instance instance) throws NacosException;


String registerInstance(String groupName, String serviceName, Instance instance) throws NacosException;


String registerInstance(String namespaceId, String groupName, String serviceName, Instance instance);


String registerInstance(Service service, Instance instance) throws NacosException;

请求参数

参数名参数类型描述
serviceName(Service.name)string服务的名称
groupName(Service.groupName)string服务的分组名称
namespaceId(Service.namespaceId)string服务所属的命名空间ID
clusterName(Instance.clusterName)string实例所属的逻辑集群名称
ip(Instance.ip)string实例的IP地址，支持域名
port(Instance.port)int实例的端口信息，取值0~65535
Instance.ephemeralboolean实例的持久化属性
Instance.weightdouble实例的权重
Instance.healthyboolean实例的健康状态
Instance.enabledboolean实例的上下线状态
Instance.instanceIdstring实例的ID
Instance.metadataMap<String,String>实例的元数据信息

返回参数

参数类型描述
String实例的注册结果描述

请求示例

try {
    // 以下请求均给服务`maintain.client.test`注册一个实例，实例的ip为`127.0.0.1`，端口为`8080`。
    String result = namingMaintainerService.registerInstance("maintain.client.test", "127.0.0.1", 8080);
    result = namingMaintainerService.registerInstance(Constants.DEFAULT_GROUP, "maintain.client.test", "127.0.0.1", 8080);
    result = namingMaintainerService.registerInstance(Constants.DEFAULT_NAMESPACE_ID, Constants.DEFAULT_GROUP, "maintain.client.test", "127.0.0.1", 8080);
    result = namingMaintainerService.registerInstance(Constants.DEFAULT_NAMESPACE_ID, Constants.DEFAULT_GROUP, "maintain.client.test", "127.0.0.1", 8080);
    result = namingMaintainerService.registerInstance("maintain.client.test", "127.0.0.1", 8080, Constants.DEFAULT_CLUSTER_NAME);
    result = namingMaintainerService.registerInstance(Constants.DEFAULT_GROUP,"maintain.client.test", "127.0.0.1", 8080, Constants.DEFAULT_CLUSTER_NAME);
    result = namingMaintainerService.registerInstance(Constants.DEFAULT_NAMESPACE_ID, Constants.DEFAULT_GROUP,"maintain.client.test", "127.0.0.1", 8080, Constants.DEFAULT_CLUSTER_NAME);
    Instance instance = new Instance();
    instance.setIp("127.0.0.1");
    instance.setPort(8080);
    instance.setEphemeral(false);
    result = namingMaintainerService.registerInstance("maintain.client.test", instance);
    result = namingMaintainerService.registerInstance(Constants.DEFAULT_GROUP,"maintain.client.test", instance);
    result = namingMaintainerService.registerInstance(Constants.DEFAULT_NAMESPACE_ID, Constants.DEFAULT_GROUP, "maintain.client.test", instance);
    Service service = new Service();
    service.setNamespaceId(Constants.DEFAULT_NAMESPACE_ID);
    service.setGroupName(Constants.DEFAULT_GROUP);
    service.setName("maintain.client.test");
    result = namingMaintainerService.registerInstance(service, instance);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.10. 注销实例

描述

通过该接口注销一个服务的实例。

String deregisterInstance(String serviceName, String ip, int port) throws NacosException;


String deregisterInstance(String groupName, String serviceName, String ip, int port) throws NacosException;


String deregisterInstance(String namespaceId, String groupName, String serviceName, String ip, int port) throws NacosException;


String deregisterInstance(String serviceName, String ip, int port, String clusterName) throws NacosException;


String deregisterInstance(String groupName, String serviceName, String ip, int port, String clusterName) throws NacosException;


String deregisterInstance(String namespaceId, String groupName, String serviceName, String ip, int port, String clusterName) throws NacosException;


String deregisterInstance(String serviceName, Instance instance) throws NacosException;


String deregisterInstance(String groupName, String serviceName, Instance instance) throws NacosException;


String deregisterInstance(String namespaceId, String groupName, String serviceName, Instance instance) throws NacosException;


String deregisterInstance(Service service, Instance instance) throws NacosException;

请求参数

参数名参数类型描述
serviceName(Service.name)string服务的名称
groupName(Service.groupName)string服务的分组名称
namespaceId(Service.namespaceId)string服务所属的命名空间ID
clusterName(Instance.clusterName)string实例所属的逻辑集群名称
ip(Instance.ip)string实例的IP地址，支持域名
port(Instance.port)int实例的端口信息，取值0~65535
Instance.ephemeralboolean实例的持久化属性

返回参数

参数类型描述
String实例的注销结果描述

请求示例

try {
    // 以下请求均给服务`maintain.client.test`注销一个实例，实例的ip为`127.0.0.1`，端口为`8080`。
    String result = namingMaintainerService.deregisterInstance("maintain.client.test", "127.0.0.1", 8080);
    result = namingMaintainerService.deregisterInstance(Constants.DEFAULT_GROUP, "maintain.client.test", "127.0.0.1", 8080);
    result = namingMaintainerService.deregisterInstance(Constants.DEFAULT_NAMESPACE_ID, Constants.DEFAULT_GROUP, "maintain.client.test", "127.0.0.1", 8080);
    result = namingMaintainerService.deregisterInstance("maintain.client.test", "127.0.0.1", 8080, Constants.DEFAULT_CLUSTER_NAME);
    result = namingMaintainerService.deregisterInstance(Constants.DEFAULT_GROUP,"maintain.client.test", "127.0.0.1", 8080, Constants.DEFAULT_CLUSTER_NAME);
    result = namingMaintainerService.deregisterInstance(Constants.DEFAULT_NAMESPACE_ID, Constants.DEFAULT_GROUP,"maintain.client.test", "127.0.0.1", 8080, Constants.DEFAULT_CLUSTER_NAME);
    Instance instance = new Instance();
    instance.setIp("127.0.0.1");
    instance.setPort(8080);
    instance.setEphemeral(false);
    result = namingMaintainerService.deregisterInstance("maintain.client.test", instance);
    result = namingMaintainerService.deregisterInstance(Constants.DEFAULT_GROUP,"maintain.client.test", instance);
    result = namingMaintainerService.deregisterInstance(Constants.DEFAULT_NAMESPACE_ID, Constants.DEFAULT_GROUP, "maintain.client.test", instance);
    Service service = new Service();
    service.setNamespaceId(Constants.DEFAULT_NAMESPACE_ID);
    service.setGroupName(Constants.DEFAULT_GROUP);
    service.setName("maintain.client.test");
    result = namingMaintainerService.deregisterInstance(service, instance);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.11. 更新实例

描述

通过该接口注销一个服务实例的元数据信息，但实例的所属服务，IP地址，端口，逻辑集群无法修改。

String updateInstance(String serviceName, Instance instance) throws NacosException;


String updateInstance(String groupName, String serviceName, Instance instance) throws NacosException;


String updateInstance(String namespaceId, String groupName, String serviceName, Instance instance) throws NacosException;


String updateInstance(Service service, Instance instance) throws NacosException;

请求参数

参数名参数类型描述
serviceName(Service.name)string服务的名称
groupName(Service.groupName)string服务的分组名称
namespaceId(Service.namespaceId)string服务所属的命名空间ID
Instance.clusterNamestring实例所属的逻辑集群名称
Instance.ipstring实例的IP地址，支持域名
Instance.portint实例的端口信息，取值0~65535
Instance.ephemeralboolean实例的持久化属性
Instance.weightdouble实例的权重
Instance.healthyboolean实例的健康状态
Instance.enabledboolean实例的上下线状态
Instance.instanceIdstring实例的ID
Instance.metadataMap<String,String>实例的元数据信息

返回参数

参数类型描述
String实例的更新结果描述

请求示例

try {
    Instance instance = new Instance();
    instance.setIp("127.0.0.1");
    instance.setPort(8080);
    instance.setEphemeral(false);
    instance.setEnabled(false);
    // 以下请求均给更新服务`maintain.client.test`下的一个实例，实例的ip为`127.0.0.1`，端口为`8080`， 将实例的`enabled`修改为`false`。
    String result = namingMaintainerService.updateInstance("maintain.client.test", instance);
    result = namingMaintainerService.updateInstance(Constants.DEFAULT_GROUP,"maintain.client.test", instance);
    result = namingMaintainerService.updateInstance(Constants.DEFAULT_NAMESPACE_ID, Constants.DEFAULT_GROUP, "maintain.client.test", instance);
    Service service = new Service();
    service.setNamespaceId(Constants.DEFAULT_NAMESPACE_ID);
    service.setGroupName(Constants.DEFAULT_GROUP);
    service.setName("maintain.client.test");
    result = namingMaintainerService.updateInstance(service, instance);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.12. 批量更新实例元数据

描述

批量对指定服务下部分或全部实例更新元数据。

InstanceMetadataBatchResult batchUpdateInstanceMetadata(Service service, List<Instance> instances, Map<String, String> newMetadata) throws NacosException;

请求参数

参数名参数类型描述
Service.namestring服务的名称
Service.groupNamestring服务的分组名称
Service.namespaceIdstring服务所属的命名空间ID
instancesList<Instance>需要更新元数据的实例列表，仅需要传入ip,port,clusterName
newMetadataMap<String,String>新的元数据信息

返回参数

参数类型描述
InstanceMetadataBatchResult实例元数据更新的结果

其中InstanceMetadataBatchResult中的内容为：

参数名参数类型描述
updatedList<String>更新成功的实例id

请求示例

try {
    Service service = new Service();
    service.setNamespaceId(Constants.DEFAULT_NAMESPACE_ID);
    service.setGroupName(Constants.DEFAULT_GROUP);
    service.setName("maintain.client.test");
    Instance instance = new Instance();
    instance.setIp("127.0.0.1");
    instance.setPort(8080);
    Map<String, String> newMetadata = Collections.singletonMap("testK", "testV");
    InstanceMetadataBatchResult result = namingMaintainerService.batchUpdateInstanceMetadata(service, Collections.singletonList(instance), newMetadata);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.13. 批量移除实例元数据

描述

批量对指定服务下部分或全部实例移除元数据。

InstanceMetadataBatchResult batchDeleteInstanceMetadata(Service service, List<Instance> instances, Map<String, String> newMetadata) throws NacosException;

请求参数

参数名参数类型描述
Service.namestring服务的名称
Service.groupNamestring服务的分组名称
Service.namespaceIdstring服务所属的命名空间ID
instancesList<Instance>需要更新元数据的实例列表，仅需要传入ip,port,clusterName
newMetadataMap<String,String>需要移除的元数据信息

返回参数

参数类型描述
InstanceMetadataBatchResult实例元数据更新的结果

其中InstanceMetadataBatchResult中的内容为：

参数名参数类型描述
updatedList<String>移除成功的实例id

请求示例

try {
    Service service = new Service();
    service.setNamespaceId(Constants.DEFAULT_NAMESPACE_ID);
    service.setGroupName(Constants.DEFAULT_GROUP);
    service.setName("maintain.client.test");
    Instance instance = new Instance();
    instance.setIp("127.0.0.1");
    instance.setPort(8080);
    Map<String, String> newMetadata = Collections.singletonMap("testK", "testV");
    InstanceMetadataBatchResult result = namingMaintainerService.batchDeleteInstanceMetadata(service, Collections.singletonList(instance), newMetadata);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.14. 更新实例的部分元数据

描述

更新实例的部分元数据。相比更新实例API，仅会更新有传入内容的元数据，若实例元数据中的key不再接口传入的参数中时，则不进行更新。

例如当前元数据为k1=v1,k2=v2，接口传入k2=v3，则元数据变为k1=v1,k2=v3,而不是k2=v3。

SDK 同时发送 Instance 中的 weight 和 enabled，这两个字段也会被更新。仅修改元数据时，先查询当前实例并保留这些属性，再设置需要合并的元数据，避免新建 Instance 的默认值覆盖现有值。

String partialUpdateInstance(Service service, Instance instance) throws NacosException;

请求参数

参数名参数类型描述
Service.namestring服务的名称
Service.groupNamestring服务的分组名称
Service.namespaceIdstring服务所属的命名空间ID
Instance.clusterNamestring实例所属的逻辑集群名称
Instance.ipstring实例的IP地址，支持域名
Instance.portint实例的端口信息，取值0~65535
Instance.ephemeralboolean实例的持久化属性
Instance.weightdouble实例的权重
Instance.enabledboolean实例的上下线状态
Instance.metadataMap<String,String>实例的元数据信息

返回参数

参数类型描述
String实例的更新结果描述

请求示例

try {
    Service service = new Service();
    service.setNamespaceId(Constants.DEFAULT_NAMESPACE_ID);
    service.setGroupName(Constants.DEFAULT_GROUP);
    service.setName("maintain.client.test");
    Instance identity = new Instance();
    identity.setIp("127.0.0.1");
    identity.setPort(8080);
    identity.setClusterName(Constants.DEFAULT_CLUSTER_NAME);
    // Preserve the current weight and enabled state.
    Instance instance = namingMaintainerService.getInstanceDetail(service, identity);
    instance.setMetadata(Collections.singletonMap("k2", "v3"));
    String result = namingMaintainerService.partialUpdateInstance(service, instance);
    System.out.println(result);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.15. 查询服务实例列表

描述

查询指定服务下满足条件的所有实例列表。

List<Instance> listInstances(String serviceName, String clusterName, boolean healthyOnly) throws NacosException;


List<Instance> listInstances(String groupName, String serviceName, String clusterName, boolean healthyOnly) throws NacosException;


List<Instance> listInstances(String namespaceId, String groupName, String serviceName, String clusterName, boolean healthyOnly) throws NacosException;


List<Instance> listInstances(Service service, String clusterName, boolean healthyOnly) throws NacosException;

请求参数

参数名参数类型描述
serviceName(Service.name)string服务的名称
groupName(Service.groupName)string服务的分组名称
namespaceId(Service.namespaceId)string服务所属的命名空间ID
clusterNamestring实例所属的逻辑集群名称，为空时返回所有逻辑集群的实例，需要查询多个逻辑集群是，使用逗号,分割
healthyOnlyboolean是否仅返回健康的实例

返回参数

参数类型描述
List<Instance>实例信息列表

请求示例

try {
    List<Instance> result = namingMaintainerService.listInstances("maintain.client.test", "", false);
    result = namingMaintainerService.listInstances(Constants.DEFAULT_GROUP, "maintain.client.test", "", false);
    result = namingMaintainerService.listInstances(Constants.DEFAULT_NAMESPACE_ID, Constants.DEFAULT_GROUP, "maintain.client.test", "", false);
    Service service = new Service();
    service.setNamespaceId(Constants.DEFAULT_NAMESPACE_ID);
    service.setGroupName(Constants.DEFAULT_GROUP);
    service.setName("maintain.client.test");
    result = namingMaintainerService.listInstances(service, "", false);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.16. 查询指定服务实例的详情

描述

查询指定服务实例的详情，主要用于查询该实例的元数据及其他附属信息（如权重等）。

Instance getInstanceDetail(String serviceName, String ip, int port) throws NacosException;


Instance getInstanceDetail(String groupName, String serviceName, String ip, int port) throws NacosException;


Instance getInstanceDetail(String namespaceId, String groupName, String serviceName, String ip, int port) throws NacosException;


Instance getInstanceDetail(String serviceName, String ip, int port, String clusterName) throws NacosException;


Instance getInstanceDetail(String groupName, String serviceName, String ip, int port, String clusterName) throws NacosException;


Instance getInstanceDetail(String namespaceId, String groupName, String serviceName, String ip, int port, String clusterName) throws NacosException;


Instance getInstanceDetail(Service service, Instance instance) throws NacosException;

请求参数

参数名参数类型描述
serviceName(Service.name)string服务的名称
groupName(Service.groupName)string服务的分组名称
namespaceId(Service.namespaceId)string服务所属的命名空间ID
clusterName(Instance.clusterName)string实例所属的逻辑集群名称
ip(Instance.ip)string实例的IP地址，支持域名
port(Instance.port)int实例的端口信息，取值0~65535

返回参数

参数类型描述
Instance实例详情，包含 IP、端口、集群、权重、健康状态、启用状态和元数据。

请求示例

try {
    Instance result = namingMaintainerService.getInstanceDetail("maintain.client.test", "127.0.0.1", 8080);
    result = namingMaintainerService.getInstanceDetail(Constants.DEFAULT_GROUP, "maintain.client.test", "127.0.0.1", 8080);
    result = namingMaintainerService.getInstanceDetail(Constants.DEFAULT_NAMESPACE_ID, Constants.DEFAULT_GROUP, "maintain.client.test", "127.0.0.1", 8080);
    result = namingMaintainerService.getInstanceDetail("maintain.client.test", "127.0.0.1", 8080, Constants.DEFAULT_CLUSTER_NAME);
    result = namingMaintainerService.getInstanceDetail(Constants.DEFAULT_GROUP,"maintain.client.test", "127.0.0.1", 8080, Constants.DEFAULT_CLUSTER_NAME);
    result = namingMaintainerService.getInstanceDetail(Constants.DEFAULT_NAMESPACE_ID, Constants.DEFAULT_GROUP,"maintain.client.test", "127.0.0.1", 8080, Constants.DEFAULT_CLUSTER_NAME);
    Service service = new Service();
    service.setNamespaceId(Constants.DEFAULT_NAMESPACE_ID);
    service.setGroupName(Constants.DEFAULT_GROUP);
    service.setName("maintain.client.test");
    Instance instance = new Instance();
    instance.setIp("127.0.0.1");
    instance.setPort(8080);
    instance.setClusterName(Constants.DEFAULT_CLUSTER_NAME);
    result = namingMaintainerService.getInstanceDetail(service, instance);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.17. 查询注册中心相关的统计信息

描述

查询注册中心相关的统计信息，主要用于查询注册中心中可用状态，实例个数，服务个数等。

MetricsInfo getMetrics(boolean onlyStatus) throws NacosException;

请求参数

参数名参数类型描述
onlyStatusboolean是否仅查询可用状态。

返回参数

参数类型描述
MetricsInfo注册中心的统计信息

其中MetricsInfo中内容如下：

参数名参数类型描述
statusstring注册中心的可用状态，如UP。
serviceCountint服务总个数
instanceCountint服务实例总个数
subscribeCountint服务订阅者总个数
clientCountint客户端连接总个数
connectionBasedClientCountint基于长连接的客户端总个数，对应SDK版本大于2.0以上的客户端数量
ephemeralIpPortClientCountint基于IP端口的临时客户端总个数，对应SDK版本小于2.0的版本客户端数量，及包括通过http openAPI及运维API注册的临时客户端。
persistentIpPortClientCountint基于IP端口的持久化客户端总个数，对应持久化实例的客户端数量。
responsibleClientCountint由此Nacos Server节点负责维护的客户端总个数， 包括直接长连接在此节点的connectionBasedClientCount以及Distro协议认为应该由此节点负责的ephemeralIpPortClientCount和persistentIpPortClientCount。

请求示例

try {
    MetricsInfo metricsInfo = namingMaintainerService.getMetrics(false);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.18. 设置注册中心的日志级别

描述

设置注册中心相关模块日志的日志级别。

String setLogLevel(String logName, String logLevel) throws NacosException;

请求参数

参数名参数类型描述
:---------:-------:----------------------------------------
logNamestring日志模块名称，如naming-server, naming-event等
logLevelstring日志级别（如INFO、DEBUG）

返回参数

参数类型描述
String设置日志级别的结果信息

请求示例

try {
    String result = namingMaintainerService.setLogLevel("naming-server", "DEBUG");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.19. 更新持久化实例的健康状态。

描述

更新持久化实例的健康状态。

String updateInstanceHealthStatus(Service service, Instance instance) throws NacosException;

请求参数

参数名参数类型描述
serviceName(Service.name)string服务的名称
groupName(Service.groupName)string服务的分组名称
namespaceId(Service.namespaceId)string服务所属的命名空间ID
clusterName(Instance.clusterName)string实例所属的逻辑集群名称
ip(Instance.ip)string实例的IP地址，支持域名
port(Instance.port)int实例的端口信息，取值0~65535
healthy(Instance.healthy)boolean实例的目标健康状态

返回参数

参数类型描述
String更新健康状态结果描述

请求示例

try {
    // 更新`maintain.client.test`下的实例`127.0.0.1:8080`的健康状态为false.
    Service service = new Service();
    service.setNamespaceId(Constants.DEFAULT_NAMESPACE_ID);
    service.setGroupName(Constants.DEFAULT_GROUP);
    service.setName("maintain.client.test");
    Instance instance = new Instance();
    instance.setIp("127.0.0.1");
    instance.setPort(8080);
    instance.setClusterName(Constants.DEFAULT_CLUSTER_NAME);
    instance.setEphemeral(false);
    instance.setHealthy(false);
    String result = namingMaintainerService.updateInstanceHealthStatus(service, instance);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.20. 查询支持的健康检查类型

描述

通过此接口查询支持的健康检查类型。

Map<String, AbstractHealthChecker> getHealthCheckers() throws NacosException;

请求参数

无

返回参数

参数类型描述
Map<String, AbstractHealthChecker>支持的健康检查方式的Map，key为类型，value为具体的健康检查器的对应配置内容

请求示例

try {
    Map<String, AbstractHealthChecker> result = namingMaintainerService.getHealthCheckers();
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.21. 更新逻辑集群的元数据

描述

更新指定服务下指定逻辑集群的元数据。

String updateCluster(Service service, ClusterInfo cluster) throws NacosException;

请求参数

参数名参数类型描述
Service.namestring服务的名称
Service.groupNamestring服务的分组名称
Service.namespaceIdstring服务所属的命名空间ID
ClusterInfo.clusterNamestring逻辑集群的名称
ClusterInfo.healthCheckerAbstractHealthChecker逻辑集群的健康检查器对象，例如 new AbstractHealthChecker.None()；可选类型参见查询支持的健康检查类型。
ClusterInfo.healthyCheckPortint健康检查的端口。
ClusterInfo.useInstancePortForCheckboolean是否使用实例所注册的端口进行健康检查，为 true 时忽略 healthyCheckPort 设置的端口。
ClusterInfo.metadataMap<String,String>实例所属的元数据信息

返回参数

参数类型描述
String逻辑集群更新的结果描述。

请求示例

try {
    Service service = new Service();
    service.setNamespaceId(Constants.DEFAULT_NAMESPACE_ID);
    service.setGroupName(Constants.DEFAULT_GROUP);
    service.setName("maintain.client.test");
    ClusterInfo clusterInfo = new ClusterInfo();
    clusterInfo.setClusterName(Constants.DEFAULT_CLUSTER_NAME);
    clusterInfo.setHealthChecker(new AbstractHealthChecker.None());
    clusterInfo.setUseInstancePortForCheck(true);
    clusterInfo.setMetadata(Collections.singletonMap("testK", "testV"));
    String result = namingMaintainerService.updateCluster(service, clusterInfo);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.22. 查询服务客户端列表

描述

获取注册中心中所有注册或订阅服务的客户端的列表。

List<String> getClientList() throws NacosException;

请求参数

无

返回参数

参数类型描述
List<String>客户端的clientId列表

请求示例

try {
    List<String> result = namingMaintainerService.getClientList();
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.23. 查询服务客户端详情

描述

查询服务客户端的详细信息。不同版本的客户端信息，返回的内容可能有所不同。

ClientSummaryInfo getClientDetail(String clientId) throws NacosException;

请求参数

参数名参数类型描述
clientIdstring客户端的clientId，可通过日志或查询服务客户端列表获得

返回参数

参数类型描述
ClientSummaryInfo客户端总结信息

其中ClientSummaryInfo中的内容如下：

参数名参数类型描述
clientIdstring客户端id
ephemeralboolean是否为持久化服务的客户端
lastUpdatedTimelong客户端最后一次进行更新（注册或注销）的时间戳
clientTypestring客户端的类型，ipPort或connection，分别对应1.X客户端或HTTP openAPI访问 和 2.X及以上的客户端或GRPC openAPI访问。
connectTypestring当clientType为connection时，该字段表示客户端的连接类型，当前为grpc。
appNamestring客户端的应用名称，需要在客户端连接时添加在连接元数据中，默认为unknown。
versionstring客户端的版本，如Nacos-Java-Client:v3.0.0
clientIpstring客户端的IP地址， 由于存在代理注册（如Nacos-Sync）的场景，此IP地址可能与此客户端所注册的服务实例的IP地址不同。
clientPortint客户端的Port地址， 表示此连接的remote port。

请求示例

try {
    ClientSummaryInfo result = namingMaintainerService.getClientDetail("127.0.0.1:8080#true");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.24. 查询指定服务客户端所注册的服务列表

描述

查询指定服务客户端所注册的服务列表。

List<ClientServiceInfo> getPublishedServiceList(String clientId) throws NacosException;

请求参数

参数名参数类型描述
clientIdstring客户端的clientId，可通过日志或查询服务客户端列表获得

返回参数

参数类型描述
List<ClientServiceInfo>客户端所注册的服务列表信息

其中ClientServiceInfo的内容如下：

参数名参数类型描述
namespaceIdstring服务所属的namespaceId
groupNamestring服务的分组名称
serviceNamestring服务的名称
publisherInfoClientPublisherInfo客户端所注册的服务实例信息
publisherInfo.ipstring实例的IP
publisherInfo.portstring实例的端口
publisherInfo.clusterNamestring实例的逻辑集群名称

请求示例

try {
    List<ClientServiceInfo> result = namingMaintainerService.getPublishedServiceList("127.0.0.1:8080#true");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.25. 查询指定服务客户端所订阅的服务列表

描述

查询指定服务客户端所订阅的服务列表。

List<ClientServiceInfo> getSubscribeServiceList(String clientId) throws NacosException;

请求参数

参数名参数类型描述
clientIdstring客户端的clientId，可通过日志或查询服务客户端列表获得

返回参数

参数类型描述
List<ClientServiceInfo>客户端所订阅的服务列表信息

其中ClientServiceInfo的内容如下：

参数名参数类型描述
namespaceIdstring服务所属的namespaceId
groupNamestring服务的分组名称
serviceNamestring服务的名称
subscriberInfoClientSubscriberInfo客户端的订阅者信息
subscriberInfo.appNamestring订阅者所属的应用名称，默认unknown
subscriberInfo.agentstring订阅者的客户端版本
subscriberInfo.addressstring订阅者的地址信息格式为IP:PORT

请求示例

try {
    List<ClientServiceInfo> result = namingMaintainerService.getSubscribeServiceList("127.0.0.1:8080#true");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.26. 查询注册了指定服务的服务客户端列表

描述

查询哪些客户端注册了指定的服务。

List<ClientPublisherInfo> getPublishedClientList(String namespaceId, String groupName, String serviceName, String ip, Integer port) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring服务所属的namespaceId
groupNamestring服务的分组名称
serviceNamestring服务的名称
ipstring服务实例的ip，为空时表示匹配所有服务实例
portint服务实例的端口，为空时表示匹配所有服务实例

返回参数

参数类型描述
List<ClientPublisherInfo>注册服务实例的客户端信息

其中ClientPublisherInfo的内容如下：

参数名参数类型描述
clientIdstring注册服务的客户端ID
ipstring注册的实例的IP
portstring注册的实例的端口
clusterNamestring注册的实例的逻辑集群名称

请求示例

try {
    List<ClientPublisherInfo> result = namingMaintainerService.getPublishedClientList(Constants.DEFAULT_NAMESPACE_ID, Constants.DEFAULT_GROUP, "maintain.client.test", "", "");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

4.27. 查询订阅了指定服务的服务客户端列表

描述

查询哪些客户端订阅了指定的服务。

List<ClientSubscriberInfo> getSubscribeClientList(String namespaceId, String groupName, String serviceName, String ip, Integer port) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring服务所属的namespaceId
groupNamestring服务的分组名称
serviceNamestring服务的名称
ipstring服务订阅者的ip，为空时表示匹配所有订阅者
portint服务订阅者的端口，为空时表示匹配所有订阅者

返回参数

参数类型描述
List<ClientSubscriberInfo>订阅服务的客户端信息

其中ClientSubscriberInfo的内容如下：

参数名参数类型描述
clientIdstring订阅服务的客户端ID
appNamestring订阅者所属的应用名称，默认unknown
agentstring订阅者的客户端版本
addressstring订阅者的地址信息格式为IP:PORT

请求示例

try {
    List<ClientSubscriberInfo> result = namingMaintainerService.getSubscribeClientList(Constants.DEFAULT_NAMESPACE_ID, Constants.DEFAULT_GROUP, "maintain.client.test", "", "");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

5. 其他Nacos核心运维API

Nacos核心的运维API可以通过NacosNamingMaintainerService或NacosConfigMaintainerService进行调用。

5.1. 查询Nacos Server的状态信息

描述

查询Nacos Server的状态信息，状态信息包括版本号, 运行模式, 开启鉴权, 运行的模块等信息

Map<String, String> getServerState() throws NacosException;

请求参数

无

返回参数

参数类型描述
Map<String, String>Nacos Server 的状态信息

请求示例

try {
    Map<String,String> result = namingMaintainerService.getServerState();
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

5.2. 获取Nacos Server的存活状态

描述

获取Nacos Server的存活状态

Boolean liveness() throws NacosException;

请求参数

无

返回参数

参数类型描述
booleantrue代表存活，false代表存在问题

请求示例

try {
    boolean result = namingMaintainerService.liveness();
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

5.3. 获取Nacos Server的就绪状态

描述

获取Nacos Server的就绪状态

Boolean readiness() throws NacosException;

请求参数

无

返回参数

参数类型描述
booleantrue代表就绪，false代表未就绪

请求示例

try {
    boolean result = namingMaintainerService.readiness();
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

5.4. Nacos Raft操作

描述

通过此接口， 可以对Nacos Server中的Raft协议进行一定的运维操作，如重新选主，进行快照等。

String raftOps(String command, String value, String groupId) throws NacosException;

请求参数

参数名参数类型描述
commandstringRaft 操作命令，见com.alibaba.nacos.core.distributed.raft.utils.JRaftOps
valuestringRaft 操作的目标值
groupIdstring操作的目标Raft Group, 为空时会对所有的Raft Group进行操作。

返回参数

参数类型描述
String操作结果

请求示例

try {
    String result = namingMaintainerService.raftOps("doSnapshot", "172.0.0.1:7848", "");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

5.5. 查询Nacos Server支持的分布式ID生成器列表

描述

查询Nacos Server支持的分布式ID生成器列表。如雪花Id生成器

List<IdGeneratorInfo> getIdGenerators() throws NacosException;

请求参数

无

返回参数

参数类型描述
List<IdGeneratorInfo>Id生成器信息列表

请求示例

try {
    List<IdGeneratorInfo> result = namingMaintainerService.getIdGenerators();
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

5.6. 更新核心模块日志级别

描述

更新核心模块日志级别

void updateLogLevel(String logName, String logLevel) throws NacosException;

请求参数

参数名参数类型描述
logNamestring日志模块名称，如core-auth等
logLevelstring日志级别（如INFO、DEBUG）

返回参数

无

请求示例

try {
    namingMaintainerService.updateLogLevel("core-auth", "INFO");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

5.7. 查询Nacos Server节点列表

描述

查询Nacos Server节点列表。

Collection<NacosMember> listClusterNodes(String address, String state) throws NacosException;

请求参数

参数名参数类型描述
addressstringServer节点的地址，默认为""，为空时返回所有节点，不为空时返回满足前缀匹配的节点
statestringServer节点的状态，如UP，默认为""，为空时返回所有节点，不为空时返回满足此状态的节点

返回参数

参数类型描述
Collection<NacosMember>Nacos Server节点列表

其中NacosMember的字段说明如下：

参数名参数类型描述
ipstringServer节点的IP
portintServer节点的主端口
stateNodeStateServer节点的运行状态
extendInfoMap<String, Object>Server节点的拓展数据，如Raft的相关信息

请求示例

try {
    Collection<NacosMember> result = namingMaintainerService.listClusterNodes("", "");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

5.8. 更新Nacos Server的地址发现模式

描述

Nacos Server的地址发现模式是控制Nacos Server发现同集群的其他节点地址的方式，用于在Nacos Server启动和运行中组建Nacos集群。

通过此接口可以动态的修改Nacos Server的地址发现模式，实现使用不同的方式进行Nacos集群的组建。

Boolean updateLookupMode(String type) throws NacosException;

请求参数

参数名参数类型描述
typestring地址发现模式的类型，默认支持file和address-server

返回参数

参数类型描述
Booleantrue代表更新成功

请求示例

try {
    // The server must already have the member addresses configured for file mode.
    Boolean result = namingMaintainerService.updateLookupMode("file");
    System.out.println(result);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

5.9. 查询当前Nacos Server节点的长连接列表

描述

查询连接到当前Nacos Server节点的长连接列表。

Map<String, ConnectionInfo> getCurrentClients() throws NacosException;

请求参数

无

返回参数

参数类型描述
Map<String, ConnectionInfo>长连接列表，key为连接ID，value为连接的详细信息

请求示例

try {
    Map<String, ConnectionInfo> result = namingMaintainerService.getCurrentClients();
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

5.10. 均匀Nacos Server节点的长连接负载

描述

Nacos Server节点的长连接负载是控制Nacos Server节点的长连接负载的方式，用于在Nacos Server节点之间均匀的负载长连接。

String reloadConnectionCount(Integer count, String redirectAddress) throws NacosException;

请求参数

参数名参数类型描述
countint预期保留的长连接个数
redirectAddressstring预期重定向地址，默认为空，为空为随机进行负载

返回参数

参数类型描述
String均匀连接的结果

请求示例

try {
    String result = namingMaintainerService.reloadConnectionCount(10, "");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

5.11. 自动均匀Nacos Server节点的长连接负载

描述

让Nacos Server根据长连接数量自动进行Server见的均匀负载。

String smartReloadCluster(String loaderFactorStr) throws NacosException;

请求参数

参数名参数类型描述
loaderFactorStrstring自动均匀负载时的方差比例，默认0.1f，代表自动均匀负载时，集群节点间最大的连接数和最小的连接数差异在10%以内

返回参数

参数类型描述
String均匀连接的结果

请求示例

try {
    String result = namingMaintainerService.smartReloadCluster("0.1f");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

5.12. 指定单个Nacos客户端连接进行重载

描述

指定单个Nacos客户端连接进行重载。

String reloadSingleClient(String connectionId, String redirectAddress) throws NacosException;

请求参数

参数名参数类型描述
connectionIdstring连接Id
redirectAddressstring预期重定向地址，默认为空，为空为随机进行负载

返回参数

参数类型描述
String均匀连接的结果

请求示例

try {
    String result = namingMaintainerService.reloadSingleClient("111111111_127.0.0.1_10000", "");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

5.13. 查询Nacos Server长连接负载统计信息

描述

查询Nacos Server长连接负载统计信息。

ServerLoaderMetrics getClusterLoaderMetrics() throws NacosException;

请求参数

无

返回参数

参数类型描述
ServerLoaderMetrics长连接负载统计信息

请求示例

try {
    ServerLoaderMetrics result = namingMaintainerService.getClusterLoaderMetrics();
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

5.14. 查询命名空间列表

描述

查询命名空间列表。

List<Namespace> getNamespaceList() throws NacosException;

请求参数

无

返回参数

参数类型描述
List<Namespace>命名空间列表

其中Namespace中的属性如下：

参数名参数类型描述
namespacestring命名空间id
namespaceShowNamestring命名空间的名字
namespaceDescstring命名空间的描述
quotaint命名空间下配置的个数配额（需要配合配置中心的容量管理使用，否则不实际生效），默认200
configCountint命名空间下配置的个数
typeint命名空间的类型，预留字段，目前均为1

请求示例

try {
    List<Namespace> result = namingMaintainerService.getNamespaceList();
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

5.15. 查询指定命名空间

描述

查询指定命名空间。

Namespace getNamespace(String namespaceId) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID

返回参数

参数类型描述
Namespace命名空间的详情

其中Namespace中的属性如下：

参数名参数类型描述
namespacestring命名空间id
namespaceShowNamestring命名空间的名字
namespaceDescstring命名空间的描述
quotaint命名空间下配置的个数配额（需要配合配置中心的容量管理使用，否则不实际生效），默认200
configCountint命名空间下配置的个数
typeint命名空间的类型，预留字段，目前均为1

请求示例

try {
    Namespace result = namingMaintainerService.getNamespace("public");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

5.16. 创建命名空间

描述

创建命名空间。

Boolean createNamespace(String namespaceName, String namespaceDesc) throws NacosException;


Boolean createNamespace(String namespaceId, String namespaceName, String namespaceDesc) throws NacosException;

请求参数

参数名参数类型描述
namespaceNamestring命名空间的名字
namespaceDescstring命名空间的描述
namespaceIdstring自定义的命名空间ID，默认为""，为空时将会由Nacos自动生成的UUID作为命名空间ID

返回参数

参数类型描述
boolean创建命名空间的结果

请求示例

try {
    boolean result = namingMaintainerService.createNamespace("test", "test");
    result = namingMaintainerService.createNamespace("test", "test", "test");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

5.17. 更新命名空间

描述

更新指定命名空间的名字或描述。

Boolean updateNamespace(String namespaceId, String namespaceName, String namespaceDesc) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring需要更新的命名空间ID。
namespaceNamestring修改后的命名空间名称。
namespaceDescstring修改后的命名空间描述。

返回参数

参数类型描述
boolean更新命名空间的结果

请求示例

try {
    boolean result = namingMaintainerService.updateNamespace("test", "testNamespaceName", "testNamespaceDesc");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

5.18. 删除命名空间

描述

删除指定命名空间。

Boolean deleteNamespace(String namespaceId) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring要删除的命名空间id

返回参数

参数类型描述
boolean删除命名空间的结果

请求示例

try {
    boolean result = namingMaintainerService.deleteNamespace("test");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

5.19. 检查命名空间是否存在

描述

检查命名空间是否存在。

Boolean checkNamespaceIdExist(String namespaceId) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring待检查的命名空间id

返回参数

参数类型描述
boolean命名空间的检查结果，true表示该命名空间id已存在

请求示例

try {
    boolean result = namingMaintainerService.checkNamespaceIdExist("test");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

5.20. 查询插件列表

描述

查询 Nacos 已加载的统一插件列表，可按插件类型过滤。返回身份使用 pluginType:pluginName，并包含状态、critical、executionMode 和 configurable 等元数据。

List<Map<String, Object>> listPlugins(String pluginType) throws NacosException;

请求参数

参数名参数类型描述
pluginTypestring插件类型过滤，如 auth、control；传 null 或空则返回全部。

返回参数

参数类型描述
List<Map<String, Object>>插件信息列表。

请求示例

try {
    List<Map<String, Object>> plugins = coreMaintainerService.listPlugins(null);
    List<Map<String, Object>> authPlugins = coreMaintainerService.listPlugins("auth");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

5.21. 查询插件详情

描述

根据插件类型和插件名称查询单个插件的详情，包括 definitions、脱敏后的有效配置，以及各项配置的 source/overridden 元数据。

Map<String, Object> getPluginDetail(String pluginType, String pluginName) throws NacosException;

请求参数

参数名参数类型描述
pluginTypestring插件类型。
pluginNamestring插件名称。

返回参数

参数类型描述
Map<String, Object>插件详情信息。

请求示例

try {
    Map<String, Object> detail = coreMaintainerService.getPluginDetail("auth", "ldap");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

5.22. 更新插件状态

描述

启用或禁用指定插件。EXCLUSIVE 选择、PRE_CONTEXT 实现和 active critical provider 不能被非法运行时修改；localOnly=true 只影响当前节点且优先于持久化状态。

void updatePluginStatus(String pluginType, String pluginName, boolean enabled) throws NacosException;


void updatePluginStatus(String pluginType, String pluginName, boolean enabled, boolean localOnly) throws NacosException;

请求参数

参数名参数类型描述
pluginTypestring插件类型。
pluginNamestring插件名称。
enabledboolean是否启用，true 启用，false 禁用。
localOnlyboolean是否仅应用到当前节点。

返回参数

无（void）。

请求示例

try {
    coreMaintainerService.updatePluginStatus("auth", "ldap", false);
    coreMaintainerService.updatePluginStatus("auth", "ldap", false, true);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

5.23. 更新插件配置

描述

替换指定插件目标来源的完整配置 map。只能运行时更新 effectMode=RUNTIME 的 definition；RESTART 项的新增、变更或删除会被拒绝。localOnly=true 写当前节点的高优先级 LOCAL_ONLY，否则写 RUNTIME_PERSISTED。

void updatePluginConfig(String pluginType, String pluginName, Map<String, String> config) throws NacosException;


void updatePluginConfig(String pluginType, String pluginName, Map<String, String> config, boolean localOnly) throws NacosException;

请求参数

参数名参数类型描述
pluginTypestring插件类型。
pluginNamestring插件名称。
configMap<String, String>以 definition item key 为键的完整目标来源 map。
localOnlyboolean是否仅应用到当前节点。

返回参数

无（void）。

请求示例

try {
    Map<String, String> config = new HashMap<>();
    config.put("connect-timeout", "6000");
    coreMaintainerService.updatePluginConfig("auth", "ldap", config);
    coreMaintainerService.updatePluginConfig("auth", "ldap", config, true);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

5.24. 查询插件可用性

描述

查询指定插件在集群各节点上的可用性。

Map<String, Boolean> getPluginAvailability(String pluginType, String pluginName) throws NacosException;

请求参数

参数名参数类型描述
pluginTypestring插件类型。
pluginNamestring插件名称。

返回参数

参数类型描述
Map<String, Boolean>节点地址到是否可用的映射。

请求示例

try {
    Map<String, Boolean> availability = coreMaintainerService.getPluginAvailability("auth", "ldap");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

6. MCP 服务

通过 aiMaintainerService.mcp() 获取 McpMaintainerService。从 3.3 开始，可以使用 McpServerDraftRequest 创建或更新草稿，再提交审核、发布，具体流程见 AI 资源生命周期管理。从旧版本升级的集群需先完成服务端升级，才能使用这些接口。

本章模型位于 com.alibaba.nacos.api.ai.model.mcp 包，ServerVersionDetail 位于其 registry 子包。新增接口通过命名空间和 MCP 服务名称指定资源，无需传入 mcpId。

旧 getMcpServerDetail、createLocalMcpServer、createRemoteMcpServer 及接受 serverSpec 等独立参数的创建、更新重载自 3.3 起已废弃，计划在 4.0 移除。旧创建、更新接口仍会直接发布版本。新接入请使用第 6.10 节查询版本，使用第 6.8、6.6 节的 McpServerDraftRequest 重载创建和更新草稿。

6.1. 获取MCP服务列表

描述

通过mcpName，精确获取MCP服务列表，若传入的mcpName为空，则返回所有MCP服务列表。

Page<McpServerBasicInfo> listMcpServer() throws NacosException;


Page<McpServerBasicInfo> listMcpServer(int pageNo, int pageSize) throws NacosException;


Page<McpServerBasicInfo> listMcpServer(String mcpName, int pageNo, int pageSize) throws NacosException;


Page<McpServerBasicInfo> listMcpServer(String namespaceId, String mcpName, int pageNo, int pageSize) throws NacosException;

请求参数

参数名参数类型描述
pageNointMCP服务列表的分页页码，默认为1。
pageSizeintMCP服务的分页大小，默认为100。
mcpNameStringMCP服务的准确名字，若传入的mcpName为空，则返回所有MCP服务列表。
namespaceIdStringMCP服务所属的命名空间id， 默认为public。

返回参数

参数类型描述
Page<McpServerBasicInfo>MCP服务列表的分页结果

请求示例

try {
    Page<McpServerBasicInfo> result = aiMaintainerService.listMcpServer();
    result = aiMaintainerService.listMcpServer(1, 100);
    result = aiMaintainerService.listMcpServer("", 1, 100);
    result = aiMaintainerService.listMcpServer("public", "", 1, 100);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

6.2. 搜索MCP服务列表

描述

通过mcpName，模糊搜索MCP服务列表，若传入的mcpName为空，则返回所有MCP服务列表。

Page<McpServerBasicInfo> searchMcpServer(String mcpName) throws NacosException;


Page<McpServerBasicInfo> searchMcpServer(String mcpName, int pageNo, int pageSize) throws NacosException;


Page<McpServerBasicInfo> searchMcpServer(String namespaceId, String mcpName, int pageNo, int pageSize) throws NacosException;

请求参数

参数名参数类型描述
pageNointMCP服务列表的分页页码，默认为1。
pageSizeintMCP服务的分页大小，默认为100。
mcpNameStringMCP服务的准确名字，若传入的mcpName为空，则返回所有MCP服务列表。
namespaceIdStringMCP服务所属的命名空间id， 默认为public。

返回参数

参数类型描述
Page<McpServerBasicInfo>MCP服务列表的分页结果

请求示例

try {
    Page<McpServerBasicInfo> result = aiMaintainerService.searchMcpServer("");
    result = aiMaintainerService.searchMcpServer("", 1, 100);
    result = aiMaintainerService.searchMcpServer("public", "", 1, 100);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

6.3. 获取MCP服务详情

描述

通过mcpName，获取详细的MCP服务信息。

McpServerDetailInfo getMcpServerDetail(String mcpName) throws NacosException;


McpServerDetailInfo getMcpServerDetail(String mcpName, String version) throws NacosException;


McpServerDetailInfo getMcpServerDetail(String namespaceId, String mcpName, String version) throws NacosException;


McpServerDetailInfo getMcpServerDetail(String namespaceId, String mcpName, String mcpId, String version) throws NacosException;

请求参数

参数名参数类型描述
mcpNameStringMCP服务的准确名字
versionStringMCP服务的版本号，不指定时默认返回最新版本。
namespaceIdStringMCP服务所属的命名空间id， 默认为public。
mcpIdStringMCP服务ID，不指定时可传 null。

返回参数

参数类型描述
McpServerDetailInfoMCP服务详情对象。

请求示例

try {
    McpServerDetailInfo result = aiMaintainerService.getMcpServerDetail("test");
    result = aiMaintainerService.getMcpServerDetail("test", "1.0.0");
    result = aiMaintainerService.getMcpServerDetail("public", "test", "1.0.0");
    result = aiMaintainerService.getMcpServerDetail("public", "test", null, "1.0.0");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

6.4. 创建Local(stdio)类型的MCP服务

描述

创建类型为Local(stdio)的MCP服务。

String createLocalMcpServer(String mcpName, String version) throws NacosException;


String createLocalMcpServer(String mcpName, String version, String description) throws NacosException;


String createLocalMcpServer(String mcpName, String version, String description, McpToolSpecification toolSpec) throws NacosException;


String createLocalMcpServer(String mcpName, String version, String description, Map<String, Object> localServerConfig, McpToolSpecification toolSpec) throws NacosException;


String createLocalMcpServer(String mcpName, McpServerBasicInfo serverSpec, McpToolSpecification toolSpec) throws NacosException;

请求参数

参数名参数类型描述
mcpNameString创建的MCP服务的名字
versionString创建的MCP服务的版本
descriptionStringMCP服务的描述
localServerConfigMap<String, Object>stdio类型的MCP服务配置信息，可参考此MCP服务的启动配置进行配置
toolSpecMcpToolSpecificationMCP服务所支持的工具定义内容
serverSpecMcpServerBasicInfoMCP服务的定义内容，可由mcpName, version,description,localServerConfig组成，也可以自行创建详细的McpServerBasicInfo

返回参数

参数类型描述
String创建成功后返回 MCP 服务 ID。

请求示例

try {
    String result = aiMaintainerService.createLocalMcpServer("test", "1.0.0");
    result = aiMaintainerService.createLocalMcpServer("test", "1.0.0", "test for mcp server");
    result = aiMaintainerService.createLocalMcpServer("test", "1.0.0", "test for mcp server", null);
    result = aiMaintainerService.createLocalMcpServer("test", "1.0.0", "test for mcp server", Collections.emptyMap(), null);
    McpServerBasicInfo mcpSpec = new McpServerBasicInfo();
    mcpSpec.setName("test");
    mcpSpec.setProtocol(AiConstants.Mcp.MCP_PROTOCOL_STDIO);
    mcpSpec.setDescription("test for mcp server");
    mcpSpec.setLocalServerConfig(Collections.emptyMap());
    ServerVersionDetail versionDetail = new ServerVersionDetail();
    versionDetail.setVersion("1.0.0");
    mcpSpec.setVersionDetail(versionDetail);
    result = aiMaintainerService.createLocalMcpServer("test", mcpSpec, null);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

6.5. 创建Remote(sse, streamable等)类型的MCP服务

描述

创建类型为Remote(sse, streamable等)的MCP服务。

String createRemoteMcpServer(String mcpName, String version, String protocol, McpEndpointSpec endpointSpec) throws NacosException;


String createRemoteMcpServer(String mcpName, String version, String protocol, McpServerRemoteServiceConfig remoteServiceConfig, McpEndpointSpec endpointSpec) throws NacosException;


String createRemoteMcpServer(String mcpName, String version, String description, String protocol, McpServerRemoteServiceConfig remoteServiceConfig, McpEndpointSpec endpointSpec) throws NacosException;


String createRemoteMcpServer(String mcpName, String version, String description, String protocol, McpServerRemoteServiceConfig remoteServiceConfig, McpEndpointSpec endpointSpec, McpToolSpecification toolSpec) throws NacosException;


String createRemoteMcpServer(String mcpName, McpServerBasicInfo serverSpec, McpEndpointSpec endpointSpec) throws NacosException;


String createRemoteMcpServer(String mcpName, McpServerBasicInfo serverSpec, McpToolSpecification toolSpec, McpEndpointSpec endpointSpec) throws NacosException;

请求参数

参数名参数类型描述
mcpNameString创建的MCP服务的名字
versionString创建的MCP服务的版本
descriptionStringMCP服务的描述
protocolStringMCP服务所支持的协议类型，目前支持sse, streamable等协议
endpointSpecMcpEndpointSpecMCP服务Remote Endpoint定义内容，可选REF或DIRECT类型进行配置。
remoteServiceConfigMcpServerRemoteServiceConfigsse或streamable类型的MCP服务配置信息，可参考此MCP服务的启动配置进行配置
toolSpecMcpToolSpecificationMCP服务所支持的工具定义内容
serverSpecMcpServerBasicInfoMCP服务的定义内容，可由mcpName, version,description,localServerConfig组成，也可以自行创建详细的McpServerBasicInfo

返回参数

参数类型描述
String创建成功后返回 MCP 服务 ID。

请求示例

try {
    McpEndpointSpec mcpEndpointSpec = new McpEndpointSpec();
    mcpEndpointSpec.setType(AiConstants.Mcp.MCP_ENDPOINT_TYPE_DIRECT);
    mcpEndpointSpec.getData().put("address", "127.0.0.1");
    mcpEndpointSpec.getData().put("port", "8080");
    String result = aiMaintainerService.createRemoteMcpServer("test", "1.0.0", AiConstants.Mcp.MCP_PROTOCOL_SSE, mcpEndpointSpec);
    result = aiMaintainerService.createRemoteMcpServer("test", "1.0.0", AiConstants.Mcp.MCP_PROTOCOL_SSE, new McpServerRemoteServiceConfig(), mcpEndpointSpec);
    result = aiMaintainerService.createRemoteMcpServer("test", "1.0.0", "test for mcp server", AiConstants.Mcp.MCP_PROTOCOL_SSE, new McpServerRemoteServiceConfig(), mcpEndpointSpec);
    result = aiMaintainerService.createRemoteMcpServer("test", "1.0.0", "test for mcp server", AiConstants.Mcp.MCP_PROTOCOL_SSE, new McpServerRemoteServiceConfig(), mcpEndpointSpec, null);
    McpServerBasicInfo mcpSpec = new McpServerBasicInfo();
    mcpSpec.setName("test");
    mcpSpec.setDescription("test for mcp server");
    mcpSpec.setProtocol(AiConstants.Mcp.MCP_PROTOCOL_SSE);
    mcpSpec.setRemoteServerConfig(new McpServerRemoteServiceConfig());
    ServerVersionDetail versionDetail = new ServerVersionDetail();
    versionDetail.setVersion("1.0.0");
    mcpSpec.setVersionDetail(versionDetail);
    result = aiMaintainerService.createRemoteMcpServer("test", mcpSpec, mcpEndpointSpec);
    result = aiMaintainerService.createRemoteMcpServer("test", mcpSpec, null, mcpEndpointSpec);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

6.6. 更新MCP服务

描述

更新指定的MCP服务。

3.3 新增的 McpServerDraftRequest 重载用于修改已有草稿。请求中的服务、工具、资源及端点定义会替换草稿的全部内容，更新后仍为 draft 状态。要创建新版本，请使用第 6.8 节的草稿创建接口。

McpServerVersionDetail updateMcpServer(String namespaceId, McpServerDraftRequest request) throws NacosException;


McpServerVersionDetail updateMcpServer(McpServerDraftRequest request) throws NacosException;


boolean updateMcpServer(String mcpName, McpServerBasicInfo serverSpec, McpToolSpecification toolSpec, McpEndpointSpec endpointSpec) throws NacosException;


boolean updateMcpServer(String mcpName, boolean isLatest, McpServerBasicInfo serverSpec, McpToolSpecification toolSpec, McpEndpointSpec endpointSpec) throws NacosException;


boolean updateMcpServer(String namespaceId, String mcpName, boolean isLatest, McpServerBasicInfo serverSpec, McpToolSpecification toolSpec, McpEndpointSpec endpointSpec) throws NacosException;


boolean updateMcpServer(String namespaceId, String mcpName, boolean isLatest, McpServerBasicInfo serverSpec, McpToolSpecification toolSpec, McpEndpointSpec endpointSpec, boolean overrideExisting) throws NacosException;

请求参数

参数名参数类型描述
mcpNameStringMCP服务的名称
namespaceIdStringMCP服务所属的命名空间ID，默认为public
isLatestboolean更新的MCP服务版本是否为最新版本，默认为true
serverSpecMcpServerBasicInfo新版本的MCP服务的服务定义内容
toolSpecMcpToolSpecification新版本的MCP服务的工具定义内容
endpointSpecMcpEndpointSpec新版本的MCP服务的Endpoint定义内容
overrideExistingboolean是否覆盖已存在的同版本信息，默认为 false，仅 7 参数重载有效。
requestMcpServerDraftRequest新增重载的完整草稿内容，字段见第 6.8 节。未提供的可选内容不会保留。

返回参数

参数类型描述
boolean兼容重载的更新结果，成功为 true。
McpServerVersionDetail新增重载返回更新后的草稿详情，字段见第 6.10 节。

请求示例

更新第 6.8 节创建的 stdio 草稿并保留工具、资源定义。Remote 草稿还需提供完整的 endpointSpecification。

try {
    McpMaintainerService mcp = aiMaintainerService.mcp();
    McpServerVersionDetail current = mcp.getMcpServerVersion("public", "demo-mcp", "1.0.0");
    McpServerBasicInfo server = current.getServerSpecification();
    server.setDescription("Updated MCP description");
    McpServerDraftRequest request = new McpServerDraftRequest();
    request.setServerSpecification(server);
    request.setToolSpecification(current.getToolSpecification());
    request.setResourceSpecification(current.getResourceSpecification());
    McpServerVersionDetail draft = mcp.updateMcpServer("public", request);
} catch (NacosException e) {
    e.printStackTrace();
}

旧重载示例（以下调用用于展示不同重载，实际使用时选择其中一个）：

try {
    McpServerBasicInfo mcpSpec = new McpServerBasicInfo();
    mcpSpec.setName("test");
    mcpSpec.setDescription("test for mcp server");
    mcpSpec.setProtocol(AiConstants.Mcp.MCP_PROTOCOL_STDIO);
    Map<String, Object> localServerConfig = Collections.singletonMap("test", new HashMap<>());
    mcpSpec.setLocalServerConfig(localServerConfig);
    ServerVersionDetail versionDetail = new ServerVersionDetail();
    versionDetail.setVersion("1.0.1");
    mcpSpec.setVersionDetail(versionDetail);
    boolean result = aiMaintainerService.updateMcpServer("test", mcpSpec, null, null);
    result = aiMaintainerService.updateMcpServer("test", true, mcpSpec, null, null);
    result = aiMaintainerService.updateMcpServer("public", "test", true, mcpSpec, null, null);
    result = aiMaintainerService.updateMcpServer("public", "test", true, mcpSpec, null, null, false);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

6.7. 删除MCP服务

描述

删除指定的MCP服务。

boolean deleteMcpServer(String mcpName) throws NacosException;


boolean deleteMcpServer(String namespaceId, String mcpName, String mcpId, String version) throws NacosException;

请求参数

参数名参数类型描述
mcpNameStringMCP服务的名称
namespaceIdStringMCP服务所属的命名空间ID，默认为public
mcpIdStringMCP服务ID，不指定时可传 null。
versionStringMCP服务版本，不指定时可传 null，传 null 时删除该服务下所有版本。

返回参数

参数类型描述
boolean删除成功为true，其他为false

请求示例

try {
    boolean result = aiMaintainerService.deleteMcpServer("test");
    result = aiMaintainerService.deleteMcpServer("public", "test", null, null);
    result = aiMaintainerService.deleteMcpServer("public", "test", null, "1.0.0");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

6.8. 创建MCP服务（统一接口）

描述

在指定命名空间下创建 MCP 服务版本。3.3 新增的 McpServerDraftRequest 重载会创建草稿；MCP 服务不存在时，也会一并创建。已有 draft、reviewing 或 reviewed 版本时不能再创建草稿，也不能创建已存在的版本号。更新已有草稿请使用第 6.6 节。

旧重载已废弃，调用后仍会直接发布版本。Local/Remote 类型由 serverSpec.protocol 决定；stdio 不需要端点定义，Remote 类型需要提供端点定义。

McpServerVersionDetail createMcpServer(String namespaceId, McpServerDraftRequest request) throws NacosException;


McpServerVersionDetail createMcpServer(McpServerDraftRequest request) throws NacosException;


String createMcpServer(String mcpName, McpServerBasicInfo serverSpec, McpToolSpecification toolSpec, McpEndpointSpec endpointSpec) throws NacosException;


String createMcpServer(String namespaceId, String mcpName, McpServerBasicInfo serverSpec, McpToolSpecification toolSpec, McpEndpointSpec endpointSpec) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID，默认为 public。
mcpNamestringMCP 服务名称。
serverSpecMcpServerBasicInfoMCP 服务基础信息（名称、版本、描述、协议、localServerConfig 等）。
toolSpecMcpToolSpecification工具定义，Local 类型可传 null。
endpointSpecMcpEndpointSpecRemote 类型所需的端点定义；stdio 可传 null。
requestMcpServerDraftRequest新增重载的完整草稿请求，见下表。

McpServerDraftRequest 的字段如下：

参数名参数类型描述
serverSpecificationMcpServerBasicInfo必填。包含 name、protocol、versionDetail.version，以及对应协议的启动或连接配置。
toolSpecificationMcpToolSpecification工具定义，可选。
resourceSpecificationMcpResourceSpecificationMCP 资源定义，可选。
endpointSpecificationMcpEndpointSpecRemote 类型的端点定义，支持 DIRECT 或 REF；stdio 不需要。

返回参数

参数类型描述
McpServerVersionDetail新增重载返回创建后的草稿详情，字段见第 6.10 节。
String兼容重载返回创建的 MCP 服务 ID。

请求示例

以下示例只保存 stdio 启动定义，不会启动 MCP 进程。创建成功后按第 6.12 节提交；启用审核时，审核通过后再按第 6.13 节发布。

try {
    McpMaintainerService mcp = aiMaintainerService.mcp();
    McpServerBasicInfo server = new McpServerBasicInfo();
    server.setName("demo-mcp");
    server.setProtocol("stdio");
    server.setLocalServerConfig(Collections.<String, Object>singletonMap("command", "my-mcp-server"));
    ServerVersionDetail version = new ServerVersionDetail();
    version.setVersion("1.0.0");
    server.setVersionDetail(version);


    McpServerDraftRequest request = new McpServerDraftRequest();
    request.setServerSpecification(server);
    McpServerVersionDetail draft = mcp.createMcpServer("public", request);
} catch (NacosException e) {
    e.printStackTrace();
}

旧重载示例（以下调用用于展示不同重载，实际使用时选择其中一个）：

try {
    McpServerBasicInfo serverSpec = new McpServerBasicInfo();
    serverSpec.setName("my-mcp");
    serverSpec.setProtocol(AiConstants.Mcp.MCP_PROTOCOL_STDIO);
    ServerVersionDetail versionDetail = new ServerVersionDetail();
    versionDetail.setVersion("1.0.0");
    serverSpec.setVersionDetail(versionDetail);
    String result = aiMaintainerService.createMcpServer("my-mcp", serverSpec, null, null);
    result = aiMaintainerService.createMcpServer(Constants.DEFAULT_NAMESPACE_ID, "my-mcp", serverSpec, null, null);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

6.9. 分页查询 MCP 版本

描述

查询指定 MCP 服务的版本摘要，可按生命周期状态过滤。

Page<McpServerVersionSummary> listMcpServerVersions(String namespaceId, String mcpName, String status, int pageNo, int pageSize) throws NacosException;


Page<McpServerVersionSummary> listMcpServerVersions(String mcpName, String status, int pageNo, int pageSize) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdString命名空间 ID；省略时使用 public。
mcpNameString精确的 MCP 服务名称。
statusString可选：draft、reviewing、reviewed、online、offline；传 null 不过滤。
pageNoint页码，从 1 开始。
pageSizeint每页数量。

返回参数

参数类型描述
Page<McpServerVersionSummary>版本摘要分页；每项包含 version、status、publishPipelineInfo、author、description、latest、createTime、updateTime。

请求示例

try {
    McpMaintainerService mcp = aiMaintainerService.mcp();
    Page<McpServerVersionSummary> page =
            mcp.listMcpServerVersions("public", "demo-mcp", "online", 1, 20);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

查询失败时抛出 NacosException。

6.10. 获取 MCP 指定版本

描述

根据版本号查询 MCP 服务的完整定义及版本状态，支持查询草稿和已下线版本。

McpServerVersionDetail getMcpServerVersion(String namespaceId, String mcpName, String version) throws NacosException;


McpServerVersionDetail getMcpServerVersion(String mcpName, String version) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdString命名空间 ID；省略时使用 public。
mcpNameString精确的 MCP 服务名称。
versionString精确版本，必填；不能传标签。

返回参数

参数类型描述
McpServerVersionDetail版本详情，在第 6.9 节摘要字段基础上增加下列信息。
字段类型描述
namespaceId、mcpNameString资源标识。
serverSpecificationMcpServerBasicInfo服务定义与协议配置。
toolSpecificationMcpToolSpecification工具定义。
resourceSpecificationMcpResourceSpecificationMCP 资源定义。
resourceStatusString资源启停状态，与版本 status 区分。
owner、scopeString所有者与可见范围。
labelsMap<String, String>版本标签，latest 由服务端维护。
editingVersion、reviewingVersionString当前编辑、审核版本。
onlineCountInteger在线版本数量。
writableboolean是否允许当前用户修改此 MCP 服务。

请求示例

try {
    McpMaintainerService mcp = aiMaintainerService.mcp();
    McpServerVersionDetail detail = mcp.getMcpServerVersion("public", "demo-mcp", "1.0.0");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

查询失败时抛出 NacosException。

6.11. 删除 MCP 草稿

描述

删除指定的 draft 版本；不能用此方法删除已发布版本。

void deleteMcpServerDraft(String namespaceId, McpServerVersionCommand command) throws NacosException;


void deleteMcpServerDraft(McpServerVersionCommand command) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdString命名空间 ID；省略时使用 public。
commandMcpServerVersionCommand包含 MCP 服务名称 mcpName 和版本号 version，均为必填。

返回参数

无返回值。

请求示例

try {
    McpMaintainerService mcp = aiMaintainerService.mcp();
    McpServerVersionCommand command = new McpServerVersionCommand();
    command.setMcpName("demo-mcp");
    command.setVersion("1.0.0");
    mcp.deleteMcpServerDraft("public", command);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

目标版本不是草稿或删除失败时抛出 NacosException。

6.12. 提交 MCP 版本

描述

提交指定版本进行审核。配置了适用于 MCP 的发布流水线时，版本进入审核；否则直接发布。可通过返回值中的 status 查看提交后的状态。重复提交正在审核的版本不会启动新的审核。

McpServerVersionSummary submitMcpServerVersion(String namespaceId, McpServerVersionCommand command) throws NacosException;


McpServerVersionSummary submitMcpServerVersion(McpServerVersionCommand command) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdString命名空间 ID；省略时使用 public。
commandMcpServerVersionCommand包含 MCP 服务名称 mcpName 和版本号 version，均为必填。

返回参数

参数类型描述
McpServerVersionSummary提交后的版本摘要。

请求示例

try {
    McpMaintainerService mcp = aiMaintainerService.mcp();
    McpServerVersionCommand command = new McpServerVersionCommand();
    command.setMcpName("demo-mcp");
    command.setVersion("1.0.0");
    McpServerVersionSummary summary = mcp.submitMcpServerVersion("public", command);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

版本状态不允许提交或请求失败时抛出 NacosException。

6.13. 发布 MCP 版本

描述

发布审核通过的 reviewed 版本。成功后状态为 online，latest 标签指向该版本。审核未通过时，可退回草稿修改后重新提交。

McpServerVersionSummary publishMcpServerVersion(String namespaceId, McpServerVersionCommand command) throws NacosException;


McpServerVersionSummary publishMcpServerVersion(McpServerVersionCommand command) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdString命名空间 ID；省略时使用 public。
commandMcpServerVersionCommand包含 MCP 服务名称 mcpName 和版本号 version，均为必填。

返回参数

参数类型描述
McpServerVersionSummary发布后的在线版本摘要。

请求示例

try {
    McpMaintainerService mcp = aiMaintainerService.mcp();
    McpServerVersionCommand command = new McpServerVersionCommand();
    command.setMcpName("demo-mcp");
    command.setVersion("1.0.0");
    McpServerVersionSummary summary = mcp.publishMcpServerVersion("public", command);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

版本未通过审核或发布失败时抛出 NacosException。

6.14. 强制发布 MCP 版本

描述

跳过审核，直接发布指定版本。版本必须处于 draft、reviewing 或 reviewed 状态；成功后变为 online，latest 标签指向该版本。常规发布请使用提交和发布接口。

McpServerVersionSummary forcePublishMcpServerVersion(String namespaceId, McpServerVersionCommand command) throws NacosException;


McpServerVersionSummary forcePublishMcpServerVersion(McpServerVersionCommand command) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdString命名空间 ID；省略时使用 public。
commandMcpServerVersionCommand包含 MCP 服务名称 mcpName 和版本号 version，均为必填。

返回参数

参数类型描述
McpServerVersionSummary强制发布后的在线版本摘要。

请求示例

try {
    McpMaintainerService mcp = aiMaintainerService.mcp();
    McpServerVersionCommand command = new McpServerVersionCommand();
    command.setMcpName("demo-mcp");
    command.setVersion("1.0.0");
    McpServerVersionSummary summary = mcp.forcePublishMcpServerVersion("public", command);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

版本状态不允许强制发布或请求失败时抛出 NacosException。

6.15. 将 MCP 版本退回草稿

描述

将 reviewed 版本退回 draft，保持版本号不变。退回后可使用第 6.6 节修改内容。

McpServerVersionSummary redraftMcpServerVersion(String namespaceId, McpServerVersionCommand command) throws NacosException;


McpServerVersionSummary redraftMcpServerVersion(McpServerVersionCommand command) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdString命名空间 ID；省略时使用 public。
commandMcpServerVersionCommand包含 MCP 服务名称 mcpName 和版本号 version，均为必填。

返回参数

参数类型描述
McpServerVersionSummary退回后的草稿版本摘要。

请求示例

try {
    McpMaintainerService mcp = aiMaintainerService.mcp();
    McpServerVersionCommand command = new McpServerVersionCommand();
    command.setMcpName("demo-mcp");
    command.setVersion("1.0.0");
    McpServerVersionSummary summary = mcp.redraftMcpServerVersion("public", command);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

版本状态不允许退回草稿或请求失败时抛出 NacosException。

6.16. 上线 MCP 版本

描述

将已下线（offline）的 MCP 版本重新上线，latest 标签指向该版本。

McpServerVersionSummary onlineMcpServerVersion(String namespaceId, McpServerVersionCommand command) throws NacosException;


McpServerVersionSummary onlineMcpServerVersion(McpServerVersionCommand command) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdString命名空间 ID；省略时使用 public。
commandMcpServerVersionCommand包含 MCP 服务名称 mcpName 和版本号 version，均为必填。

返回参数

参数类型描述
McpServerVersionSummary上线后的版本摘要。

请求示例

try {
    McpMaintainerService mcp = aiMaintainerService.mcp();
    McpServerVersionCommand command = new McpServerVersionCommand();
    command.setMcpName("demo-mcp");
    command.setVersion("1.0.0");
    McpServerVersionSummary summary = mcp.onlineMcpServerVersion("public", command);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

版本状态不允许上线或请求失败时抛出 NacosException。

6.17. 下线 MCP 版本

描述

将 online 版本下线，客户端将无法再发现该版本。版本内容仍保留，下线操作不会停止 MCP 服务进程。如果下线的是 latest 指向的版本，服务端会将该标签改为指向其他在线版本；没有在线版本时移除标签。

McpServerVersionSummary offlineMcpServerVersion(String namespaceId, McpServerVersionCommand command) throws NacosException;


McpServerVersionSummary offlineMcpServerVersion(McpServerVersionCommand command) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdString命名空间 ID；省略时使用 public。
commandMcpServerVersionCommand包含 MCP 服务名称 mcpName 和版本号 version，均为必填。

返回参数

参数类型描述
McpServerVersionSummary下线后的版本摘要。

请求示例

try {
    McpMaintainerService mcp = aiMaintainerService.mcp();
    McpServerVersionCommand command = new McpServerVersionCommand();
    command.setMcpName("demo-mcp");
    command.setVersion("1.0.0");
    McpServerVersionSummary summary = mcp.offlineMcpServerVersion("public", command);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

版本状态不允许下线或请求失败时抛出 NacosException。

6.18. 更新 MCP 自定义版本标签

描述

替换全部自定义版本标签。标签指向的版本必须存在，且不能处于 draft 或 reviewing 状态；传入空 Map 可清空自定义标签。latest 由服务端维护，请求中对它的修改会被忽略。

Map<String, String> updateMcpServerLabels(String namespaceId, McpServerLabelsUpdateRequest request) throws NacosException;


Map<String, String> updateMcpServerLabels(McpServerLabelsUpdateRequest request) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdString命名空间 ID；省略时使用 public。
requestMcpServerLabelsUpdateRequest必填 mcpName 和非 null 的 labels（Map<String, String>）。

返回参数

参数类型描述
Map<String, String>更新后的完整标签映射，包括服务端维护的 latest（存在时）。

请求示例

try {
    McpMaintainerService mcp = aiMaintainerService.mcp();
    McpServerLabelsUpdateRequest request = new McpServerLabelsUpdateRequest();
    request.setMcpName("demo-mcp");
    request.setLabels(Collections.singletonMap("stable", "1.0.0"));
    Map<String, String> labels = mcp.updateMcpServerLabels("public", request);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

标签无效或更新失败时抛出 NacosException。

6.19. 启用或禁用 MCP 服务

描述

启用或禁用 MCP 服务。此操作修改 MCP 定义中的启用状态，不影响各版本的内容、发布状态，也不会启停 MCP 服务进程。

boolean updateMcpServerStatus(String namespaceId, String mcpName, boolean enabled) throws NacosException;


boolean updateMcpServerStatus(String mcpName, boolean enabled) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdString命名空间 ID；省略时使用 public。
mcpNameString精确的 MCP 服务名称。
enabledbooleantrue 启用，false 禁用。

返回参数

参数类型描述
boolean操作是否成功。

请求示例

try {
    McpMaintainerService mcp = aiMaintainerService.mcp();
    boolean updated = mcp.updateMcpServerStatus("public", "demo-mcp", true);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

参数无效或更新失败时抛出 NacosException。

6.20. 更新 MCP 可见范围

描述

修改 MCP 服务的可见范围，内置策略支持 PUBLIC（公开）和 PRIVATE（私有）。公开资源的访问仍受鉴权和资源权限控制。

boolean updateMcpServerScope(String namespaceId, String mcpName, String scope) throws NacosException;


boolean updateMcpServerScope(String mcpName, String scope) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdString命名空间 ID；省略时使用 public。
mcpNameString精确的 MCP 服务名称。
scopeString目标可见范围：PUBLIC 或 PRIVATE。

返回参数

参数类型描述
boolean操作是否成功。

请求示例

try {
    McpMaintainerService mcp = aiMaintainerService.mcp();
    boolean updated = mcp.updateMcpServerScope("public", "demo-mcp", "PRIVATE");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

参数无效或更新失败时抛出 NacosException。

7. A2A 注册中心

兼容与迁移建议：本章的 A2aMaintainerService 是旧 A2A 管理接口，兼容期内仍会保留。协议无关的 AgentMaintainerService（通过 aiMaintainerService.agent() 获取）未来将替代本章接口；新接入的用户和 SDK 建议优先使用第 11 章的 Agent 管理接口，不再新增对旧 A2A 管理接口的依赖。

7.1. 发布AgentCard

描述

发布AgentCard到指定的命名空间下。

boolean registerAgent(AgentCard agentCard) throws NacosException;


boolean registerAgent(AgentCard agentCard, String namespaceId) throws NacosException;


boolean registerAgent(AgentCard agentCard, String namespaceId, String registrationType) throws NacosException;

请求参数

参数名参数类型描述
agentCardAgentCardAgentCard对象
namespaceIdStringAgentCard所属的命名空间ID，默认为public
registrationTypeString注册方式，可选值为URL和SERVICE，默认为URL，设置此AgentCard默认的url获取方式，URL代表直接读取注册时的url，SERVICE代表根据注册在Nacos中的endpoint生成url

返回参数

参数类型描述
boolean注册成功为true，其他为false

请求示例

try {
    AgentCard agentCard = new AgentCard();
    agentCard.setName("test");
    agentCard.setDescription("test for agent card");
    agentCard.setUrl("http://localhost:8848");
    agentCard.setVersion("1.0.0");
    agentCard.setProtocolVersion("0.3.0");
    boolean result = aiMaintainerService.registerAgent(agentCard);
    result = aiMaintainerService.registerAgent(agentCard, "public");
    result = aiMaintainerService.registerAgent(agentCard, "public", "URL");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

7.2. 查询AgentCard

描述

查询指定命名空间下的AgentCard。

AgentCardDetailInfo getAgentCard(String agentName) throws NacosException;


AgentCardDetailInfo getAgentCard(String agentName, String namespaceId) throws NacosException;


AgentCardDetailInfo getAgentCard(String agentName, String namespaceId, String registrationType) throws NacosException;


AgentCardDetailInfo getAgentCard(String agentName, String namespaceId, String registrationType, String version) throws NacosException;

请求参数

参数名参数类型描述
agentNameStringAgentCard的名称
namespaceIdStringAgentCard所属的命名空间ID，默认为public
registrationTypeString注册方式，可选值为URL和SERVICE，默认为URL，可选，若为空，则根据注册此AgentCard时设置的registrationType自动选择url
versionStringAgentCard 的版本号，不指定时可传空字符串，则返回默认版本。

返回参数

参数类型描述
AgentCardDetailInfoAgentCard详情对象

请求示例

try {
    AgentCardDetailInfo result = aiMaintainerService.getAgentCard("test");
    result = aiMaintainerService.getAgentCard("test", "public");
    result = aiMaintainerService.getAgentCard("test", "public", "URL");
    result = aiMaintainerService.getAgentCard("test", "public", "URL", "1.0.0");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

7.3. 更新AgentCard

描述

更新指定命名空间下的AgentCard。

boolean updateAgentCard(AgentCard agentCard) throws NacosException;


boolean updateAgentCard(AgentCard agentCard, String namespaceId) throws NacosException;


boolean updateAgentCard(AgentCard agentCard, String namespaceId, boolean setAsLatest) throws NacosException;


boolean updateAgentCard(AgentCard agentCard, String namespaceId, boolean setAsLatest, String registrationType) throws NacosException;

请求参数

参数名参数类型描述
agentCardAgentCardAgentCard对象
namespaceIdStringAgentCard所属的命名空间ID，默认为public
setAsLatestboolean是否将此AgentCard设置为最新版本
registrationTypeString注册方式，可选值为URL和SERVICE，默认为URL，设置此AgentCard默认的url获取方式，URL代表直接读取注册时的url，SERVICE代表根据注册在Nacos中的endpoint生成url

返回参数

参数类型描述
boolean更新成功为true，其他为false

请求示例

try {
    AgentCard agentCard = new AgentCard();
    agentCard.setName("test");
    agentCard.setDescription("test for agent card");
    agentCard.setUrl("http://localhost:8848");
    agentCard.setVersion("1.0.0");
    agentCard.setProtocolVersion("0.3.0");
    boolean result = aiMaintainerService.updateAgentCard(agentCard);
    result = aiMaintainerService.updateAgentCard(agentCard, "public");
    result = aiMaintainerService.updateAgentCard(agentCard, "public", true);
    result = aiMaintainerService.updateAgentCard(agentCard, "public", true, "URL");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

7.4. 删除AgentCard

描述

删除指定命名空间下的AgentCard。

boolean deleteAgent(String agentName) throws NacosException;


boolean deleteAgent(String agentName, String namespaceId) throws NacosException;


boolean deleteAgent(String agentName, String namespaceId, String version) throws NacosException;

请求参数

参数名参数类型描述
agentNameStringAgentCard的名称
namespaceIdStringAgentCard所属的命名空间ID，默认为public
versionStringAgentCard的版本，若为空，则删除所有版本

返回参数

参数类型描述
boolean删除成功为true，其他为false

请求示例

try {
    boolean result = aiMaintainerService.deleteAgent("test");
    result = aiMaintainerService.deleteAgent("test", "public");
    result = aiMaintainerService.deleteAgent("test", "public", "");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

7.5. 查询指定AgentCard的所有版本

描述

查询指定命名空间下的指定AgentCard的所有版本。

List<AgentVersionDetail> listAllVersionOfAgent(String agentName) throws NacosException;


List<AgentVersionDetail> listAllVersionOfAgent(String agentName, String namespaceId) throws NacosException;

请求参数

参数名参数类型描述
agentNameStringAgentCard的名称
namespaceIdStringAgentCard所属的命名空间ID，默认为public

返回参数

参数类型描述
ListAgentCard的所有版本列表

请求示例

try {
    List<AgentVersionDetail> result = aiMaintainerService.listAllVersionOfAgent("test");
    result = aiMaintainerService.listAllVersionOfAgent("test", "public");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

7.6. 根据AgentCard名称搜索AgentCard

描述

根据AgentCard名称搜索AgentCard。每次仅能搜索单个命名空间下的AgentCard。

Page<AgentCardVersionInfo> searchAgentCardsByName(String agentNamePattern) throws NacosException;


default Page<AgentCardVersionInfo> searchAgentCardsByName(String agentNamePattern, int pageNo, int pageSize) throws NacosException;


Page<AgentCardVersionInfo> searchAgentCardsByName(String namespaceId, String agentNamePattern, int pageNo, int pageSize) throws NacosException;

请求参数

参数名参数类型描述
agentNamePatternStringAgentCard的名称的格式匹配字符串
namespaceIdStringAgentCard所属的命名空间ID，默认为public
pageNoint页码，默认为1
pageSizeint每页大小，默认为100

返回参数

参数类型描述
Page搜索的分页结果

请求示例

try {
    Page<AgentCardVersionInfo> result = aiMaintainerService.searchAgentCardsByName("test");
    result = aiMaintainerService.searchAgentCardsByName("test", 1, 100);
    result = aiMaintainerService.searchAgentCardsByName("test", "public", 1, 100);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

7.7. 分页查询AgentCard列表

描述

分页查询AgentCard列表。每次仅能查询单个命名空间下的AgentCard。

Page<AgentCardVersionInfo> listAgentCards() throws NacosException;


Page<AgentCardVersionInfo> listAgentCards(int pageNo, int pageSize) throws NacosException;


Page<AgentCardVersionInfo> listAgentCards(String namespaceId, int pageNo, int pageSize) throws NacosException;


Page<AgentCardVersionInfo> listAgentCards(String namespaceId, String agentName, int pageNo, int pageSize) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdStringAgentCard所属的命名空间ID，默认为public
pageNoint页码，默认为1
pageSizeint每页大小，默认为100
agentNameStringAgentCard的名称，精确匹配，若为空，则查询所有AgentCard

返回参数

参数类型描述
Page查询的分页结果

请求示例

try {
    Page<AgentCardVersionInfo> result = aiMaintainerService.listAgentCards();
    result = aiMaintainerService.listAgentCards(1, 100);
    result = aiMaintainerService.listAgentCards("public", 1, 100);
    result = aiMaintainerService.listAgentCards("test", "public", 1, 100);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求执行失败（例如请求超时或网络异常）时，抛出 NacosException。

8. Prompt 能力

8.1. 分页查询 Prompt 列表

描述

按命名空间、promptKey 模式、搜索模式、业务标签等分页查询 Prompt 列表。

Page<PromptMetaSummary> listPrompts(String namespaceId, String promptKey, String search, String bizTags, int pageNo, int pageSize) throws NacosException;


Page<PromptMetaSummary> listPrompts(String promptKey, int pageNo, int pageSize) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID，默认 public。
promptKeystringprompt 键名模式过滤。
searchstring搜索模式：accurate 精确 或 blur 模糊。
bizTagsstring业务标签过滤，逗号分隔（可选）。
pageNoint页码。
pageSizeint每页条数。

返回参数

参数类型描述
Page<PromptMetaSummary>分页 Prompt 列表。

请求示例

try {
    PromptMaintainerService promptMaintainerService = aiMaintainerService.prompt();
    Page<PromptMetaSummary> result = promptMaintainerService.listPrompts("public", "my-prompt", "blur", null, 1, 100);
    result = promptMaintainerService.listPrompts("my-prompt", 1, 100);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

8.2. 获取 Prompt 元信息

描述

根据命名空间与 promptKey 获取 Prompt 的元信息。

PromptMetaInfo getPromptMeta(String namespaceId, String promptKey) throws NacosException;


PromptMetaInfo getPromptMeta(String promptKey) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
promptKeystringPrompt 的 key。

返回参数

参数类型描述
PromptMetaInfoPrompt 元信息。

请求示例

try {
    PromptMaintainerService promptMaintainerService = aiMaintainerService.prompt();
    PromptMetaInfo meta = promptMaintainerService.getPromptMeta("public", "my-prompt");
    meta = promptMaintainerService.getPromptMeta("my-prompt");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

8.3. 查询 Prompt 版本详情

描述

根据命名空间、promptKey、版本与标签查询 Prompt 版本详情。

PromptVersionInfo queryPromptDetail(String namespaceId, String promptKey, String version, String label) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
promptKeystringPrompt key。
versionstring版本号。
labelstring标签（可选）。

返回参数

参数类型描述
PromptVersionInfoPrompt 版本详情。

请求示例

try {
    PromptMaintainerService promptMaintainerService = aiMaintainerService.prompt();
    PromptVersionInfo detail = promptMaintainerService.queryPromptDetail("public", "my-prompt", "1.0.0", null);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

8.4. 绑定 Prompt 标签

描述

将指定标签绑定到 Prompt 的某一版本。

boolean bindLabel(String namespaceId, String promptKey, String label, String version) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
promptKeystringPrompt key。
labelstring标签名。
versionstring版本号。

返回参数

参数类型描述
boolean绑定是否成功。

请求示例

try {
    PromptMaintainerService promptMaintainerService = aiMaintainerService.prompt();
    boolean ok = promptMaintainerService.bindLabel("public", "my-prompt", "stable", "1.0.0");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

8.5. 解绑 Prompt 标签

描述

解绑 Prompt 的指定标签。

boolean unbindLabel(String namespaceId, String promptKey, String label) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
promptKeystringPrompt key。
labelstring标签名。

返回参数

参数类型描述
boolean解绑是否成功。

请求示例

try {
    PromptMaintainerService promptMaintainerService = aiMaintainerService.prompt();
    boolean ok = promptMaintainerService.unbindLabel("public", "my-prompt", "stable");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

8.6. 发布 Prompt 版本

描述

发布 Prompt 新版本，可带描述与业务标签。

boolean publishPrompt(String namespaceId, String promptKey, String version, String template, String commitMsg, String description, String bizTags, String variables) throws NacosException;


boolean publishPrompt(String namespaceId, String promptKey, String version, String template, String commitMsg, String description, String bizTags) throws NacosException;


boolean publishPrompt(String namespaceId, String promptKey, String version, String template, String commitMsg, String description) throws NacosException;


boolean publishPrompt(String promptKey, String version, String template, String commitMsg) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
promptKeystringPrompt key。
versionstring版本号（需大于当前版本）。
templatestring模板内容。
commitMsgstring提交说明。
descriptionstring描述（可选）。
bizTagsstring业务标签，逗号分隔（可选）。
variablesstring变量定义 JSON（可选）。

返回参数

参数类型描述
boolean发布是否成功。

请求示例

try {
    PromptMaintainerService promptMaintainerService = aiMaintainerService.prompt();
    boolean ok = promptMaintainerService.publishPrompt("public", "my-prompt", "1.0.1", "Hello {{name}}", "init", "desc", null, "{\"name\":\"string\"}");
    ok = promptMaintainerService.publishPrompt("public", "my-prompt", "1.0.1", "Hello {{name}}", "init", "desc", null);
    ok = promptMaintainerService.publishPrompt("my-prompt", "1.0.1", "Hello {{name}}", "init");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

8.7. 删除 Prompt

描述

删除指定命名空间下的 Prompt。

boolean deletePrompt(String namespaceId, String promptKey) throws NacosException;


boolean deletePrompt(String promptKey) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
promptKeystringPrompt key。

返回参数

参数类型描述
boolean删除是否成功。

请求示例

try {
    PromptMaintainerService promptMaintainerService = aiMaintainerService.prompt();
    boolean ok = promptMaintainerService.deletePrompt("public", "my-prompt");
    ok = promptMaintainerService.deletePrompt("my-prompt");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

8.8. 分页查询 Prompt 版本列表

描述

分页查询指定 Prompt 的版本列表。

Page<PromptVersionSummary> listPromptVersions(String namespaceId, String promptKey, int pageNo, int pageSize) throws NacosException;


Page<PromptVersionSummary> listPromptVersions(String promptKey, int pageNo, int pageSize) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
promptKeystringPrompt key。
pageNoint页码。
pageSizeint每页条数。

返回参数

参数类型描述
Page<PromptVersionSummary>版本分页列表。

请求示例

try {
    PromptMaintainerService promptMaintainerService = aiMaintainerService.prompt();
    Page<PromptVersionSummary> result = promptMaintainerService.listPromptVersions("public", "my-prompt", 1, 100);
    result = promptMaintainerService.listPromptVersions("my-prompt", 1, 100);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

8.9. 更新 Prompt 元数据

描述

更新 Prompt 的描述与业务标签。

boolean updatePromptMetadata(String namespaceId, String promptKey, String description, String bizTags) throws NacosException;


boolean updatePromptMetadata(String namespaceId, String promptKey, String description) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
promptKeystringPrompt key。
descriptionstring新描述。
bizTagsstring新业务标签，逗号分隔（可选）。

返回参数

参数类型描述
boolean更新是否成功。

请求示例

try {
    PromptMaintainerService promptMaintainerService = aiMaintainerService.prompt();
    boolean ok = promptMaintainerService.updatePromptMetadata("public", "my-prompt", "new desc", "tag1,tag2");
    ok = promptMaintainerService.updatePromptMetadata("public", "my-prompt", "new desc");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

8.10. 获取 Prompt 治理详情

描述

根据命名空间与 promptKey 获取 Prompt 治理详情，包含版本治理信息与所有版本摘要。

PromptMetaInfo getPromptGovernanceDetail(String namespaceId, String promptKey) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
promptKeystringPrompt 的 key。

返回参数

参数类型描述
PromptMetaInfoPrompt 治理详情。

请求示例

try {
    PromptMaintainerService promptMaintainerService = aiMaintainerService.prompt();
    PromptMetaInfo detail = promptMaintainerService.getPromptGovernanceDetail("public", "my-prompt");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

8.11. 获取 Prompt 指定版本详情

描述

根据命名空间、promptKey 与版本号获取 Prompt 指定版本详情。

PromptVersionInfo getVersionDetail(String namespaceId, String promptKey, String version) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
promptKeystringPrompt 的 key。
versionstringPrompt 版本。

返回参数

参数类型描述
PromptVersionInfoPrompt 指定版本详情。

请求示例

try {
    PromptMaintainerService promptMaintainerService = aiMaintainerService.prompt();
    PromptVersionInfo detail = promptMaintainerService.getVersionDetail("public", "my-prompt", "1.0.0");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

8.12. 创建 Prompt 草稿

描述

创建 Prompt 草稿版本，可基于已有版本 fork，并可指定目标草稿版本、模板、变量、提交说明、描述与业务标签。

String createDraft(String namespaceId, String promptKey, String basedOnVersion, String targetVersion, String template, String variables, String commitMsg, String description, String bizTags) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
promptKeystringPrompt 的 key。
basedOnVersionstringfork 基于的版本（可选）。
targetVersionstring目标草稿版本（可选）。
templatestringPrompt 模板内容。
variablesstring变量定义 JSON（可选）。
commitMsgstring提交说明（可选）。
descriptionstringPrompt 描述（首次创建时可选）。
bizTagsstring业务标签 JSON（首次创建时可选）。

返回参数

参数类型描述
String创建出的草稿版本号。

请求示例

try {
    PromptMaintainerService promptMaintainerService = aiMaintainerService.prompt();
    String version = promptMaintainerService.createDraft("public", "my-prompt", "1.0.0", "1.0.1-draft",
            "Hello {{name}}", "{\"name\":\"string\"}", "update prompt", "desc", "[\"ai\"]");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

8.13. 更新 Prompt 草稿

描述

更新当前 Prompt 草稿内容。

void updateDraft(String namespaceId, String promptKey, String template, String variables, String commitMsg) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
promptKeystringPrompt 的 key。
templatestring更新后的模板内容。
variablesstring变量定义 JSON（可选）。
commitMsgstring提交说明（可选）。

返回参数

无

请求示例

try {
    PromptMaintainerService promptMaintainerService = aiMaintainerService.prompt();
    promptMaintainerService.updateDraft("public", "my-prompt", "Hello {{name}}", "{\"name\":\"string\"}", "update template");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

8.14. 删除 Prompt 草稿

描述

删除指定 Prompt 的当前草稿版本。

void deleteDraft(String namespaceId, String promptKey) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
promptKeystringPrompt 的 key。

返回参数

无

请求示例

try {
    PromptMaintainerService promptMaintainerService = aiMaintainerService.prompt();
    promptMaintainerService.deleteDraft("public", "my-prompt");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

8.15. 提交 Prompt 版本审核

描述

提交 Prompt 指定版本进入发布审核流程。

String submit(String namespaceId, String promptKey, String version) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
promptKeystringPrompt 的 key。
versionstring版本号（可选，服务端可自动选择当前草稿）。

返回参数

参数类型描述
String提交后的版本号。

请求示例

try {
    PromptMaintainerService promptMaintainerService = aiMaintainerService.prompt();
    String version = promptMaintainerService.submit("public", "my-prompt", "1.0.1");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

8.16. 发布 Prompt 版本

描述

发布审核通过的 Prompt 版本。latest 标签由服务端管理。

void publish(String namespaceId, String promptKey, String version, Boolean updateLatestLabel) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
promptKeystringPrompt 的 key。
versionstring待发布版本。
updateLatestLabelboolean兼容保留参数，服务端忽略该值。

返回参数

无

请求示例

try {
    PromptMaintainerService promptMaintainerService = aiMaintainerService.prompt();
    promptMaintainerService.publish("public", "my-prompt", "1.0.1", true);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

8.17. 强制发布 Prompt 版本

描述

跳过审核流程强制发布 Prompt 版本。latest 标签由服务端管理。

void forcePublish(String namespaceId, String promptKey, String version, Boolean updateLatestLabel) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
promptKeystringPrompt 的 key。
versionstring待发布版本。
updateLatestLabelboolean兼容保留参数，服务端忽略该值。

返回参数

无

请求示例

try {
    PromptMaintainerService promptMaintainerService = aiMaintainerService.prompt();
    promptMaintainerService.forcePublish("public", "my-prompt", "1.0.1", true);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

8.18. 重新编辑 Prompt 版本

描述

将已审核的 Prompt 版本重新转回草稿状态，以便继续编辑。

boolean redraft(String namespaceId, String promptKey, String version) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
promptKeystringPrompt 的 key。
versionstring需要重新编辑的版本。

返回参数

参数类型描述
boolean重新转草稿是否成功。

请求示例

try {
    PromptMaintainerService promptMaintainerService = aiMaintainerService.prompt();
    boolean ok = promptMaintainerService.redraft("public", "my-prompt", "1.0.1");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

8.19. 变更 Prompt 上下线状态

描述

对 Prompt 指定版本进行上线或下线操作。

void changeOnlineStatus(String namespaceId, String promptKey, String version, boolean online) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
promptKeystringPrompt 的 key。
versionstring版本号。
onlinebooleantrue 上线，false 下线。

返回参数

无

请求示例

try {
    PromptMaintainerService promptMaintainerService = aiMaintainerService.prompt();
    promptMaintainerService.changeOnlineStatus("public", "my-prompt", "1.0.1", true);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

8.20. 更新 Prompt 标签

描述

更新 Prompt 的 labels JSON，用于维护标签与版本的映射。

void updateLabels(String namespaceId, String promptKey, String labels) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
promptKeystringPrompt 的 key。
labelsstringlabels JSON。

返回参数

无

请求示例

try {
    PromptMaintainerService promptMaintainerService = aiMaintainerService.prompt();
    promptMaintainerService.updateLabels("public", "my-prompt", "{\"latest\":\"1.0.1\"}");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

8.21. 更新 Prompt 描述

描述

更新 Prompt 的描述信息。

void updateDescription(String namespaceId, String promptKey, String description) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
promptKeystringPrompt 的 key。
descriptionstring新描述。

返回参数

无

请求示例

try {
    PromptMaintainerService promptMaintainerService = aiMaintainerService.prompt();
    promptMaintainerService.updateDescription("public", "my-prompt", "new desc");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

8.22. 更新 Prompt 业务标签

描述

更新 Prompt 的业务标签（bizTags JSON）。

void updateBizTags(String namespaceId, String promptKey, String bizTags) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
promptKeystringPrompt 的 key。
bizTagsstringbizTags JSON。

返回参数

无

请求示例

try {
    PromptMaintainerService promptMaintainerService = aiMaintainerService.prompt();
    promptMaintainerService.updateBizTags("public", "my-prompt", "[\"ai\",\"ops\"]");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

9. Skill 能力

9.1. 删除 Skill

描述

删除指定命名空间下的 Skill。

boolean deleteSkill(String namespaceId, String skillName) throws NacosException;


boolean deleteSkill(String skillName) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
skillNamestringSkill 名称。

返回参数

参数类型描述
boolean删除是否成功。

请求示例

try {
    SkillMaintainerService skillMaintainerService = aiMaintainerService.skill();
    boolean ok = skillMaintainerService.deleteSkill("public", "my-skill");
    ok = skillMaintainerService.deleteSkill("my-skill");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

9.2. 分页查询 Skill 列表

描述

按命名空间、名称模式、搜索模式分页查询 Skill 列表。

Page<SkillSummary> listSkills(String namespaceId, String skillName, String search, int pageNo, int pageSize) throws NacosException;


Page<SkillSummary> listSkills(String namespaceId, String skillName, String search, String orderBy, String owner, String scope, int pageNo, int pageSize) throws NacosException;


Page<SkillSummary> listSkills(String namespaceId, String skillName, String search, String orderBy, String owner, String scope, String bizTag, int pageNo, int pageSize) throws NacosException;


Page<SkillSummary> listSkills(String skillName, int pageNo, int pageSize) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
skillNamestringSkill 名称模式过滤。
searchstring搜索模式：accurate 精确 或 blur 模糊。
orderBystring排序字段（可选）。
ownerstring资源所有者过滤（可选）。
scopestring可见范围过滤（可选）。
bizTagstring业务标签过滤（可选）。
pageNoint页码。
pageSizeint每页条数。

返回参数

参数类型描述
Page<SkillSummary>Skill 分页列表。

SkillSummary.writable 表示当前请求者是否可以修改该 Skill。

请求示例

try {
    SkillMaintainerService skillMaintainerService = aiMaintainerService.skill();
    Page<SkillSummary> result = skillMaintainerService.listSkills("public", "my-skill", "blur", 1, 100);
    result = skillMaintainerService.listSkills("public", "my-skill", "blur", "download_count", "nacos", "PUBLIC", 1, 100);
    result = skillMaintainerService.listSkills("public", "my-skill", "blur", "download_count", "nacos", "PUBLIC", "ops", 1, 100);
    result = skillMaintainerService.listSkills("my-skill", 1, 100);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

9.3. 从 ZIP 上传 Skill

描述

从 ZIP 字节流在指定命名空间下上传并注册 Skill。

String uploadSkillFromZip(String namespaceId, byte[] zipBytes, boolean overwrite) throws NacosException;


String uploadSkillFromZip(String namespaceId, byte[] zipBytes, boolean overwrite, String targetVersion) throws NacosException;


String uploadSkillFromZip(String namespaceId, byte[] zipBytes, boolean overwrite, String targetVersion, String commitMsg) throws NacosException;


String uploadSkillFromZip(String namespaceId, byte[] zipBytes, boolean overwrite, String targetVersion, String commitMsg, String uploadAction) throws NacosException;


String uploadSkillFromZip(String namespaceId, byte[] zipBytes) throws NacosException;


String uploadSkillFromZip(byte[] zipBytes) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
zipBytesbyte[]Skill 的 ZIP 包字节。
overwritebooleanSkill 已存在时是否覆盖当前可编辑草稿。
targetVersionstring目标版本（可选，当 ZIP 中未包含版本时作为兜底）。
commitMsgstring版本提交说明（可选）。
uploadActionstring前置检查后选择的上传动作（可选）：CREATE_DRAFT、OVERWRITE_DRAFT 或 DELETE_DRAFT_AND_CREATE。

返回参数

参数类型描述
StringSkill 名称。

请求示例

try {
    SkillMaintainerService skillMaintainerService = aiMaintainerService.skill();
    byte[] zipBytes = Files.readAllBytes(Paths.get("my-skill.zip"));
    String name = skillMaintainerService.uploadSkillFromZip("public", zipBytes, true);
    name = skillMaintainerService.uploadSkillFromZip("public", zipBytes, true, "1.0.1");
    name = skillMaintainerService.uploadSkillFromZip("public", zipBytes, true, "1.0.1", "upload skill");
    // 前置检查要求明确处理草稿冲突时，可改用：
    // String name = skillMaintainerService.uploadSkillFromZip("public", zipBytes, true, "1.0.1", "upload skill", "OVERWRITE_DRAFT");
    name = skillMaintainerService.uploadSkillFromZip("public", zipBytes);
    name = skillMaintainerService.uploadSkillFromZip(zipBytes);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

9.4. 获取 Skill 元信息

描述

获取 Skill 的元信息（支持默认命名空间和指定命名空间）。

SkillMeta getSkillMeta(String skillName) throws NacosException;


SkillMeta getSkillMeta(String namespaceId, String skillName) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
skillNamestringSkill 名称。

返回参数

参数类型描述
SkillMetaSkill 元信息。

请求示例

try {
    SkillMaintainerService skillMaintainerService = aiMaintainerService.skill();
    SkillMeta meta = skillMaintainerService.getSkillMeta("my-skill");
    meta = skillMaintainerService.getSkillMeta("public", "my-skill");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

9.5. 获取 Skill 指定版本详情

描述

查询 Skill 指定版本的完整详情。

Skill getSkillVersionDetail(String skillName, String version) throws NacosException;


Skill getSkillVersionDetail(String namespaceId, String skillName, String version) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
skillNamestringSkill 名称。
versionstringSkill 版本。

返回参数

参数类型描述
Skill指定版本的 Skill 详情对象。

请求示例

try {
    SkillMaintainerService skillMaintainerService = aiMaintainerService.skill();
    Skill detail = skillMaintainerService.getSkillVersionDetail("my-skill", "1.0.0");
    detail = skillMaintainerService.getSkillVersionDetail("public", "my-skill", "1.0.0");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

9.6. 创建 Skill 草稿

描述

创建新的 Skill 草稿，支持从现有版本 fork 并可指定目标版本。

String createDraft(String namespaceId, String skillCard) throws NacosException;


String createDraft(String namespaceId, String skillName, String basedOnVersion) throws NacosException;


String createDraft(String namespaceId, String skillName, String basedOnVersion, String targetVersion) throws NacosException;


String createDraft(String namespaceId, String skillName, String basedOnVersion, String targetVersion, String skillCard) throws NacosException;


String createDraft(String namespaceId, String skillName, String basedOnVersion, String targetVersion, String skillCard, String commitMsg) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
skillNamestringSkill 名称（fork 时必填）。
basedOnVersionstringfork 基于的版本（可选）。
targetVersionstring目标草稿版本（可选）。
skillCardstringSkill 完整 JSON（非 fork 场景通常必填）。
commitMsgstring版本提交说明（可选）。

返回参数

参数类型描述
String创建出的草稿版本号。

请求示例

try {
    SkillMaintainerService skillMaintainerService = aiMaintainerService.skill();
    String version = skillMaintainerService.createDraft("public", "{\"name\":\"my-skill\"}");
    version = skillMaintainerService.createDraft("public", "my-skill", "1.0.0");
    version = skillMaintainerService.createDraft("public", "my-skill", "1.0.0", "1.0.1-draft");
    version = skillMaintainerService.createDraft("public", "my-skill", "1.0.0", "1.0.1-draft", "{\"name\":\"my-skill\"}");
    version = skillMaintainerService.createDraft("public", "my-skill", "1.0.0", "1.0.1-draft", "{\"name\":\"my-skill\"}", "update skill");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

9.7. 更新 Skill 草稿

描述

更新当前 Skill 草稿内容。

boolean updateDraft(String namespaceId, String skillCard, Boolean setAsLatest) throws NacosException;


boolean updateDraft(String namespaceId, String skillCard, Boolean setAsLatest, String commitMsg) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
skillCardstringSkill 完整 JSON。
setAsLatestboolean是否设为 latest 标签（可选）。
commitMsgstring版本提交说明（可选）。

返回参数

参数类型描述
boolean更新是否成功。

请求示例

try {
    SkillMaintainerService skillMaintainerService = aiMaintainerService.skill();
    boolean ok = skillMaintainerService.updateDraft("public", "{\"name\":\"my-skill\"}", true);
    ok = skillMaintainerService.updateDraft("public", "{\"name\":\"my-skill\"}", true, "update skill");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

9.8. 删除 Skill 草稿

描述

删除指定 Skill 的当前草稿版本。

boolean deleteDraft(String namespaceId, String skillName) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
skillNamestringSkill 名称。

返回参数

参数类型描述
boolean删除是否成功。

请求示例

try {
    SkillMaintainerService skillMaintainerService = aiMaintainerService.skill();
    boolean ok = skillMaintainerService.deleteDraft("public", "my-skill");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

9.9. 提交 Skill 版本审核

描述

提交 Skill 指定版本进入发布审核流程。

String submit(String namespaceId, String skillName, String version) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
skillNamestringSkill 名称。
versionstring版本号（可选，服务端可自动选择当前草稿）。

返回参数

参数类型描述
String提交结果（如 pipelineId）。

请求示例

try {
    SkillMaintainerService skillMaintainerService = aiMaintainerService.skill();
    String result = skillMaintainerService.submit("public", "my-skill", "1.0.1");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

9.10. 发布 Skill 版本

描述

发布审核通过的 Skill 版本。latest 标签由服务端管理。

boolean publish(String namespaceId, String skillName, String version, Boolean updateLatestLabel) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
skillNamestringSkill 名称。
versionstring待发布版本。
updateLatestLabelboolean兼容保留参数，服务端忽略该值。

返回参数

参数类型描述
boolean发布是否成功。

请求示例

try {
    SkillMaintainerService skillMaintainerService = aiMaintainerService.skill();
    boolean ok = skillMaintainerService.publish("public", "my-skill", "1.0.1", false);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

9.11. 强制发布 Skill 版本

描述

跳过审核流程强制发布 Skill 版本。

boolean forcePublish(String namespaceId, String skillName, String version, Boolean updateLatestLabel) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
skillNamestringSkill 名称。
versionstring待发布版本。
updateLatestLabelboolean兼容保留参数，服务端忽略该值。

返回参数

参数类型描述
boolean强制发布是否成功。

请求示例

try {
    SkillMaintainerService skillMaintainerService = aiMaintainerService.skill();
    boolean ok = skillMaintainerService.forcePublish("public", "my-skill", "1.0.1", false);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

9.12. 更新 Skill 运行标签

描述

更新 Skill 的运行标签映射（labels JSON）。

boolean updateLabels(String namespaceId, String skillName, String labels) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
skillNamestringSkill 名称。
labelsstringlabels JSON。

返回参数

参数类型描述
boolean更新是否成功。

请求示例

try {
    SkillMaintainerService skillMaintainerService = aiMaintainerService.skill();
    boolean ok = skillMaintainerService.updateLabels("public", "my-skill", "{\"stable\":\"1.0.1\"}");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

9.13. 更新 Skill 业务标签

描述

更新 Skill 的业务标签（bizTags JSON）。

boolean updateBizTags(String namespaceId, String skillName, String bizTags) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
skillNamestringSkill 名称。
bizTagsstringbizTags JSON。

返回参数

参数类型描述
boolean更新是否成功。

请求示例

try {
    SkillMaintainerService skillMaintainerService = aiMaintainerService.skill();
    boolean ok = skillMaintainerService.updateBizTags("public", "my-skill", "[\"ai\",\"ops\"]");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

9.14. 变更 Skill 上下线状态

描述

对 Skill 或指定版本进行上线/下线操作。

boolean changeOnlineStatus(String namespaceId, String skillName, String scope, String version, boolean online) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
skillNamestringSkill 名称。
scopestring作用域，skill 表示 Skill 级，其它值表示版本级。
versionstring版本号（版本级操作时使用）。
onlinebooleantrue 上线，false 下线。

返回参数

参数类型描述
boolean操作是否成功。

请求示例

try {
    SkillMaintainerService skillMaintainerService = aiMaintainerService.skill();
    boolean ok = skillMaintainerService.changeOnlineStatus("public", "my-skill", "skill", null, true);
    ok = skillMaintainerService.changeOnlineStatus("public", "my-skill", "version", "1.0.1", false);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

9.15. 更新 Skill 可见范围

描述

更新 Skill 的可见范围（如 PUBLIC / PRIVATE）。

boolean updateScope(String namespaceId, String skillName, String scope) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
skillNamestringSkill 名称。
scopestring可见范围。

返回参数

参数类型描述
boolean更新是否成功。

请求示例

try {
    SkillMaintainerService skillMaintainerService = aiMaintainerService.skill();
    boolean ok = skillMaintainerService.updateScope("public", "my-skill", "PUBLIC");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

9.16. 批量从 ZIP 上传 Skill

描述

从包含多个 Skill 目录的 ZIP 包中批量上传 Skill。

BatchUploadResult batchUploadSkillsFromZip(byte[] zipBytes) throws NacosException;


BatchUploadResult batchUploadSkillsFromZip(String namespaceId, byte[] zipBytes, boolean overwrite) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
zipBytesbyte[]包含多个 Skill 目录的 ZIP 包字节。
overwriteboolean是否覆盖已存在的草稿。

返回参数

参数类型描述
BatchUploadResult批量上传结果，包含逐项结构化结果及兼容字段。

BatchUploadResult 的主要字段如下：

参数名参数类型描述
resultsList<BatchUploadItemResult>每个 Skill 或候选目录的结构化处理结果。
succeededList<String>上传成功的 Skill 名称列表（兼容字段）。
failedList<FailedItem>上传失败的 Skill 列表（兼容字段）。

BatchUploadItemResult 包含 name、success、errorCode、errorMessage 和 owner 字段。

请求示例

try {
    SkillMaintainerService skillMaintainerService = aiMaintainerService.skill();
    byte[] zipBytes = Files.readAllBytes(Paths.get("skills.zip"));
    BatchUploadResult result = skillMaintainerService.batchUploadSkillsFromZip(zipBytes);
    result = skillMaintainerService.batchUploadSkillsFromZip("public", zipBytes, true);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

9.17. 重新编辑 Skill 版本

描述

将已审核的 Skill 版本重新转回草稿状态，以便继续编辑。

boolean redraft(String namespaceId, String skillName, String version) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
skillNamestringSkill 名称。
versionstring需要重新编辑的版本。

返回参数

参数类型描述
boolean重新转草稿是否成功。

请求示例

try {
    SkillMaintainerService skillMaintainerService = aiMaintainerService.skill();
    boolean ok = skillMaintainerService.redraft("public", "my-skill", "1.0.1");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

操作失败时抛出 NacosException 异常。

9.18. Skill ZIP 上传前置检查

描述

在实际上传前检查 ZIP 中的一个或多个 Skill，返回版本冲突、权限和可执行上传动作等逐项结果。调用者可根据前置检查结果选择 uploadSkillFromZip 的 uploadAction。

List<SkillUploadPrecheckResult> precheckUploadSkillFromZip(byte[] zipBytes) throws NacosException;


List<SkillUploadPrecheckResult> precheckUploadSkillFromZip(String namespaceId, byte[] zipBytes) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间 ID；省略时使用默认命名空间 public。
zipBytesbyte[]单个或多个 Skill 的 ZIP 包字节。

返回参数

参数类型描述
List<SkillUploadPrecheckResult>ZIP 中每个 Skill 或候选目录的前置检查结果。

SkillUploadPrecheckResult 的主要字段如下：

参数名参数类型描述
namespaceIdstring命名空间 ID。
entryPathstringZIP 中的候选目录路径。
skillNamestring识别出的 Skill 名称。
reasonstring检查结果说明。
ownerstring已存在 Skill 的所有者。
maxPublishedVersionstring当前最大已发布版本。
parsedVersionstring从 ZIP 内容解析出的版本。
targetVersionstring前置检查确定的目标版本。
existsbooleanSkill 是否已存在。
editingVersionstring当前草稿版本。
reviewingVersionstring当前审核中版本。
precheckCodestring检查码，如 READY、VERSION_ADJUSTED、DRAFT_EXISTS、REVIEWING_EXISTS、NO_PERMISSION、NOT_A_SKILL 或 INVALID_SKILL。

请求示例

try {
    SkillMaintainerService skillMaintainerService = aiMaintainerService.skill();
    byte[] zipBytes = Files.readAllBytes(Paths.get("skills.zip"));
    List<SkillUploadPrecheckResult> results = skillMaintainerService.precheckUploadSkillFromZip(zipBytes);
    results = skillMaintainerService.precheckUploadSkillFromZip("public", zipBytes);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

前置检查请求发生非预期失败时抛出 NacosException 异常；业务检查不通过的信息通过逐项结果返回。

10. AgentSpec 能力

10.1. 查询 AgentSpec 详情

描述

查询 AgentSpec 当前详情。

AgentSpec getAgentSpecDetail(String namespaceId, String agentSpecName) throws NacosException;
AgentSpec getAgentSpecDetail(String agentSpecName) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
agentSpecNamestringAgentSpec 名称。

返回参数

参数类型描述
AgentSpecAgentSpec 详情对象。

请求示例

try {
    AgentSpecMaintainerService agentSpecMaintainerService = aiMaintainerService.agentSpec();
    AgentSpec detail = agentSpecMaintainerService.getAgentSpecDetail("public", "test-agent-spec");
    detail = agentSpecMaintainerService.getAgentSpecDetail("test-agent-spec");
} catch (NacosException e) {
    e.printStackTrace();
}

10.2. 查询 AgentSpec 管理详情

描述

查询 AgentSpec 管理面元数据详情。

AgentSpecMeta getAgentSpecAdminDetail(String namespaceId, String agentSpecName) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
agentSpecNamestringAgentSpec 名称。

返回参数

参数类型描述
AgentSpecMetaAgentSpec 管理元信息对象。

请求示例

try {
    AgentSpecMaintainerService agentSpecMaintainerService = aiMaintainerService.agentSpec();
    AgentSpecMeta meta = agentSpecMaintainerService.getAgentSpecAdminDetail("public", "test-agent-spec");
} catch (NacosException e) {
    e.printStackTrace();
}

10.3. 查询 AgentSpec 指定版本详情

描述

查询 AgentSpec 指定版本详情。

AgentSpec getAgentSpecVersionDetail(String namespaceId, String agentSpecName, String version) throws NacosException;
AgentSpec getAgentSpecVersionDetail(String agentSpecName, String version) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
agentSpecNamestringAgentSpec 名称。
versionstringAgentSpec 版本。

返回参数

参数类型描述
AgentSpecAgentSpec 指定版本详情对象。

请求示例

try {
    AgentSpecMaintainerService agentSpecMaintainerService = aiMaintainerService.agentSpec();
    AgentSpec detail = agentSpecMaintainerService.getAgentSpecVersionDetail("public", "test-agent-spec", "1.0.0");
    detail = agentSpecMaintainerService.getAgentSpecVersionDetail("test-agent-spec", "1.0.0");
} catch (NacosException e) {
    e.printStackTrace();
}

10.4. 删除 AgentSpec

描述

删除指定 AgentSpec。

boolean deleteAgentSpec(String namespaceId, String agentSpecName) throws NacosException;
boolean deleteAgentSpec(String agentSpecName) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
agentSpecNamestringAgentSpec 名称。

返回参数

参数类型描述
boolean删除是否成功。

请求示例

try {
    AgentSpecMaintainerService agentSpecMaintainerService = aiMaintainerService.agentSpec();
    boolean ok = agentSpecMaintainerService.deleteAgentSpec("public", "test-agent-spec");
    ok = agentSpecMaintainerService.deleteAgentSpec("test-agent-spec");
} catch (NacosException e) {
    e.printStackTrace();
}

10.5. 分页查询 AgentSpec 列表

描述

分页查询 AgentSpec 基础列表。

Page<AgentSpecBasicInfo> listAgentSpecs(String namespaceId, String agentSpecName, String search, int pageNo, int pageSize) throws NacosException;
Page<AgentSpecBasicInfo> listAgentSpecs(String agentSpecName, int pageNo, int pageSize) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
agentSpecNamestringAgentSpec 名称模式。
searchstring搜索模式：accurate 或 blur。
pageNoint页码。
pageSizeint每页条数。

返回参数

参数类型描述
Page<AgentSpecBasicInfo>AgentSpec 基础分页列表。

请求示例

try {
    AgentSpecMaintainerService agentSpecMaintainerService = aiMaintainerService.agentSpec();
    Page<AgentSpecBasicInfo> list = agentSpecMaintainerService.listAgentSpecs("public", "test-agent-spec", "blur", 1, 100);
    list = agentSpecMaintainerService.listAgentSpecs("test-agent-spec", 1, 100);
} catch (NacosException e) {
    e.printStackTrace();
}

10.6. 分页查询 AgentSpec 管理列表

描述

分页查询 AgentSpec 管理列表（含治理信息）。

Page<AgentSpecSummary> listAgentSpecAdminItems(String namespaceId, String agentSpecName, String search, int pageNo, int pageSize) throws NacosException;


Page<AgentSpecSummary> listAgentSpecAdminItems(String namespaceId, String agentSpecName, String search, String orderBy, String owner, String scope, int pageNo, int pageSize) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
agentSpecNamestringAgentSpec 名称模式。
searchstring搜索模式：accurate 或 blur。
orderBystring排序字段（可选）。
ownerstring资源所有者过滤（可选）。
scopestring可见范围过滤（可选）。
pageNoint页码。
pageSizeint每页条数。

返回参数

参数类型描述
Page<AgentSpecSummary>AgentSpec 管理分页列表。

AgentSpecSummary.owner 表示资源所有者，AgentSpecSummary.writable 表示当前请求者是否可以修改该 AgentSpec。

请求示例

try {
    AgentSpecMaintainerService agentSpecMaintainerService = aiMaintainerService.agentSpec();
    Page<AgentSpecSummary> adminList = agentSpecMaintainerService.listAgentSpecAdminItems("public", "test-agent-spec", "blur", 1, 100);
    adminList = agentSpecMaintainerService.listAgentSpecAdminItems("public", "test-agent-spec", "blur", "download_count", "nacos", "PUBLIC", 1, 100);
} catch (NacosException e) {
    e.printStackTrace();
}

10.7. 从 ZIP 上传 AgentSpec

描述

从 ZIP 字节流上传 AgentSpec。

String uploadAgentSpecFromZip(String namespaceId, byte[] zipBytes, boolean overwrite) throws NacosException;
String uploadAgentSpecFromZip(String namespaceId, byte[] zipBytes) throws NacosException;
String uploadAgentSpecFromZip(byte[] zipBytes) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
zipBytesbyte[]AgentSpec ZIP 包字节流。
overwritebooleanAgentSpec 已存在时是否覆盖当前可编辑草稿。

返回参数

参数类型描述
StringAgentSpec 名称。

请求示例

try {
    AgentSpecMaintainerService agentSpecMaintainerService = aiMaintainerService.agentSpec();
    byte[] zipBytes = Files.readAllBytes(Paths.get("test-agent-spec.zip"));
    String name = agentSpecMaintainerService.uploadAgentSpecFromZip("public", zipBytes, true);
    name = agentSpecMaintainerService.uploadAgentSpecFromZip("public", zipBytes);
    name = agentSpecMaintainerService.uploadAgentSpecFromZip(zipBytes);
} catch (NacosException e) {
    e.printStackTrace();
}

10.8. 创建 AgentSpec 草稿

描述

基于已发布版本创建新的草稿版本。

String createDraft(String namespaceId, String agentSpecName, String basedOnVersion) throws NacosException;


String createDraft(String namespaceId, String agentSpecName, String basedOnVersion, String targetVersion) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
agentSpecNamestringAgentSpec 名称。
basedOnVersionstring基于版本（可选）。
targetVersionstring目标草稿版本（可选，空时自动递增）。

返回参数

参数类型描述
String创建出的草稿版本号。

请求示例

try {
    AgentSpecMaintainerService agentSpecMaintainerService = aiMaintainerService.agentSpec();
    String version = agentSpecMaintainerService.createDraft("public", "test-agent-spec", "1.0.0");
    version = agentSpecMaintainerService.createDraft("public", "test-agent-spec", "1.0.0", "1.0.1-draft");
} catch (NacosException e) {
    e.printStackTrace();
}

10.9. 更新 AgentSpec 草稿

描述

更新当前草稿内容。

boolean updateDraft(String namespaceId, String agentSpecCard, Boolean setAsLatest) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
agentSpecCardstringAgentSpec 完整 JSON。
setAsLatestboolean是否更新 latest 标签。

返回参数

参数类型描述
boolean更新是否成功。

请求示例

try {
    AgentSpecMaintainerService agentSpecMaintainerService = aiMaintainerService.agentSpec();
    boolean ok = agentSpecMaintainerService.updateDraft("public", "{\"name\":\"test-agent-spec\"}", true);
} catch (NacosException e) {
    e.printStackTrace();
}

10.10. 删除 AgentSpec 草稿

描述

删除当前草稿版本。

boolean deleteDraft(String namespaceId, String agentSpecName) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
agentSpecNamestringAgentSpec 名称。

返回参数

参数类型描述
boolean删除是否成功。

请求示例

try {
    AgentSpecMaintainerService agentSpecMaintainerService = aiMaintainerService.agentSpec();
    boolean ok = agentSpecMaintainerService.deleteDraft("public", "test-agent-spec");
} catch (NacosException e) {
    e.printStackTrace();
}

10.11. 提交 AgentSpec 版本

描述

提交 AgentSpec 版本进入审核流程。

String submit(String namespaceId, String agentSpecName, String version) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
agentSpecNamestringAgentSpec 名称。
versionstring目标版本。

返回参数

参数类型描述
String提交结果（如 pipelineId）。

请求示例

try {
    AgentSpecMaintainerService agentSpecMaintainerService = aiMaintainerService.agentSpec();
    String result = agentSpecMaintainerService.submit("public", "test-agent-spec", "1.0.1");
} catch (NacosException e) {
    e.printStackTrace();
}

10.12. 发布 AgentSpec 版本

描述

发布指定 AgentSpec 版本。latest 标签由服务端管理。

boolean publish(String namespaceId, String agentSpecName, String version, Boolean updateLatestLabel) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
agentSpecNamestringAgentSpec 名称。
versionstring目标版本。
updateLatestLabelboolean兼容保留参数，服务端忽略该值。

返回参数

参数类型描述
boolean发布是否成功。

请求示例

try {
    AgentSpecMaintainerService agentSpecMaintainerService = aiMaintainerService.agentSpec();
    boolean ok = agentSpecMaintainerService.publish("public", "test-agent-spec", "1.0.1", false);
} catch (NacosException e) {
    e.printStackTrace();
}

10.13. 强制发布 AgentSpec 版本

描述

强制发布指定 AgentSpec 版本。latest 标签由服务端管理。

boolean forcePublish(String namespaceId, String agentSpecName, String version, Boolean updateLatestLabel) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
agentSpecNamestringAgentSpec 名称。
versionstring目标版本。
updateLatestLabelboolean兼容保留参数，服务端忽略该值。

返回参数

参数类型描述
boolean强制发布是否成功。

请求示例

try {
    AgentSpecMaintainerService agentSpecMaintainerService = aiMaintainerService.agentSpec();
    boolean ok = agentSpecMaintainerService.forcePublish("public", "test-agent-spec", "1.0.1", false);
} catch (NacosException e) {
    e.printStackTrace();
}

10.14. 更新 AgentSpec Labels

描述

更新 AgentSpec 的 labels JSON。

boolean updateLabels(String namespaceId, String agentSpecName, String labels) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
agentSpecNamestringAgentSpec 名称。
labelsstringlabels JSON。

返回参数

参数类型描述
boolean更新是否成功。

请求示例

try {
    AgentSpecMaintainerService agentSpecMaintainerService = aiMaintainerService.agentSpec();
    boolean ok = agentSpecMaintainerService.updateLabels("public", "test-agent-spec", "{\"latest\":\"1.0.1\"}");
} catch (NacosException e) {
    e.printStackTrace();
}

10.15. 更新 AgentSpec 业务标签

描述

更新 AgentSpec 的 bizTags JSON。

boolean updateBizTags(String namespaceId, String agentSpecName, String bizTags) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
agentSpecNamestringAgentSpec 名称。
bizTagsstringbizTags JSON。

返回参数

参数类型描述
boolean更新是否成功。

请求示例

try {
    AgentSpecMaintainerService agentSpecMaintainerService = aiMaintainerService.agentSpec();
    boolean ok = agentSpecMaintainerService.updateBizTags("public", "test-agent-spec", "[\"ai\",\"ops\"]");
} catch (NacosException e) {
    e.printStackTrace();
}

10.16. 变更 AgentSpec 上下线状态

描述

按 AgentSpec 或版本维度执行上下线。

boolean changeOnlineStatus(String namespaceId, String agentSpecName, String scope, String version, boolean online) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
agentSpecNamestringAgentSpec 名称。
scopestring作用域（如 agentspec 或 version）。
versionstring版本号（版本级操作时使用）。
onlinebooleantrue 上线，false 下线。

返回参数

参数类型描述
boolean操作是否成功。

请求示例

try {
    AgentSpecMaintainerService agentSpecMaintainerService = aiMaintainerService.agentSpec();
    boolean ok = agentSpecMaintainerService.changeOnlineStatus("public", "test-agent-spec", "agentspec", null, true);
    ok = agentSpecMaintainerService.changeOnlineStatus("public", "test-agent-spec", "version", "1.0.1", false);
} catch (NacosException e) {
    e.printStackTrace();
}

10.17. 更新 AgentSpec 可见范围

描述

更新 AgentSpec 的可见范围（如 PUBLIC / PRIVATE）。

boolean updateScope(String namespaceId, String agentSpecName, String scope) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
agentSpecNamestringAgentSpec 名称。
scopestring可见范围。

返回参数

参数类型描述
boolean更新是否成功。

请求示例

try {
    AgentSpecMaintainerService agentSpecMaintainerService = aiMaintainerService.agentSpec();
    boolean ok = agentSpecMaintainerService.updateScope("public", "test-agent-spec", "PUBLIC");
} catch (NacosException e) {
    e.printStackTrace();
}

10.18. 查询 AgentSpec 指定版本元信息

描述

查询 AgentSpec 指定版本元信息，返回主配置及仅包含名称和类型的资源列表，避免读取完整资源内容。

AgentSpec getAgentSpecVersionMeta(String namespaceId, String agentSpecName, String version) throws NacosException;
AgentSpec getAgentSpecVersionMeta(String agentSpecName, String version) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
agentSpecNamestringAgentSpec 名称。
versionstringAgentSpec 版本。

返回参数

参数类型描述
AgentSpecAgentSpec 指定版本元信息。

请求示例

try {
    AgentSpecMaintainerService agentSpecMaintainerService = aiMaintainerService.agentSpec();
    AgentSpec meta = agentSpecMaintainerService.getAgentSpecVersionMeta("public", "test-agent-spec", "1.0.0");
    meta = agentSpecMaintainerService.getAgentSpecVersionMeta("test-agent-spec", "1.0.0");
} catch (NacosException e) {
    e.printStackTrace();
}

10.19. 重新编辑 AgentSpec 版本

描述

将已审核的 AgentSpec 版本重新转回草稿状态，以便继续编辑。

boolean redraft(String namespaceId, String agentSpecName, String version) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间ID。
agentSpecNamestringAgentSpec 名称。
versionstring需要重新编辑的版本。

返回参数

参数类型描述
boolean重新转草稿是否成功。

请求示例

try {
    AgentSpecMaintainerService agentSpecMaintainerService = aiMaintainerService.agentSpec();
    boolean ok = agentSpecMaintainerService.redraft("public", "test-agent-spec", "1.0.1");
} catch (NacosException e) {
    e.printStackTrace();
}

11. Agent 管理

Agent 管理是协议无关的新主入口，未来将替代旧的 A2A 管理 API。兼容期内 aiMaintainerService.a2a() 仍可使用；新接入的用户和 SDK 应优先兼容 aiMaintainerService.agent() 返回的 AgentMaintainerService。

AgentMaintainerService 不绑定命名空间。每个操作均提供显式 namespaceId 的形式和使用默认命名空间 public 的便利重载；Request 和 Command 对象自身不包含 namespaceId。Agent 定义没有独立的创建方法，首次调用 createDraft 会同时创建 Agent 元数据和第一个草稿版本。

本章请求模型位于 com.alibaba.nacos.api.ai.model.agent.admin 包，返回值和端点模型位于 com.alibaba.nacos.api.ai.model.agent 包。示例中的 JSON 工具类为 com.alibaba.nacos.api.utils.json.JsonUtils。

注意：本章与第 7 章的 com.alibaba.nacos.api.ai.model.a2a 包中有 AgentVersionDetail 等同名类型，导入时请确认包名。

11.1. 获取 Agent 概览

描述

获取 Agent 元数据和首个有界版本摘要分页。

AgentOverview getAgent(String namespaceId, String agentName) throws NacosException;


AgentOverview getAgent(String agentName) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间 ID；省略时使用默认命名空间 public。
agentNamestring精确的 Agent 名称。

返回参数

参数类型描述
AgentOverviewAgent 概览，包含 agent 元数据和 versionPage 版本摘要分页。

agent 的类型为 AgentSummary，包含资源元数据、status、owner、scope 和 versionInfo。在线版本从 versionInfo.onlineVersions 读取，默认版本从 versionInfo.labels.latest 读取。

请求示例

try {
    AgentMaintainerService agentMaintainerService = aiMaintainerService.agent();
    AgentOverview overview = agentMaintainerService.getAgent("public", "demo-agent");
    overview = agentMaintainerService.getAgent("demo-agent");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求失败时抛出 NacosException 异常。

11.2. 更新 Agent 元数据

描述

完整替换 Agent 的可写元数据。可修改展示字段、标签、扩展信息和启停状态，但不能修改身份、所有者、可见范围、版本内容、版本标签或派生版本目录。

AgentSummary updateAgent(String namespaceId, AgentUpdateRequest request) throws NacosException;


AgentSummary updateAgent(AgentUpdateRequest request) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间 ID；省略时使用默认命名空间 public。
requestAgentUpdateRequestAgent 元数据更新请求。

AgentUpdateRequest 的字段如下：

参数名参数类型描述
agentNamestringAgent 名称，必填。
displayNamestring展示名称。
descriptionstring描述。
iconUrlstring图标 URL。
providerAgentProvider提供者信息，包含 name 和 url。
tagsList<String>Agent 标签。
extensionsMap<String, Object>扩展属性。
statusstring可写状态，必填；仅支持 enable 或 disable。

返回参数

参数类型描述
AgentSummary更新后的 Agent 摘要。

请求示例

try {
    AgentMaintainerService agentMaintainerService = aiMaintainerService.agent();
    AgentUpdateRequest request = new AgentUpdateRequest();
    request.setAgentName("demo-agent");
    request.setDisplayName("Demo Agent");
    request.setDescription("Agent for SDK examples");
    request.setTags(Arrays.asList("demo", "java"));
    request.setStatus("enable");
    AgentSummary agent = agentMaintainerService.updateAgent("public", request);
    // 使用默认命名空间时，可改用：AgentSummary agent = agentMaintainerService.updateAgent(request);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求参数无效或更新失败时抛出 NacosException 异常。

11.3. 删除 Agent

描述

删除 Agent 定义及其全部版本内容。该操作不会删除由独立 Publisher 持有的运行时发布。

void deleteAgent(String namespaceId, String agentName) throws NacosException;


void deleteAgent(String agentName) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间 ID；省略时使用默认命名空间 public。
agentNamestring精确的 Agent 名称。

返回参数

无返回值。

请求示例

try {
    AgentMaintainerService agentMaintainerService = aiMaintainerService.agent();
    agentMaintainerService.deleteAgent("public", "demo-agent");
    // 使用默认命名空间时，可改用：agentMaintainerService.deleteAgent("demo-agent");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

删除失败时抛出 NacosException 异常。

11.4. 分页查询 Agent

描述

按名称、业务标签、可见范围和所有者筛选 Agent 摘要，并进行稳定分页。名称和单个业务标签使用模糊匹配。

Page<AgentSummary> listAgents(String namespaceId, String agentName, String bizTag, String scope, String owner, String orderBy, int pageNo, int pageSize) throws NacosException;


Page<AgentSummary> listAgents(String agentName, String bizTag, String scope, String owner, String orderBy, int pageNo, int pageSize) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间 ID；省略时使用默认命名空间 public。
agentNamestringAgent 名称模糊过滤条件（可选）。
bizTagstring单个业务标签模糊过滤条件（可选）。
scopestring可见范围过滤条件（可选）。
ownerstring所有者过滤条件（可选）。
orderBystring排序字段（可选）；首版支持 download_count。
pageNoint页码。
pageSizeint每页数量。

返回参数

参数类型描述
Page<AgentSummary>Agent 摘要分页结果。

请求示例

try {
    AgentMaintainerService agentMaintainerService = aiMaintainerService.agent();
    Page<AgentSummary> page = agentMaintainerService.listAgents(
            "public", "demo", "java", "PUBLIC", null, "download_count", 1, 20);
    page = agentMaintainerService.listAgents(
            "demo", "java", "PUBLIC", null, "download_count", 1, 20);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

查询失败时抛出 NacosException 异常。

11.5. 分页查询 Agent 版本

描述

分页查询指定 Agent 的版本摘要，可按版本状态过滤。

Page<AgentVersionSummary> listAgentVersions(String namespaceId, String agentName, String status, int pageNo, int pageSize) throws NacosException;


Page<AgentVersionSummary> listAgentVersions(String agentName, String status, int pageNo, int pageSize) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间 ID；省略时使用默认命名空间 public。
agentNamestring精确的 Agent 名称。
statusstring版本状态过滤条件（可选）。
pageNoint页码。
pageSizeint每页数量。

返回参数

参数类型描述
Page<AgentVersionSummary>Agent 版本摘要分页结果。

请求示例

try {
    AgentMaintainerService agentMaintainerService = aiMaintainerService.agent();
    Page<AgentVersionSummary> page =
            agentMaintainerService.listAgentVersions("public", "demo-agent", "online", 1, 20);
    page = agentMaintainerService.listAgentVersions("demo-agent", null, 1, 20);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

查询失败时抛出 NacosException 异常。

11.6. 获取 Agent 指定版本

描述

获取一个精确版本的 Agent 定义。

AgentVersionDetail getAgentVersion(String namespaceId, String agentName, String version) throws NacosException;


AgentVersionDetail getAgentVersion(String agentName, String version) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间 ID；省略时使用默认命名空间 public。
agentNamestring精确的 Agent 名称。
versionstring精确版本。

返回参数

参数类型描述
AgentVersionDetail版本详情，包含状态、callInterfaces、作者、变更说明、内容摘要及时间信息。

请求示例

try {
    AgentMaintainerService agentMaintainerService = aiMaintainerService.agent();
    AgentVersionDetail detail =
            agentMaintainerService.getAgentVersion("public", "demo-agent", "1.0.0");
    detail = agentMaintainerService.getAgentVersion("demo-agent", "1.0.0");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

查询失败时抛出 NacosException 异常。

11.7. 获取 Agent 运行时端点

描述

查询 Agent 在指定协议下注册的运行端点。传入 version 时，只返回支持该定义版本的端点及其版本绑定；省略时返回全部端点及版本绑定。即使尚未创建 Agent 定义，也可以查询已注册的端点。

RuntimeEndpointSnapshot getRuntimeEndpoints(String namespaceId, String agentName, String protocol, String version) throws NacosException;


RuntimeEndpointSnapshot getRuntimeEndpoints(String agentName, String protocol, String version) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间 ID；省略时使用默认命名空间 public。
agentNamestring精确的 Agent 名称。
protocolstring协议标识，必填。
versionstringAgent 版本过滤条件（可选）。

返回参数

参数类型描述
RuntimeEndpointSnapshot包含 namespaceId、agentName、可选 version 和 callInterface。

callInterface 包含协议名称 protocol 和一个 source=RUNTIME 的端点集合。运行端点从 callInterface.endpointSets[0].endpoints 读取，没有实例时列表为空。每个端点的主要字段如下：

字段描述
uri、transport端点地址和传输方式。
priority、weight端点优先级和权重。
metadata端点元数据。
bindings版本绑定列表，每项包含运行版本 runtimeVersion 和兼容的定义版本范围 versionRange。
enabled、healthy端点的启用状态和健康状态。

端点集合的更新时间通过 EndpointSet.lastUpdatedTime 读取。

请求示例

try {
    AgentMaintainerService agentMaintainerService = aiMaintainerService.agent();
    RuntimeEndpointSnapshot snapshot =
            agentMaintainerService.getRuntimeEndpoints("public", "demo-agent", "a2a", "1.0.0");
    snapshot = agentMaintainerService.getRuntimeEndpoints("demo-agent", "a2a", null);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

查询失败时抛出 NacosException 异常。

11.8. 创建 Agent 草稿

描述

创建首个或后续 Agent 草稿。Agent 不存在时，此方法是唯一创建入口，请求必须直接提供 callInterfaces，不能使用 basedOnVersion；Agent 已存在时，可以直接提供 callInterfaces 或从一个精确的 basedOnVersion 复制，两者必须且只能选择一个。

createDraft 只创建草稿，包括 Agent 的第一个版本；创建后还需提交、审核和发布，流程见 AI 资源生命周期管理。展示名称、描述等元数据只在首次创建时填写，后续修改请使用 updateAgent。

AgentVersionDetail createDraft(String namespaceId, AgentDraftCreateRequest request) throws NacosException;


AgentVersionDetail createDraft(AgentDraftCreateRequest request) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间 ID；省略时使用默认命名空间 public。
requestAgentDraftCreateRequest草稿创建请求。

AgentDraftCreateRequest 的字段如下：

参数名参数类型描述
agentNamestringAgent 名称，必填。
displayNamestring首次创建时可选的展示名称。
descriptionstring首次创建时可选的描述。
iconUrlstring首次创建时可选的图标 URL。
providerAgentProvider首次创建时可选的提供者信息。
tagsList<String>首次创建时可选的标签。
extensionsMap<String, Object>首次创建时可选的扩展属性。
versionstring要创建的精确版本，必填。
callInterfacesList<AgentCallInterface>直接版本内容；与 basedOnVersion 二选一。
authorstring版本作者。
changeDescriptionstring版本变更说明。
basedOnVersionstring要复制的精确已有版本；与 callInterfaces 二选一。

返回参数

参数类型描述
AgentVersionDetail创建后的草稿详情。

请求示例

try {
    AgentMaintainerService agentMaintainerService = aiMaintainerService.agent();
    AgentCallInterface callInterface = new AgentCallInterface();
    callInterface.setProtocol("a2a");
    callInterface.setProtocolVersion("0.3.0");
    callInterface.setDescriptorMediaType("application/json");
    com.alibaba.nacos.api.ai.model.a2a.AgentCard a2aDescriptor =
            new com.alibaba.nacos.api.ai.model.a2a.AgentCard();
    a2aDescriptor.setName("demo-agent");
    a2aDescriptor.setDescription("Agent for SDK examples");
    a2aDescriptor.setUrl("https://example.com/a2a");
    a2aDescriptor.setVersion("1.0.0");
    a2aDescriptor.setProtocolVersion("0.3.0");
    a2aDescriptor.setPreferredTransport("JSONRPC");
    callInterface.setNativeDescriptor(JsonUtils.toObj(JsonUtils.toJson(a2aDescriptor), Map.class));
    callInterface.setEndpointSourceOrder(Arrays.asList(EndpointSource.RUNTIME, EndpointSource.DECLARED));
    Endpoint endpoint = new Endpoint();
    endpoint.setUri("https://example.com/a2a");
    endpoint.setTransport("JSONRPC");
    EndpointSet declared = new EndpointSet();
    declared.setSource(EndpointSource.DECLARED);
    declared.setEndpoints(Collections.singletonList(endpoint));
    callInterface.setEndpointSets(Collections.singletonList(declared));


    AgentDraftCreateRequest request = new AgentDraftCreateRequest();
    request.setAgentName("demo-agent");
    request.setDisplayName("Demo Agent");
    request.setVersion("1.0.0");
    request.setCallInterfaces(Collections.singletonList(callInterface));
    request.setAuthor("nacos");
    request.setChangeDescription("initial version");
    AgentVersionDetail draft = agentMaintainerService.createDraft("public", request);
    // 使用默认命名空间时，可改用：AgentVersionDetail draft = agentMaintainerService.createDraft(request);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求内容源不唯一、版本无效或创建失败时抛出 NacosException 异常。

11.9. 更新 Agent 草稿

描述

完整替换一个精确草稿的 CallInterface 内容和变更说明；不会创建缺失的 Agent 或版本，也不会修改 Agent 元数据。

需提交要保留的完整接口集合，遗漏的接口会被移除。定义中的 endpointSets 只能包含 DECLARED 地址；endpointSourceOrder 必须按偏好顺序各包含一次 RUNTIME 和 DECLARED。

AgentVersionDetail updateDraft(String namespaceId, AgentDraftUpdateRequest request) throws NacosException;


AgentVersionDetail updateDraft(AgentDraftUpdateRequest request) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间 ID；省略时使用默认命名空间 public。
requestAgentDraftUpdateRequest草稿更新请求。

AgentDraftUpdateRequest 包含必填的 agentName、精确 version 和非空 callInterfaces，以及可选的 changeDescription。

返回参数

参数类型描述
AgentVersionDetail更新后的草稿详情。

请求示例

try {
    AgentMaintainerService agentMaintainerService = aiMaintainerService.agent();
    AgentCallInterface callInterface = new AgentCallInterface();
    callInterface.setProtocol("a2a");
    callInterface.setProtocolVersion("0.3.0");
    callInterface.setDescriptorMediaType("application/json");
    com.alibaba.nacos.api.ai.model.a2a.AgentCard a2aDescriptor =
            new com.alibaba.nacos.api.ai.model.a2a.AgentCard();
    a2aDescriptor.setName("demo-agent");
    a2aDescriptor.setDescription("Updated Agent descriptor");
    a2aDescriptor.setUrl("https://example.com/a2a");
    a2aDescriptor.setVersion("1.0.0");
    a2aDescriptor.setProtocolVersion("0.3.0");
    a2aDescriptor.setPreferredTransport("JSONRPC");
    callInterface.setNativeDescriptor(JsonUtils.toObj(JsonUtils.toJson(a2aDescriptor), Map.class));
    callInterface.setEndpointSourceOrder(Arrays.asList(EndpointSource.RUNTIME, EndpointSource.DECLARED));
    Endpoint endpoint = new Endpoint();
    endpoint.setUri("https://example.com/a2a");
    endpoint.setTransport("JSONRPC");
    EndpointSet declared = new EndpointSet();
    declared.setSource(EndpointSource.DECLARED);
    declared.setEndpoints(Collections.singletonList(endpoint));
    callInterface.setEndpointSets(Collections.singletonList(declared));


    AgentDraftUpdateRequest request = new AgentDraftUpdateRequest();
    request.setAgentName("demo-agent");
    request.setVersion("1.0.0");
    request.setCallInterfaces(Collections.singletonList(callInterface));
    request.setChangeDescription("update descriptor");
    AgentVersionDetail draft = agentMaintainerService.updateDraft("public", request);
    // 使用默认命名空间时，可改用：AgentVersionDetail draft = agentMaintainerService.updateDraft(request);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

目标不是草稿、请求内容无效或更新失败时抛出 NacosException 异常。

11.10. 删除 Agent 草稿

描述

删除一个精确的 Agent 草稿版本。

void deleteDraft(String namespaceId, String agentName, String version) throws NacosException;


void deleteDraft(String agentName, String version) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间 ID；省略时使用默认命名空间 public。
agentNamestring精确的 Agent 名称。
versionstring精确的草稿版本。

返回参数

无返回值。

请求示例

try {
    AgentMaintainerService agentMaintainerService = aiMaintainerService.agent();
    agentMaintainerService.deleteDraft("public", "demo-agent", "1.0.0");
    // 使用默认命名空间时，可改用：agentMaintainerService.deleteDraft("demo-agent", "1.0.0");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

删除失败时抛出 NacosException 异常。

11.11. 提交 Agent 版本

描述

提交指定版本进行审核。配置了适用于 Agent 的发布流水线时，版本进入审核；否则直接发布。可通过返回值中的 status 查看提交后的状态。

AgentVersionSummary submit(String namespaceId, AgentVersionRequest command) throws NacosException;


AgentVersionSummary submit(AgentVersionRequest command) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间 ID；省略时使用默认命名空间 public。
commandAgentVersionRequest版本命令，包含必填的 agentName 和精确 version。

返回参数

参数类型描述
AgentVersionSummary转换后的版本摘要。

请求示例

try {
    AgentMaintainerService agentMaintainerService = aiMaintainerService.agent();
    AgentVersionRequest command = new AgentVersionRequest();
    command.setAgentName("demo-agent");
    command.setVersion("1.0.0");
    AgentVersionSummary summary = agentMaintainerService.submit("public", command);
    // 使用默认命名空间时，可改用：AgentVersionSummary summary = agentMaintainerService.submit(command);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

版本状态不允许转换或提交失败时抛出 NacosException 异常。

11.12. 发布 Agent 版本

描述

发布审核通过的 reviewed 版本。成功后状态为 online，latest 标签指向该版本。审核未通过时，可退回草稿修改后重新提交。

AgentVersionSummary publish(String namespaceId, AgentVersionRequest command) throws NacosException;


AgentVersionSummary publish(AgentVersionRequest command) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间 ID；省略时使用默认命名空间 public。
commandAgentVersionRequest版本命令，包含必填的 agentName 和精确 version。

返回参数

参数类型描述
AgentVersionSummary上线后的版本摘要。

请求示例

try {
    AgentMaintainerService agentMaintainerService = aiMaintainerService.agent();
    AgentVersionRequest command = new AgentVersionRequest();
    command.setAgentName("demo-agent");
    command.setVersion("1.0.0");
    AgentVersionSummary summary = agentMaintainerService.publish("public", command);
    // 使用默认命名空间时，可改用：AgentVersionSummary summary = agentMaintainerService.publish(command);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

版本未审核或发布失败时抛出 NacosException 异常。

11.13. 强制发布 Agent 版本

描述

跳过审核，直接发布指定版本。版本必须处于 draft、reviewing 或 reviewed 状态；成功后变为 online，latest 标签指向该版本。

AgentVersionSummary forcePublish(String namespaceId, AgentVersionRequest command) throws NacosException;


AgentVersionSummary forcePublish(AgentVersionRequest command) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间 ID；省略时使用默认命名空间 public。
commandAgentVersionRequest版本命令，包含必填的 agentName 和精确 version。

返回参数

参数类型描述
AgentVersionSummary上线后的版本摘要。

请求示例

try {
    AgentMaintainerService agentMaintainerService = aiMaintainerService.agent();
    AgentVersionRequest command = new AgentVersionRequest();
    command.setAgentName("demo-agent");
    command.setVersion("1.0.0");
    AgentVersionSummary summary = agentMaintainerService.forcePublish("public", command);
    // 使用默认命名空间时，可改用：AgentVersionSummary summary = agentMaintainerService.forcePublish(command);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

强制发布失败时抛出 NacosException 异常。

11.14. 重新编辑 Agent 版本

描述

将一个精确且已审核的 Agent 版本从 reviewed 转回 draft。

AgentVersionSummary redraft(String namespaceId, AgentVersionRequest command) throws NacosException;


AgentVersionSummary redraft(AgentVersionRequest command) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间 ID；省略时使用默认命名空间 public。
commandAgentVersionRequest版本命令，包含必填的 agentName 和精确 version。

返回参数

参数类型描述
AgentVersionSummary草稿状态的版本摘要。

请求示例

try {
    AgentMaintainerService agentMaintainerService = aiMaintainerService.agent();
    AgentVersionRequest command = new AgentVersionRequest();
    command.setAgentName("demo-agent");
    command.setVersion("1.0.0");
    AgentVersionSummary summary = agentMaintainerService.redraft("public", command);
    // 使用默认命名空间时，可改用：AgentVersionSummary summary = agentMaintainerService.redraft(command);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

版本状态不允许转换或操作失败时抛出 NacosException 异常。

11.15. 上线 Agent 版本

描述

将已下线（offline）的 Agent 版本重新上线，latest 标签指向该版本。

AgentVersionSummary online(String namespaceId, AgentVersionRequest command) throws NacosException;


AgentVersionSummary online(AgentVersionRequest command) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间 ID；省略时使用默认命名空间 public。
commandAgentVersionRequest版本命令，包含必填的 agentName 和精确 version。

返回参数

参数类型描述
AgentVersionSummary上线后的版本摘要。

请求示例

try {
    AgentMaintainerService agentMaintainerService = aiMaintainerService.agent();
    AgentVersionRequest command = new AgentVersionRequest();
    command.setAgentName("demo-agent");
    command.setVersion("1.0.0");
    AgentVersionSummary summary = agentMaintainerService.online("public", command);
    // 使用默认命名空间时，可改用：AgentVersionSummary summary = agentMaintainerService.online(command);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

版本状态不允许转换或操作失败时抛出 NacosException 异常。

11.16. 下线 Agent 版本

描述

将 online 版本下线，客户端将无法再发现该版本。版本内容仍保留，下线操作不会停止 Agent 实例。如果下线的是 latest 指向的版本，服务端会将该标签改为指向其他在线版本；没有在线版本时移除标签。

AgentVersionSummary offline(String namespaceId, AgentVersionRequest command) throws NacosException;


AgentVersionSummary offline(AgentVersionRequest command) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间 ID；省略时使用默认命名空间 public。
commandAgentVersionRequest版本命令，包含必填的 agentName 和精确 version。

返回参数

参数类型描述
AgentVersionSummary下线后的版本摘要。

请求示例

try {
    AgentMaintainerService agentMaintainerService = aiMaintainerService.agent();
    AgentVersionRequest command = new AgentVersionRequest();
    command.setAgentName("demo-agent");
    command.setVersion("1.0.0");
    AgentVersionSummary summary = agentMaintainerService.offline("public", command);
    // 使用默认命名空间时，可改用：AgentVersionSummary summary = agentMaintainerService.offline(command);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

版本状态不允许转换或操作失败时抛出 NacosException 异常。

11.17. 更新 Agent 自定义标签

描述

替换 Agent 的全部自定义版本标签。标签指向的版本必须存在，且不能处于 draft 或 reviewing 状态；传入空 Map 可清空自定义标签。latest 由服务端维护，请求中对它的修改会被忽略。

AgentSummary updateLabels(String namespaceId, AgentLabelsUpdateRequest request) throws NacosException;


AgentSummary updateLabels(AgentLabelsUpdateRequest request) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdstring命名空间 ID；省略时使用默认命名空间 public。
requestAgentLabelsUpdateRequest标签更新请求。

AgentLabelsUpdateRequest 包含必填的 agentName 和不可为 null 的 labels（Map<String, String>，标签名映射到精确版本）；传入空 Map 可清空全部自定义标签。

返回参数

参数类型描述
AgentSummary更新标签后的 Agent 摘要。

请求示例

try {
    AgentMaintainerService agentMaintainerService = aiMaintainerService.agent();
    AgentLabelsUpdateRequest request = new AgentLabelsUpdateRequest();
    request.setAgentName("demo-agent");
    request.setLabels(Collections.singletonMap("stable", "1.0.0"));
    AgentSummary agent = agentMaintainerService.updateLabels("public", request);
    // 使用默认命名空间时，可改用：AgentSummary agent = agentMaintainerService.updateLabels(request);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

标签无效、目标版本不存在或更新失败时抛出 NacosException 异常。

11.18. 更新 Agent 可见范围

描述

修改 Agent 的可见范围，内置策略支持 PUBLIC（公开）和 PRIVATE（私有）。公开资源的访问仍受鉴权和资源权限控制。

boolean updateScope(String namespaceId, String agentName, String scope) throws NacosException;


boolean updateScope(String agentName, String scope) throws NacosException;

请求参数

参数名参数类型描述
namespaceIdString命名空间 ID；省略时使用 public。
agentNameString精确的 Agent 名称。
scopeString目标可见范围：PUBLIC 或 PRIVATE。

返回参数

参数类型描述
boolean操作是否成功。

请求示例

try {
    AgentMaintainerService agentMaintainerService = aiMaintainerService.agent();
    boolean updated = agentMaintainerService.updateScope("public", "demo-agent", "PRIVATE");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

参数无效、权限不足或更新失败时抛出 NacosException。

12. Pipeline 管理

通过 aiMaintainerService.pipeline() 获取 PipelineMaintainerService。新代码应优先使用返回 Result 的类型化方法，以便显式检查服务端业务 code 和 message；返回 JsonNode 的旧方法仅用于兼容已有调用。

12.1. 获取 Pipeline 执行详情

描述

根据执行 ID 获取类型化的 Pipeline 执行详情。

Result<PipelineExecution> getPipelineDetail(String pipelineId) throws NacosException;

请求参数

参数名参数类型描述
pipelineIdstringPipeline 执行 ID。

返回参数

参数类型描述
Result服务端结果包装，可检查 code、message 和 data。

PipelineExecution 包含 executionId、resourceType、resourceName、namespaceId、version、status、节点结果 pipeline、createTime 和 updateTime。

请求示例

try {
    PipelineMaintainerService pipelineMaintainerService = aiMaintainerService.pipeline();
    Result<PipelineExecution> result =
            pipelineMaintainerService.getPipelineDetail("pipeline-execution-id");
    if (ErrorCode.SUCCESS.getCode().equals(result.getCode())) {
        PipelineExecution execution = result.getData();
    }
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

连接异常、无法解析响应或无可用响应体等传输/HTTP 失败时抛出 NacosException 异常。HTTP 200 中的业务失败通过 Result.code 和 Result.message 返回。

12.2. 分页查询 Pipeline 执行

描述

按资源类型及可选资源标识条件分页查询 Pipeline 执行记录。

Result<Page<PipelineExecution>> listPipelineExecutions(String resourceType, String resourceName, String namespaceId, String version, int pageNo, int pageSize) throws NacosException;

请求参数

参数名参数类型描述
resourceTypestring资源类型，必填。
resourceNamestring资源名称（可选）。
namespaceIdstring命名空间 ID（可选）。
versionstring资源版本（可选）。
pageNoint页码。
pageSizeint每页数量。

返回参数

参数类型描述
Result<Page>服务端结果包装，data 为 Pipeline 执行分页。

请求示例

try {
    PipelineMaintainerService pipelineMaintainerService = aiMaintainerService.pipeline();
    Result<Page<PipelineExecution>> result =
            pipelineMaintainerService.listPipelineExecutions(
                    "agent", "demo-agent", "public", "1.0.0", 1, 20);
    if (ErrorCode.SUCCESS.getCode().equals(result.getCode())) {
        Page<PipelineExecution> page = result.getData();
    }
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

传输或 HTTP 请求失败时抛出 NacosException 异常；业务失败通过 Result 返回。

12.3. 获取 Pipeline 执行详情（兼容方法）

描述

获取 Pipeline 执行详情的旧 JsonNode 访问器。该方法自 3.2.1 起已废弃，新代码请使用 getPipelineDetail。

@Deprecated
JsonNode getPipeline(String pipelineId) throws NacosException;

请求参数

参数名参数类型描述
pipelineIdstringPipeline 执行 ID。

返回参数

参数类型描述
JsonNode成功结果中的 Pipeline 执行 data JSON。

请求示例

try {
    PipelineMaintainerService pipelineMaintainerService = aiMaintainerService.pipeline();
    JsonNode execution = pipelineMaintainerService.getPipeline("pipeline-execution-id");
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求失败或服务端返回非成功业务结果时抛出 NacosException 异常。

12.4. 分页查询 Pipeline 执行（兼容方法）

描述

分页查询 Pipeline 执行的旧 JsonNode 访问器。该方法自 3.2.1 起已废弃，新代码请使用 listPipelineExecutions。

@Deprecated
JsonNode listPipelines(String resourceType, String resourceName, String namespaceId, String version, int pageNo, int pageSize) throws NacosException;

请求参数

参数名参数类型描述
resourceTypestring资源类型，必填。
resourceNamestring资源名称（可选）。
namespaceIdstring命名空间 ID（可选）。
versionstring资源版本（可选）。
pageNoint页码。
pageSizeint每页数量。

返回参数

参数类型描述
JsonNode成功结果中的 Pipeline 执行分页 data JSON。

请求示例

try {
    PipelineMaintainerService pipelineMaintainerService = aiMaintainerService.pipeline();
    JsonNode page = pipelineMaintainerService.listPipelines(
            "agent", "demo-agent", "public", "1.0.0", 1, 20);
} catch (NacosException e) {
    e.printStackTrace();
}

异常说明

请求失败或服务端返回非成功业务结果时抛出 NacosException 异常。