我的书签
添加书签
移除书签- 运维SDK
- 运维SDK
- 1. 引用概述
- 2. 初始化SDK
- 3. 配置中心运维 API
- 3.1. 获取配置
- 3.2. 发布配置
- 3.3. 删除配置
- 3.4. 批量删除配置
- 3.5. 获取配置列表
- 3.6. 搜索配置列表
- 3.7. 克隆配置
- 3.8. 获取命名空间下所有配置列表
- 3.9. 获取配置订阅者列表
- 3.10. 获取某个订阅者订阅的所有配置列表
- 3.11. 发布Beta灰度配置
- 3.12. 停止配置Beta灰度
- 3.13. 查询Beta灰度的配置
- 3.14. 获取配置历史历史版本列表
- 3.15. 获取配置历史历史版本详情
- 3.16. 查询配置上一版本信息详情
- 3.17. 触发Nacos Server从存储介质中dump数据到磁盘缓存中
- 3.18. 设置配置中心日志级别
- 3.19. 更新配置的元数据
- 4. 服务发现运维API
运维SDK
运维SDK
Nacos 的 运维SDK（或称Nacos-Maintainer-SDK），是一个针对 Nacos 配置中心、服务注册中心、分布式锁等功能运维场景下的的 Java SDK。旨在为Nacos的运维人员或部分特殊应用场景（如网关类应用，控制台类应用 ）提供稳定易用的配置中心、服务注册中心、分布式锁等功能，方便运维人员或特殊应用访问Nacos进行配置、服务和分布式锁的操作。
因为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>-->
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 maintainService = NamingMaintainerFactory.createNamingMaintainerService(properties);
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;
请求参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| dataId | string | 配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、” ”），不超过 256 字节。 |
| groupName | string | 配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、””），不超过128字节。 |
| namespaceId | long | 配置所属的命名空间ID。 |
返回值
| 参数类型 | 描述 |
|---|---|
| ConfigDetailInfo | 配置的具体信息 |
具体ConfigDetailInfo的内容如下：
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| id | long | 配置在实际存储介质中的ID，没有业务含义，仅作为配置在存储介质中的唯一标识。一般为唯一自增ID。 |
| namespaceId | string | 配置所属的命名空间ID。 |
| groupName | string | 配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、” ”），不超过128字节。 |
| dataId | string | 配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、””），不超过 256 字节。 |
| md5 | string | 配置内容的md5值。 |
| type | string | 配置的类型，如properties、json、yaml等，主要用于标记和展示。 |
| appName | string | 配置所属的应用名称。 |
| createTime | long | 配置的创建时间，为时间戳，单位为毫秒。 |
| modifyTime | long | 配置的最新更新时间，为时间戳，单位为毫秒。 |
| content | string | 配置内容。 |
| desc | string | 配置的描述信息。 |
| encryptedDataKey | string | 配置的加密密钥，当使用配置的加密功能时，该字段才有值。 |
| createUser | string | 创建此配置的用户名。 |
| createIp | string | 创建此配置的来源IP。 |
| configTags | string | 此配置的标签，多个标签用逗号,分隔。 |
请求示例
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 NacosExceptio;
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;
请求参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| dataId | string | 配置 ID。只允许英文字符和 4 种特殊字符（“.”、“:”、“-”、“ ”），不超过 256 字节。 |
| groupName | string | 配置分组。只允许英文字符和 4 种特殊字符（“.”、“:”、“-”、“”），不超过 128 字节。 |
| namespaceId | long | 配置所属的命名空间ID。 |
| content | string | 配置内容，不超过 100K 字节。 |
| desc | string | 配置的描述内容。 |
| type | string | 配置类型，见 com.alibaba.nacos.api.config.ConfigType，默认为TEXT |
| appName | string | 配置所属的应用名称。 |
| srcUser | string | 创建此配置的用户名，即代理此用户进行配置发布，此配置的createUser将为此用户，若传入空字串，则表示当前登录的用户名作为createUser。 |
| configTags | string | 此配置的标签，多个标签用逗号,分隔。 |
返回参数
| 参数类型 | 描述 |
|---|---|
| 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;
请求参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| dataId | string | 配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、” ”），不超过 256 字节。 |
| groupName | string | 配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、””），不超过128字节。 |
| namespaceId | long | 配置所属的命名空间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;
请求参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| ids | List<Long> | 待删除配置的ID列表，此ID为配置在实际存储介质中的ID，需要从获取配置或获取配置列表API中的id字段获取。 |
返回值
| 参数类型 | 描述 |
|---|---|
| boolean | 是否删除成功 |
请求示例
try {
ConfigDetailInfo configDetailInfo = configMaintainerService.getConfig("maintain.client.test");
boolean result = configMaintainerService.deleteConfigs(Collections.singletonList(configDetailInfo.getId()));
} 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;
请求参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| namespaceId | long | 配置所属的命名空间ID。 |
| dataId | string | 配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、” ”），不超过 256 字节, 默认为””，不为空时则只会匹配dataId为此值的配置。 |
| groupName | string | 配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、””），不超过128字节，默认为””，不为空时则只会匹配groupName为此值的配置。 |
| type | string | 配置类型，见 com.alibaba.nacos.api.config.ConfigType，默认为””，不为空时则只会匹配类型为此值的配置。 |
| configTags | string | 此配置的标签，多个标签用逗号,分隔，默认为””，不为空时则只会匹配标签为此值的配置。 |
| appName | string | 配置所属的应用名称，默认为””，不为空时则只会匹配应用名为此值的配置。 |
| pageNo | int | 配置列表的分页页码，默认为1。 |
| pageSize | int | 配置列表的分页大小，默认为100。 |
返回参数
| 参数类型 | 描述 |
|---|---|
| Page<ConfigBasicInfo> | 配置列表的分页结果 |
具体Page及ConfigBasicInfo的内容如下：
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| totalCount | int | 符合该条件下的配置总数。 |
| pageNumber | int | 当前页码。 |
| pagesAvailable | int | 分页的总页数。 |
| pageItems | List<ConfigBasicInfo> | 当前页的配置列表。 |
| 参数名 | 参数类型 | 描述 |
| --- | --- | --- |
| id | long | 配置在实际存储介质中的ID，没有业务含义，仅作为配置在存储介质中的唯一标识。一般为唯一自增ID。 |
| namespaceId | string | 配置所属的命名空间ID。 |
| groupName | string | 配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、” ”），不超过128字节。 |
| dataId | string | 配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、””），不超过 256 字节。 |
| md5 | string | 配置内容的md5值。 |
| type | string | 配置的类型，如properties、json、yaml等，主要用于标记和展示。 |
| appName | string | 配置所属的应用名称。 |
| createTime | long | 配置的创建时间，为时间戳，单位为毫秒。 |
| modifyTime | long | 配置的最新更新时间，为时间戳，单位为毫秒。 |
请求示例
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;
请求参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| namespaceId | long | 配置所属的命名空间ID。 |
| dataId | string | 配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、” ”），不超过 256 字节, 默认为””，不为空时则只会匹配所有dataId包含此值的配置。 |
| groupName | string | 配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、””），不超过128字节，默认为””，不为空时则只会匹配groupName包含此值的配置。 |
| type | string | 配置类型，见 com.alibaba.nacos.api.config.ConfigType，默认为””，不为空时则只会匹配类型为此值的配置。 |
| configDetail | string | 配置的内容，默认为””，不为空时则只会匹配配置内容包含此值的配置。 |
| configTags | string | 此配置的标签，多个标签用逗号,分隔，默认为””，不为空时则只会匹配标签为此值的配置。 |
| appName | string | 配置所属的应用名称，默认为””，不为空时则只会匹配应用名为此值的配置。 |
| pageNo | int | 配置列表的分页页码，默认为1。 |
| pageSize | int | 配置列表的分页大小，默认为100。 |
返回参数
| 参数类型 | 描述 |
|---|---|
| Page<ConfigBasicInfo> | 配置列表的分页结果 |
具体Page及ConfigBasicInfo的内容如下：
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| totalCount | int | 符合该条件下的配置总数。 |
| pageNumber | int | 当前页码。 |
| pagesAvailable | int | 分页的总页数。 |
| pageItems | List<ConfigBasicInfo> | 当前页的配置列表。 |
| 参数名 | 参数类型 | 描述 |
| --- | --- | --- |
| id | long | 配置在实际存储介质中的ID，没有业务含义，仅作为配置在存储介质中的唯一标识。一般为唯一自增ID。 |
| namespaceId | string | 配置所属的命名空间ID。 |
| groupName | string | 配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、” ”），不超过128字节。 |
| dataId | string | 配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、””），不超过 256 字节。 |
| md5 | string | 配置内容的md5值。 |
| type | string | 配置的类型，如properties、json、yaml等，主要用于标记和展示。 |
| appName | string | 配置所属的应用名称。 |
| createTime | long | 配置的创建时间，为时间戳，单位为毫秒。 |
| modifyTime | long | 配置的最新更新时间，为时间戳，单位为毫秒。 |
请求示例
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;
请求参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| namespaceId | string | 克隆的目标命名空间ID |
| cloneInfos | List<ConfigCloneInfo> | 需要克隆的配置列表 |
| srcUser | string | 克隆此配置的用户名，即代理此用户进行配置克隆，克隆的配置的createUser将为此用户，若传入空字串，则表示当前登录的用户名作为createUser。 |
| policy | SameConfigPolicy | 克隆配置时出现冲突后的处理策略，默认为ABORT，可选值为ABORT(终止）,SKIP（跳过）,OVERWRITE（覆盖）。 |
其中ConfigCloneInfo中的参数详情为：
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| configId | long | 配置在实际存储介质中的ID，没有业务含义，仅作为配置在存储介质中的唯一标识。一般为唯一自增ID。 |
| targetGroupName | string | 目标配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、” ”），不超过128字节，为空时则使用配置当前的分组。 |
| targetDataId | string | 目标配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、””），不超过 256 字节，为空时则使用配置当前的 ID。 |
返回参数
| 参数类型 | 描述 |
|---|---|
| Map<String, Object> | 克隆配置的结果，根据policy的不同，可能返回成功的数量，失败的数量，跳过的数量，或覆盖的数量 |
请求示例
try {
# 将配置ID为1的配置克隆到`cloue-test`命名空间下，克隆策略为`ABORT`，即如果目标命名空间下有同名配置，则克隆失败。
ConfigCloneInfo configCloneInfo = new ConfigCloneInfo();
configCloneInfo.setConfigId(1L);
Map<String, Object> result = configMaintainerService.cloneConfig("cloue-test", Collections.singletonList(configCloneInfo), "", SameConfigPolicy.ABORT);
} catch (NacosException e) {
e.printStackTrace();
}
异常说明
读取配置超时或网络异常，抛出 NacosException 异常。
3.8. 获取命名空间下所有配置列表
描述
通过此接口，可以获取指定命名空间下所有的配置列表。
注意
此API不同于查询配置列表，不会进行分页，而是将命名空间下所有的配置一次性返回，需要确保使用此API时，命名空间下的配置数量不能太大，否则可能会导致内存溢出。 尽量使用查询配置列表，进行分页查询。
List<ConfigBasicInfo> getConfigListByNamespace(String namespaceId) throws NacosException;
请求参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| namespaceId | string | 配置所属的命名空间ID |
返回参数
| 参数类型 | 描述 |
|---|---|
| List<ConfigBasicInfo> | 配置列表的分页结果 |
具体ConfigBasicInfo的内容如下：
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| id | long | 配置在实际存储介质中的ID，没有业务含义，仅作为配置在存储介质中的唯一标识。一般为唯一自增ID。 |
| namespaceId | string | 配置所属的命名空间ID。 |
| groupName | string | 配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、” ”），不超过128字节。 |
| dataId | string | 配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、””），不超过 256 字节。 |
| md5 | string | 配置内容的md5值。 |
| type | string | 配置的类型，如properties、json、yaml等，主要用于标记和展示。 |
| appName | string | 配置所属的应用名称。 |
| createTime | long | 配置的创建时间，为时间戳，单位为毫秒。 |
| modifyTime | long | 配置的最新更新时间，为时间戳，单位为毫秒。 |
请求示例
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;
请求参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| groupName | string | 配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、” ”），不超过128字节。 |
| dataId | string | 配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、””），不超过 256 字节。 |
| namespaceId | string | 配置所属的命名空间ID。 |
| aggregation | boolean | 是否聚合查询，默认为true，为false时仅查询请求所在节点的订阅者列表，为true时查询整个集群中此配置的订阅者列表。 |
返回参数
| 参数类型 | 描述 |
|---|---|
| ConfigListenerInfo | 配置的订阅者信息 |
其中ConfigListenerInfo的内容如下：
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| queryType | string | 此接口固定返回config |
| listenersStatus | Map<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;
请求参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| ip | string | 配置订阅者的IP |
| all | boolean | 是否查询所有相同IP的订阅者所订阅的配置列表，默认为false，为false时仅返回第一个匹配到ip的订阅者订阅的配置列表，为true时返回所有匹配到ip的订阅者订阅的配置列表。 |
| namespaceId | string | 配置所属的命名空间ID。 |
| aggregation | boolean | 是否聚合查询，默认为true，为false时仅查询请求所在节点的订阅者列表，为true时查询整个集群中此配置的订阅者列表。 |
返回参数
| 参数类型 | 描述 |
|---|---|
| ConfigListenerInfo | 配置的订阅者信息 |
其中ConfigListenerInfo的内容如下：
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| queryType | string | 此接口固定返回ip |
| listenersStatus | Map<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 配置，方便修改配置时进行测试，降低因配置错误导致的应用故障范围。
注意
灰度发布的配置不能重复灰度，若该配置已经存在一个Beta灰度配置存在，则该接口将发布失败，需要先停止灰度后，再重新发布。
boolean publishBetaConfig(String dataId, String groupName, String namespaceId, String content, String appName, String srcUser, String configTags, String desc, String type, String betaIps) throws NacosException;
请求参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| dataId | string | 配置 ID。只允许英文字符和 4 种特殊字符（“.”、“:”、“-”、“ ”），不超过 256 字节。 |
| groupName | string | 配置分组。只允许英文字符和 4 种特殊字符（“.”、“:”、“-”、“”），不超过 128 字节。 |
| namespaceId | long | 配置所属的命名空间ID。 |
| content | string | 配置内容，不超过 100K 字节。 |
| desc | string | 配置的描述内容。 |
| type | string | 配置类型，见 com.alibaba.nacos.api.config.ConfigType，默认为TEXT |
| appName | string | 配置所属的应用名称。 |
| srcUser | string | 创建此配置的用户名，即代理此用户进行配置发布，此配置的createUser将为此用户，若传入空字串，则表示当前登录的用户名作为createUser。 |
| configTags | string | 此配置的标签，多个标签用逗号,分隔。 |
| betaIps | string | 配置的灰度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配置
注意
只有通过发布Beta灰度配置将配置变更为Beta发布中的状态，调用此接口才能停止Beta发布状态。
boolean stopBeta(String dataId, String groupName) throws NacosException;
boolean stopBeta(String dataId, String groupName, String namespaceId) throws NacosException;
请求参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| dataId | string | 配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、” ”），不超过 256 字节。 |
| groupName | string | 配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、””），不超过128字节。 |
| namespaceId | string | 配置所属的命名空间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配置
注意
只有通过发布Beta灰度配置将配置变更为Beta发布中的状态，调用此接口才能查询Beta发布状态。
ConfigGrayInfo queryBeta(String dataId, String groupName) throws NacosException;
ConfigGrayInfo queryBeta(String dataId, String groupName, String namespaceId) throws NacosException;
请求参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| dataId | string | 配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、” ”），不超过 256 字节。 |
| groupName | string | 配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、””），不超过128字节。 |
| namespaceId | string | 配置所属的命名空间ID。 |
返回参数
| 参数类型 | 描述 |
|---|---|
| ConfigGrayInfo | 灰度配置的信息 |
其中ConfigGrayInfo的内容如下：
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| id | long | 配置在实际存储介质中的ID，没有业务含义，仅作为配置在存储介质中的唯一标识。一般为唯一自增ID。 |
| namespaceId | string | 配置所属的命名空间ID。 |
| groupName | string | 配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、” ”），不超过128字节。 |
| dataId | string | 配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、””），不超过 256 字节。 |
| md5 | string | 配置内容的md5值。 |
| type | string | 配置的类型，如properties、json、yaml等，主要用于标记和展示。 |
| appName | string | 配置所属的应用名称。 |
| createTime | long | 配置的创建时间，为时间戳，单位为毫秒。 |
| modifyTime | long | 配置的最新更新时间，为时间戳，单位为毫秒。 |
| content | string | 配置内容。 |
| desc | string | 配置的描述信息。 |
| encryptedDataKey | string | 配置的加密密钥，当使用配置的加密功能时，该字段才有值。 |
| createUser | string | 创建此配置的用户名。 |
| createIp | string | 创建此配置的来源IP。 |
| configTags | string | 此配置的标签，多个标签用逗号,分隔。 |
| grayName | string | 灰度名称，固定为beta |
| grayRule | string | 灰度的规则，格式为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 group, String namespaceId, Integer pageNo, Integer pageSize) throws NacosException;
请求参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| dataId | string | 配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、” ”），不超过 256 字节。 |
| groupName | string | 配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、””），不超过128字节。 |
| namespaceId | string | 配置所属的命名空间ID。 |
| pageNo | int | 配置历史版本列表的分页页码，默认为1。 |
| pageSize | int | 配置历史版本列表的分页大小，默认为100。 |
返回参数
| 参数类型 | 描述 |
|---|---|
| Page<ConfigHistoryBasicInfo> | 配置历史版本列表的分页结果 |
其中Page及ConfigHistoryBasicInfo的内容如下：
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| totalCount | int | 符合该条件下的配置历史版本总数。 |
| pageNumber | int | 当前页码。 |
| pagesAvailable | int | 分页的总页数。 |
| pageItems | List<ConfigHistoryBasicInfo> | 当前页的配置历史版本列表。 |
| 参数名 | 参数类型 | 描述 |
| --- | --- | --- |
| id | long | 配置历史版本的ID，没有业务含义，仅作为配置历史版本在存储介质中的唯一标识。一般为唯一自增ID。 |
| namespaceId | string | 配置所属的命名空间ID。 |
| groupName | string | 配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、” ”），不超过128字节。 |
| dataId | string | 配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、””），不超过 256 字节。 |
| md5 | string | 配置内容的md5值。 |
| type | string | 配置的类型，如properties、json、yaml等，主要用于标记和展示。 |
| appName | string | 配置所属的应用名称。 |
| createTime | long | 配置的创建时间，为时间戳，单位为毫秒。 |
| modifyTime | long | 配置的最新更新时间，为时间戳，单位为毫秒。 |
| srcUser | string | 操作此版本的用户名。 |
| srcIp | string | 操作此版本的来源IP。 |
| opType | string | 此历史版本的操作类型，I为创建，U为更新，D为删除 |
| publishType | string | 此历史版本的发布类型，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;
请求参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| namespaceId | string | 配置所属的命名空间ID。 |
| groupName | string | 配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、” ”），不超过128字节。 |
| dataId | string | 配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、””），不超过 256 字节。 |
| nid | long | 目标历史版本在的Id， 通过获取配置历史历史版本列表接口获取。 |
返回参数
| 参数类型 | 描述 |
|---|---|
| ConfigHistoryDetailInfo | 配置历史版本的详细信息 |
其中ConfigHistoryDetailInfo的内容如下：
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| id | long | 配置历史版本的ID，没有业务含义，仅作为配置历史版本在存储介质中的唯一标识。一般为唯一自增ID。 |
| namespaceId | string | 配置所属的命名空间ID。 |
| groupName | string | 配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、” ”），不超过128字节。 |
| dataId | string | 配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、””），不超过 256 字节。 |
| md5 | string | 配置内容的md5值。 |
| type | string | 配置的类型，如properties、json、yaml等，主要用于标记和展示。 |
| appName | string | 配置所属的应用名称。 |
| createTime | long | 配置的创建时间，为时间戳，单位为毫秒。 |
| modifyTime | long | 配置的最新更新时间，为时间戳，单位为毫秒。 |
| content | string | 配置历史版本的内容。 |
| encryptedDataKey | string | 配置解密的密钥，仅当配置为加密配置时返回。 |
| grayName | string | 配置历史版本的灰度发布名称，当此次历史版本为灰度发布时存在，一般为beta |
| extInfo | string | 历史版本的扩展信息，目前存储灰度发布时的发布规则，如灰度的ip地址列表，格式为json。 |
请求示例
try {
# 查询`maintain.client.test`配置的历史版本列表。
Page<ConfigHistoryBasicInfo> configHistoryBasicInfoPage = configMaintainerService.listConfigHistory("maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID, 1, 10);
int 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;
请求参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| namespaceId | string | 配置所属的命名空间ID。 |
| groupName | string | 配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、” ”），不超过128字节。 |
| dataId | string | 配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、””），不超过 256 字节。 |
| id | long | 配置在实际存储介质中的ID，通过获取配置 获取 |
返回参数
| 参数类型 | 描述 |
|---|---|
| ConfigHistoryDetailInfo | 配置历史版本的详细信息 |
其中ConfigHistoryDetailInfo的内容如下：
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| id | long | 配置历史版本的ID，没有业务含义，仅作为配置历史版本在存储介质中的唯一标识。一般为唯一自增ID。 |
| namespaceId | string | 配置所属的命名空间ID。 |
| groupName | string | 配置分组。只允许英文字符和4种特殊字符（”.”、”:”、”-”、” ”），不超过128字节。 |
| dataId | string | 配置 ID。只允许英文字符和 4 种特殊字符（”.”、”:”、”-”、””），不超过 256 字节。 |
| md5 | string | 配置内容的md5值。 |
| type | string | 配置的类型，如properties、json、yaml等，主要用于标记和展示。 |
| appName | string | 配置所属的应用名称。 |
| createTime | long | 配置的创建时间，为时间戳，单位为毫秒。 |
| modifyTime | long | 配置的最新更新时间，为时间戳，单位为毫秒。 |
| content | string | 配置历史版本的内容。 |
| encryptedDataKey | string | 配置解密的密钥，仅当配置为加密配置时返回。 |
| grayName | string | 配置历史版本的灰度发布名称，当此次历史版本为灰度发布时存在，一般为beta |
| extInfo | string | 历史版本的扩展信息，目前存储灰度发布时的发布规则，如灰度的ip地址列表，格式为json。 |
请求示例
try {
# 获取`maintain.client.test`配置的ID。
int 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;
请求参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| logName | string | 日志模块名称，如config-server, config-dump等 |
| logLevel | string | 日志级别（如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;
请求参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| dataId | string | 配置 ID。只允许英字符和 4 种特殊字符（”.”、”:”、”-”、” ”），不超过 256 字节。 |
| groupName | string | 配置分组。只允许英字符和 4 种特殊字符（”.”、”:”、”-”、””），不超过 128 字节。 |
| namespaceId | string | 配置所属的命名空间ID。 |
| description | string | 配置的描述信息 |
| configTags | string | 此配置的标签，多个标签用逗号,分隔。 |
返回参数
| 参数类型 | 描述 |
|---|---|
| boolean | 是否更新成功 |
请求示例
try {
configMaintainerService.updateConfigMetadata("maintain.client.test", "DEFAULT_GROUP", "public", "this is a description", "tag1,tag2");
} 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.serviceName) | string | 服务的名称 |
| groupName(Service.groupName) | string | 服务的分组名称 |
| namespaceId(Service.namespaceId) | string | 服务所属的命名空间ID |
| ephemeral(Service.ephemeral) | boolean | 是否临时服务，默认为false |
| protectThreshold(Service.protectThreshold) | float | 服务的防护阈值，默认为0.0 |
| Service.metadata | Map<String,String> | 服务的元数据 |
| Service.selector | Selector | 服务的实例选择器，默认为None |
返回参数
| 参数类型 | 描述 |
|---|---|
| String | 创建服务的结果描述 |
请求示例
try {
# 以下请求均创建一个名为`maintain.client.test`的持久化服务。
String result = namingMaintainerService.createService("maintain.client.test");
result = namingMaintainerService.createService("maintain.client.test", Constants.DEFAULT_GROUP);
result = namingMaintainerService.createService("maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID);
result = namingMaintainerService.createService("maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID, false);
result = namingMaintainerService.createService("maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID, 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.serviceName) | string | 服务的名称 |
| groupName(Service.groupName) | string | 服务的分组名称 |
| namespaceId(Service.namespaceId) | string | 服务所属的命名空间ID |
| ephemeral(Service.ephemeral) | boolean | 是否临时服务，默认为false |
| protectThreshold(Service.protectThreshold) | float | 服务的防护阈值，默认为0.0 |
| Service.metadata | Map<String,String> | 服务的元数据 |
| 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("maintain.client.test", Constants.DEFAULT_GROUP, new HashMap<>(), 0.0f, new NoneSelector());
result = namingMaintainerService.updateService("maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID, new HashMap<>(), 0.0f, new NoneSelector());
result = namingMaintainerService.updateService("maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID, 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.serviceName) | 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("maintain.client.test", Constants.DEFAULT_GROUP);
result = namingMaintainerService.removeService("maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID);
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.serviceName) | string | 服务的名称 |
| groupName(Service.groupName) | string | 服务的分组名称 |
| namespaceId(Service.namespaceId) | string | 服务所属的命名空间ID |
返回参数
| 参数类型 | 描述 |
|---|---|
| ServiceDetailInfo | 服务的详细信息 |
其中ServiceDetailInfo中的详细内容有：
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| namespaceId | string | 服务的命名空间ID |
| groupName | string | 服务的分组名称 |
| serviceName | string | 服务的名称 |
| ephemeral | boolean | 服务的持久化属性 |
| protectThreshold | float | 服务的保护阈值 |
| selector | Selector | 服务的实例选择器 |
| metadata | Map<String,String> | 服务的元数据 |
| clusterMap | Map<String, ClusterInfo> | 服务下的逻辑集群信息Map，其中key为逻辑集群名称，value为详细信息 |
| clusterMap.${key}.clusterName | string | 逻辑集群的名称 |
| clusterMap.${key}.healthyCheckPort | int | 逻辑集群的健康检查断藕 |
| clusterMap.${key}.useInstancePortForCheck | boolean | 逻辑集群是否使用实例信息的端口进行健康检查 |
| clusterMap.${key}.healthChecker | AbstractHealthChecker | 逻辑集群的健康检查类型 |
| clusterMap.${key}.metadata | Map<String,String> | 逻辑集群的元数据 |
请求示例
try {
# 以下请求均获取一个名为`maintain.client.test`的服务详情信息。
ServiceDetailInfo result = namingMaintainService.getServiceDetail("maintain.client.test");
result = namingMaintainService.getServiceDetail("maintain.client.test", Constants.DEFAULT_GROUP);
result = namingMaintainService.getServiceDetail("maintain.client.test", Constants.DEFAULT_GROUP, Constants.DEFAULT_NAMESPACE_ID);
Service service = new Service();
service.setName("maintain.client.test");
service.setNamespaceId(Constants.DEFAULT_NAMESPACE_ID);
service.setGroupName(Constants.DEFAULT_GROUP);
result = namingMaintainService.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;
请求参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| namespaceId | string | 服务所属的命名空间ID |
| groupNameParam | string | 服务的分组名称模版，支持使用__进行前缀后缀的模糊匹配，为空时获取所有分组。 |
| serviceNameParam | string | 服务的名称模版，支持使用``进行前缀后缀的模糊匹配，为空时获取所有服务。 |
| ignoreEmptyService | boolean | 是否忽略空服务，默认为true，为true将不返回空服务。 |
| pageNo | int | 分页页码，默认为1。 |
| pageSize | int | 分页每页大小，默认为100。 |
返回参数
| 参数类型 | 描述 |
|---|---|
| Page<ServiceView> | 满足条件服务列表的分页结果 |
具体Page及ServiceView的内容如下：
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| totalCount | int | 符合该条件下的服务总数。 |
| pageNumber | int | 当前页码。 |
| pagesAvailable | int | 分页的总页数。 |
| pageItems | List<ConfigBasicInfo> | 当前页的服务列表。 |
| 参数名 | 参数类型 | 描述 |
| --- | --- | --- |
| name | string | 服务的名称 |
| groupName | string | 服务的分组名称 |
| clusterCount | int | 服务下逻辑集群的个数 |
| ipCount | int | 服务下的实例总数 |
| healthyInstanceCount | int | 服务下的健康实例总数 |
| triggerFlag | boolean | 是否触发了阈值保护 |
请求示例
try {
# 以下请求均获取所有服务列表(最多前100个)。
Page<ServiceView> result = namingMaintainService.listServices(Constants.DEFAULT_NAMESPACE_ID);
result = namingMaintainService.listServices(Constants.DEFAULT_NAMESPACE_ID, "", "");
result = namingMaintainService.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;
请求参数
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| namespaceId | string | 服务所属的命名空间ID |
| groupNameParam | string | 服务的分组名称模版，支持使用__进行前缀后缀的模糊匹配，为空时获取所有分组。 |
| serviceNameParam | string | 服务的名称模版，支持使用``进行前缀后缀的模糊匹配，为空时获取所有服务。 |
| pageNo | int | 分页页码，默认为1。 |
| pageSize | int | 分页每页大小，默认为100。 |
返回参数
| 参数类型 | 描述 |
|---|---|
| Page<ServiceDetailInfo> | 满足条件服务列表的分页结果 |
具体Page及ServiceDetailInfo的内容如下：
| 参数名 | 参数类型 | 描述 |
|---|---|---|
| totalCount | int | 符合该条件下的服务总数。 |
| pageNumber | int | 当前页码。 |
| pagesAvailable | int | 分页的总页数。 |
| pageItems | List<ConfigBasicInfo> | 当前页的服务列表。 |
| 参数名 | 参数类型 | 描述 |
| --- | --- | --- |
| namespaceId | string | 服务的命名空间ID |
| groupName | string | 服务的分组名称 |
| serviceName | string | 服务的名称 |
| ephemeral | boolean | 服务的持久化属性 |
| protectThreshold | float | 服务的保护阈值 |
| selector | Selector | 服务的实例选择器 |
| metadata | Map<String,String> | 服务的元数据 |
| clusterMap | Map<String, ClusterInfo> | 服务下的逻辑集群信息Map，其中key为逻辑集群名称，value为详细信息 |
| clusterMap.${key}.clusterName | string | 逻辑集群的名称 |
| clusterMap.${key}.healthyCheckPort | int | 逻辑集群的健康检查断藕 |
| clusterMap.${key}.useInstancePortForCheck | boolean | 逻辑集群是否使用实例信息的端口进行健康检查 |
| clusterMap.${key}.healthChecker | AbstractHealthChecker | 逻辑集群的健康检查类型 |
| clusterMap.${key}.metadata | Map<String,String> | 逻辑集群的元数据 |
请求示例
try {
# 以下请求均获取所有服务列表(最多前100个)。
Page<ServiceDetailInfo> result = namingMaintainService.listServicesWithDetail(Constants.DEFAULT_NAMESPACE_ID);
result = namingMaintainService.listServicesWithDetail(Constants.DEFAULT_NAMESPACE_ID, "", "");
result = namingMaintainService.listServicesWithDetail(Constants.DEFAULT_NAMESPACE_ID, "", "", 1, 10);
} catch (NacosException e) {
e.printStackTrace();
}
异常说明
读取配置超时或网络异常，抛出 NacosException 异常。
（本文超出站点单文档体积上限，已按小节截断）
