Open API 指南知识图谱 - 健康快乐每一天

Open API 指南

本站和网页 https://nacos.io/zh-cn/docs/open-api.html 的作者无关，不对其内容负责。快照谨为网络故障时之索引，不代表被搜索网站的即时页面。

Open API 指南
En首页文档2.X（推荐）1.X 解决方案微服务解决方案微服务Serverless解决方案PaaS解决方案企业版NACOSNACOS架构与原理博客社区控制台样例Nacos 文档Nacos Nacos是什么?Nacos简介概念架构快速开始NacosNacos SpringNacos Spring BootNacos Spring CloudNacos DockerNacos DubboNacos k8sNacos Sync用户指南Java的SDK其他语言的SDKOpen-API指南Nacos SpringNacos系统参数介绍权限认证FAQ运维指南部署手册集群部署说明运维API控制台手册监控手册Nacos配置模块压测报告Nacos服务发现模块压测报告其他环境迁移到Nacos开源共建贡献源码贡献流程pull request模板如何提交问题报告社区社区开发团队Open API 指南
配置管理
获取配置
监听配置
发布配置
删除配置
查询历史版本
查询历史版本详情
查询配置上一版本信息
服务发现
注册实例
注销实例
修改实例
查询实例列表
查询实例详情
发送实例心跳
创建服务
删除服务
修改服务
查询服务
查询服务列表
查询系统开关
修改系统开关
查看系统当前数据指标
查看当前集群Server列表
查看当前集群leader
更新实例的健康状态
批量更新实例元数据(Beta)
批量删除实例元数据(Beta)
命名空间
查询命名空间列表
创建命名空间
修改命名空间
删除命名空间
配置管理
获取配置
描述
获取Nacos上的配置。
请求类型
GET
请求URL
/nacos/v1/cs/configs
请求参数
名称
类型
是否必须
描述
tenant
string
租户信息，对应 Nacos 的命名空间ID字段。
dataId
string
配置 ID。
group
string
配置分组。
返回参数
参数类型
描述
string
配置值
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例
请求示例
curl -X GET 'http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=nacos.example&group=com.alibaba.nacos'
返回示例
contentTest
监听配置
描述
监听 Nacos 上的配置，以便实时感知配置变更。如果配置变更，则用获取配置接口获取配置的最新值，动态刷新本地缓存。
注册监听采用的是异步 Servlet 技术。注册监听本质就是带着配置和配置值的 MD5 值和后台对比。如果 MD5 值不一致，就立即返回不一致的配置。如果值一致，就等待住 30 秒。返回值为空。
请求类型
POST
请求URL
/nacos/v1/cs/configs/listener
请求参数
名称
类型
是否必须
描述
Listening-Configs
string
监听数据报文。格式为 dataId^2Group^2contentMD5^2tenant^1或者dataId^2Group^2contentMD5^1。
dataId：配置 ID
group：配置分组
contentMD5：配置内容 MD5 值
tenant：租户信息，对应 Nacos 的命名空间字段(非必填)
Header 参数
名称
类型
是否必须
描述
Long-Pulling-Timeout
string
长轮训等待 30s，此处填写 30000。
参数说明
配置多个字段间分隔符：^2 = Character.toString((char) 2，urlencode 后值为 %02
配置间分隔符：^1 = Character.toString((char) 1)，urlencode 后值为 %01
contentMD5: MD5(content)，第一次本地缓存为空，所以这块为空串
返回参数
参数类型
描述
string
配置值
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例
请求示例
http://serverIp:8848/nacos/v1/cs/configs/listener
POST 请求体数据内容：
Listening-Configs=dataId%02group%02contentMD5%02tenant%01
返回示例
如果配置变化
dataId%02group%02tenant%01
如果配置无变化：会返回空串
发布配置
描述
发布 Nacos 上的配置。
请求类型
POST
请求 URL
/nacos/v1/cs/configs
请求参数
名称
类型
是否必须
描述
tenant
string
租户信息，对应 Nacos 的命名空间ID字段
dataId
string
配置 ID
group
string
配置分组
content
string
配置内容
type
String
配置类型
返回参数
参数类型
描述
boolean
是否发布成功
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例
请求示例
curl -X POST 'http://127.0.0.1:8848/nacos/v1/cs/configs' -d 'dataId=nacos.example&group=com.alibaba.nacos&content=contentTest'
返回示例
true
删除配置
描述
删除 Nacos 上的配置。
请求类型
DELETE
请求 URL
/nacos/v1/cs/configs
请求参数
名称
类型
是否必须
描述
tenant
string
租户信息，对应 Naocs 的命名空间ID字段
dataId
string
配置 ID
group
string
配置分组
返回参数
参数类型
描述
boolean
是否删除成功
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例
请求示例
curl -X DELETE 'http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=nacos.example&group=com.alibaba.nacos'
返回示例
true
查询历史版本
描述
查询配置项历史版本。
请求类型
GET
请求 URL
/nacos/v1/cs/history?search=accurate
请求参数
名称
类型
是否必须
描述
tenant
string
租户信息，对应 Naocs 的命名空间ID字段
dataId
string
配置 ID
group
string
配置分组
pageNo
integer
当前页码
pageSize
integer
分页条数(默认100条,最大为500)
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例
请求示例
curl -X GET 'http://127.0.0.1:8848/nacos/v1/cs/history?search=accurate&dataId=nacos.example&group=com.alibaba.nacos'
返回示例
"totalCount": 1,
"pageNumber": 1,
"pagesAvailable": 1,
"pageItems": [
"id": "203",
"lastId": -1,
"dataId": "nacos.example",
"group": "com.alibaba.nacos",
"tenant": "",
"appName": "",
"md5": null,
"content": null,
"srcIp": "0:0:0:0:0:0:0:1",
"srcUser": null,
"opType": "I ",
"createdTime": "2010-05-04T16:00:00.000+0000",
"lastModifiedTime": "2020-12-05T01:48:03.380+0000"
查询历史版本详情
描述
查询配置项历史版本详情
请求类型
GET
请求 URL
/nacos/v1/cs/history
请求参数
名称
类型
是否必须
描述
nid
Integer
配置项历史版本ID
tenant
string
租户信息，对应 Naocs 的命名空间ID字段（2.0.3起）
dataId
string
配置 ID （2.0.3起）
group
string
配置分组（2.0.3起）
注意：2.0.3版本起，此接口需要新增字段tenant、dataId和group，其中tenant非必填。
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例
请求示例
curl -X GET 'http://127.0.0.1:8848/nacos/v1/cs/history?nid=203&tenant=&dataId=nacos.example&group=com.alibaba.nacos'
返回示例
"id": "203",
"lastId": -1,
"dataId": "nacos.example",
"group": "com.alibaba.nacos",
"tenant": "",
"appName": "",
"md5": "9f67e6977b100e00cab385a75597db58",
"content": "contentTest",
"srcIp": "0:0:0:0:0:0:0:1",
"srcUser": null,
"opType": "I ",
"createdTime": "2010-05-04T16:00:00.000+0000",
"lastModifiedTime": "2020-12-05T01:48:03.380+0000"
查询配置上一版本信息
描述
查询配置上一版本信息(1.4起)
请求类型
GET
请求 URL
/nacos/v1/cs/history/previous
请求参数
名称
类型
是否必须
描述
id
Integer
配置ID
tenant
string
租户信息，对应 Naocs 的命名空间ID字段（2.0.3起）
dataId
string
配置 ID （2.0.3起）
group
string
配置分组（2.0.3起）
说明：2.0.3版本起，此接口需要新增字段tenant、dataId和group，其中tenant非必填。
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例
请求示例
curl -X GET 'http://127.0.0.1:8848/nacos/v1/cs/history/previous?id=309135486247505920&tenant=&dataId=nacos.example&group=com.alibaba.nacos'
返回示例
"id": "203",
"lastId": -1,
"dataId": "nacos.example",
"group": "com.alibaba.nacos",
"tenant": "",
"appName": "",
"md5": "9f67e6977b100e00cab385a75597db58",
"content": "contentTest",
"srcIp": "0:0:0:0:0:0:0:1",
"srcUser": null,
"opType": "I ",
"createdTime": "2010-05-04T16:00:00.000+0000",
"lastModifiedTime": "2020-12-05T01:48:03.380+0000"
服务发现
注册实例
描述
注册一个实例到服务。
请求类型
POST
请求路径
/nacos/v1/ns/instance
请求参数
名称
类型
是否必选
描述
ip
字符串
服务实例IP
port
int
服务实例port
namespaceId
字符串
命名空间ID
weight
double
权重
enabled
boolean
是否上线
healthy
boolean
是否健康
metadata
字符串
扩展信息
clusterName
字符串
集群名
serviceName
字符串
服务名
groupName
字符串
分组名
ephemeral
boolean
是否临时实例
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例请求
curl -X POST 'http://127.0.0.1:8848/nacos/v1/ns/instance?port=8848&healthy=true&ip=11.11.11.11&weight=1.0&serviceName=nacos.test.3&encoding=GBK&namespaceId=n1'
示例返回
ok
注销实例
描述
删除服务下的一个实例。
请求类型
DELETE
请求路径
/nacos/v1/ns/instance
请求参数
名称
类型
是否必选
描述
serviceName
字符串
服务名
groupName
字符串
分组名
ip
字符串
服务实例IP
port
int
服务实例port
clusterName
字符串
集群名称
namespaceId
字符串
命名空间ID
ephemeral
boolean
是否临时实例
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例请求
curl -X DELETE '127.0.0.1:8848/nacos/v1/ns/instance?serviceName=nacos.test.1&ip=1.1.1.1&port=8888&clusterName=TEST1'
示例返回
ok
修改实例
描述
修改服务下的一个实例。
注意：在Nacos2.0版本后，通过该接口更新的元数据拥有更高的优先级，且具有记忆能力；会在对应实例删除后，依旧存在一段时间，如果在此期间实例重新注册，该元数据依旧生效；您可以通过nacos.naming.clean.expired-metadata.expired-time及nacos.naming.clean.expired-metadata.interval对记忆时间进行修改
请求类型
PUT
请求路径
/nacos/v1/ns/instance
请求参数
名称
类型
是否必选
描述
serviceName
字符串
服务名
groupName
字符串
分组名
ip
字符串
服务实例IP
port
int
服务实例port
clusterName
字符串
集群名称
namespaceId
字符串
命名空间ID
weight
double
权重
metadata
JSON
扩展信息
enabled
boolean
是否打开流量
ephemeral
boolean
是否临时实例
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例请求
curl -X PUT '127.0.0.1:8848/nacos/v1/ns/instance?serviceName=nacos.test.1&ip=1.1.1.1&port=8888&clusterName=TEST1&weight=8&metadata={}'
示例返回
ok
查询实例列表
描述
查询服务下的实例列表
请求类型
GET
请求路径
/nacos/v1/ns/instance/list
请求参数
名称
类型
是否必选
描述
serviceName
字符串
服务名
groupName
字符串
分组名
namespaceId
字符串
命名空间ID
clusters
字符串，多个集群用逗号分隔
集群名称
healthyOnly
boolean
否，默认为false
是否只返回健康实例
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例请求
curl -X GET '127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=nacos.test.1'
示例返回
"name": "DEFAULT_GROUP@@nacos.test.1",
"groupName": "DEFAULT_GROUP",
"clusters": "",
"cacheMillis": 10000,
"hosts": [
"instanceId": "10.10.10.10#8888#DEFAULT#DEFAULT_GROUP@@nacos.test.1",
"ip": "10.10.10.10",
"port": 8888,
"weight": 1,
"healthy": false,
"enabled": true,
"ephemeral": false,
"clusterName": "DEFAULT",
"serviceName": "DEFAULT_GROUP@@nacos.test.1",
"metadata": { },
"instanceHeartBeatInterval": 5000,
"instanceIdGenerator": "simple",
"instanceHeartBeatTimeOut": 15000,
"ipDeleteTimeout": 30000
],
"lastRefTime": 1528787794594,
"checksum": "",
"allIPs": false,
"reachProtectionThreshold": false,
"valid": true
查询实例详情
描述
查询一个服务下个某个实例详情。
请求类型
GET
请求路径
/nacos/v1/ns/instance
请求参数
名称
类型
是否必选
描述
serviceName
字符串
服务名
groupName
字符串
分组名
ip
字符串
实例IP
port
字符串
实例端口
namespaceId
字符串
命名空间ID
cluster
字符串
集群名称
healthyOnly
boolean
否，默认为false
是否只返回健康实例
ephemeral
boolean
是否临时实例
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例请求
curl -X GET '127.0.0.1:8848/nacos/v1/ns/instance?serviceName=nacos.test.2&ip=10.10.10.10&port=8888&cluster=DEFAULT'
示例返回
"metadata": {},
"instanceId": "10.10.10.10-8888-DEFAULT-nacos.test.2",
"port": 8888,
"service": "nacos.test.2",
"healthy": false,
"ip": "10.10.10.10",
"clusterName": "DEFAULT",
"weight": 1.0
发送实例心跳
描述
发送某个实例的心跳
请求类型
PUT
请求路径
/nacos/v1/ns/instance/beat
请求参数
名称
类型
是否必选
描述
serviceName
字符串
服务名
ip
字符串
服务实例IP
port
int
服务实例PORT
namespaceId
字符串
命名空间ID
groupName
字符串
分组名
ephemeral
boolean
是否临时实例
beat
JSON格式字符串
实例心跳内容
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例请求
curl -X PUT '127.0.0.1:8848/nacos/v1/ns/instance/beat?serviceName=nacos.test.2&beat=%7b%22cluster%22%3a%22c1%22%2c%22ip%22%3a%22127.0.0.1%22%2c%22metadata%22%3a%7b%7d%2c%22port%22%3a8080%2c%22scheduled%22%3atrue%2c%22serviceName%22%3a%22jinhan0Fx4s.173TL.net%22%2c%22weight%22%3a1%7d'
示例返回
ok
创建服务
描述
创建一个服务
请求类型
POST
请求路径
/nacos/v1/ns/service
请求参数
名称
类型
是否必选
描述
serviceName
字符串
服务名
groupName
字符串
分组名
namespaceId
字符串
命名空间ID
protectThreshold
浮点数
保护阈值,取值0到1,默认0
metadata
字符串
元数据
selector
JSON格式字符串
访问策略
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例请求
curl -X POST '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2&metadata=k1%3dv1'
示例返回
ok
删除服务
描述
删除一个服务,只有当服务下实例数为0时允许删除
请求类型
DELETE
请求路径
/nacos/v1/ns/service
请求参数
名称
类型
是否必选
描述
serviceName
字符串
服务名
groupName
字符串
分组名
namespaceId
字符串
命名空间ID
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例请求
curl -X DELETE '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2'
示例返回
ok
修改服务
描述
更新一个服务
请求类型
PUT
请求路径
/nacos/v1/ns/service
请求参数
名称
类型
是否必选
描述
serviceName
字符串
服务名
groupName
字符串
分组名
namespaceId
字符串
命名空间ID
protectThreshold
浮点数
保护阈值,取值0到1,默认0
metadata
字符串
元数据
selector
JSON格式字符串
访问策略
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例请求
curl -X PUT '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2&metadata=k1%3dv1'
示例返回
ok
查询服务
描述
查询一个服务
请求类型
GET
请求路径
/nacos/v1/ns/service
请求参数
名称
类型
是否必选
描述
serviceName
字符串
服务名
groupName
字符串
分组名
namespaceId
字符串
命名空间ID
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例请求
curl -X GET '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2'
示例返回
metadata: { },
groupName: "DEFAULT_GROUP",
namespaceId: "public",
name: "nacos.test.2",
selector: {
type: "none"
},
protectThreshold: 0,
clusters: [
healthChecker: {
type: "TCP"
},
metadata: { },
name: "c1"
查询服务列表
描述
查询服务列表
请求类型
GET
请求路径
/nacos/v1/ns/service/list
请求参数
名称
类型
是否必选
描述
pageNo
int
当前页码
pageSize
int
分页大小
groupName
字符串
分组名
namespaceId
字符串
命名空间ID
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例请求
curl -X GET '127.0.0.1:8848/nacos/v1/ns/service/list?pageNo=1&pageSize=2'
示例返回
"count":148,
"doms": [
"nacos.test.1",
"nacos.test.2"
查询系统开关
描述
查询系统开关
请求类型
GET
请求路径
/nacos/v1/ns/operator/switches
请求参数
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例请求
curl -X GET '127.0.0.1:8848/nacos/v1/ns/operator/switches'
示例返回
name: "00-00---000-NACOS_SWITCH_DOMAIN-000---00-00",
masters: null,
adWeightMap: { },
defaultPushCacheMillis: 10000,
clientBeatInterval: 5000,
defaultCacheMillis: 3000,
distroThreshold: 0.7,
healthCheckEnabled: true,
distroEnabled: true,
enableStandalone: true,
pushEnabled: true,
checkTimes: 3,
httpHealthParams: {
max: 5000,
min: 500,
factor: 0.85
},
tcpHealthParams: {
max: 5000,
min: 1000,
factor: 0.75
},
mysqlHealthParams: {
max: 3000,
min: 2000,
factor: 0.65
},
incrementalList: [ ],
serverStatusSynchronizationPeriodMillis: 15000,
serviceStatusSynchronizationPeriodMillis: 5000,
disableAddIP: false,
sendBeatOnly: false,
limitedUrlMap: { },
distroServerExpiredMillis: 30000,
pushGoVersion: "0.1.0",
pushJavaVersion: "0.1.0",
pushPythonVersion: "0.4.3",
pushCVersion: "1.0.12",
enableAuthentication: false,
overriddenServerStatus: "UP",
defaultInstanceEphemeral: true,
healthCheckWhiteList: [ ],
checksum: null
修改系统开关
描述
修改系统开关
请求类型
PUT
请求路径
/nacos/v1/ns/operator/switches
请求参数
名称
类型
是否必选
描述
entry
字符串
开关名
value
字符串
开关值
debug
boolean
是否只在本机生效,true表示本机生效,false表示集群生效
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例请求
curl -X PUT '127.0.0.1:8848/nacos/v1/ns/operator/switches?entry=pushEnabled&value=false&debug=true'
示例返回
ok
查看系统当前数据指标
描述
查看系统当前数据指标
请求类型
GET
请求路径
/nacos/v1/ns/operator/metrics
请求参数
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例请求
curl -X GET '127.0.0.1:8848/nacos/v1/ns/operator/metrics'
示例返回
serviceCount: 336,
load: 0.09,
mem: 0.46210432,
responsibleServiceCount: 98,
instanceCount: 4,
cpu: 0.010242796,
status: "UP",
responsibleInstanceCount: 0
查看当前集群Server列表
描述
查看当前集群Server列表
请求类型
GET
请求路径
/nacos/v1/ns/operator/servers
请求参数
名称
类型
是否必选
描述
healthy
boolean
是否只返回健康Server节点
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例请求
curl -X GET '127.0.0.1:8848/nacos/v1/ns/operator/servers'
示例返回
servers: [
ip: "1.1.1.1",
servePort: 8848,
site: "unknown",
weight: 1,
adWeight: 0,
alive: false,
lastRefTime: 0,
lastRefTimeStr: null,
key: "1.1.1.1:8848"
},
ip: "1.1.1.2",
servePort: 8848,
site: "unknown",
weight: 1,
adWeight: 0,
alive: false,
lastRefTime: 0,
lastRefTimeStr: null,
key: "1.1.1.2:8848"
},
ip: "1.1.1.3",
servePort: 8848,
site: "unknown",
weight: 1,
adWeight: 0,
alive: false,
lastRefTime: 0,
lastRefTimeStr: null,
key: "1.1.1.3:8848"
查看当前集群leader
描述
查看当前集群leader
请求类型
GET
请求路径
/nacos/v1/ns/raft/leader
请求参数
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例请求
curl -X GET '127.0.0.1:8848/nacos/v1/ns/raft/leader'
示例返回
leader: "{"heartbeatDueMs":2500,"ip":"1.1.1.1:8848","leaderDueMs":12853,"state":"LEADER","term":54202,"voteFor":"1.1.1.1:8848"}"
更新实例的健康状态
描述
更新实例的健康状态,仅在集群的健康检查关闭时才生效,当集群配置了健康检查时,该接口会返回错误
请求类型
PUT
请求路径
/nacos/v1/ns/health/instance
请求参数
名称
类型
是否必选
描述
namespaceId
字符串
命名空间ID
serviceName
字符串
服务名
groupName
字符串
分组名
clusterName
字符串
集群名
ip
字符串
服务实例IP
port
int
服务实例port
healthy
boolean
是否健康
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例请求
curl -X PUT 'http://127.0.0.1:8848/nacos/v1/ns/health/instance?port=8848&healthy=true&ip=11.11.11.11&serviceName=nacos.test.3&namespaceId=n1'
示例返回
ok
批量更新实例元数据(Beta)
描述
批量更新实例元数据(1.4起)
注意：该接口为Beta接口，后续版本可能有所修改，甚至删除，请谨慎使用。
请求类型
PUT
请求路径
/nacos/v1/ns/instance/metadata/batch
请求参数
名称
类型
是否必选
描述
namespaceId
字符串
命名空间ID
serviceName
字符串
服务名(group@@serviceName)
consistencyType
字符串
实例的类型(ephemeral/persist)
instances
JSON格式字符串
需要更新的实例
metadata
JSON格式字符串
元数据信息
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
参数说明
consistencyType: 优先级高于instances参数，如果进行配置，则忽略instances参数的值。当值为'ephemeral'，则对serviceName下的所有非持久化实例进行更新。当值为'persist'，则对serviceName下的所有持久化实例进行更新。当为其他值，没有实例进行更新。
instances: json数组。通过ip+port+ephemeral+cluster定位到某一实例。
示例请求
curl -X PUT 'http://localhost:8848/nacos/v1/ns/instance/metadata/batch' -d 'namespaceId=public&serviceName=xxxx@@xxxx&instances=[{"ip":"3.3.3.3","port": "8080","ephemeral":"true","clusterName":"xxxx-cluster"},{"ip":"2.2.2.2","port":"8080","ephemeral":"true","clusterName":"xxxx-cluster"}]&metadata={"age":"20","name":"cocolan"}'
or
curl -X PUT 'http://localhost:8848/nacos/v1/ns/instance/metadata/batch' -d 'namespaceId=public&serviceName=xxxx@@xxxx&consistencyType=ephemeral&metadata={"age":"20","name":"cocolan"}'
示例返回
{"updated":["2.2.2.2:8080:unknown:xxxx-cluster:ephemeral","3.3.3.3:8080:unknown:xxxx-cluster:ephemeral"]}
批量删除实例元数据(Beta)
描述
批量删除实例元数据(1.4起)
注意：该接口为Beta接口，后续版本可能有所修改，甚至删除，请谨慎使用。
请求类型
DELETE
请求路径
/nacos/v1/ns/instance/metadata/batch
请求参数
名称
类型
是否必选
描述
namespaceId
字符串
命名空间ID
serviceName
字符串
服务名(group@@serviceName)
consistencyType
字符串
实例的类型(ephemeral/persist)
instances
JSON格式字符串
需要更新的实例
metadata
JSON格式字符串
元数据信息
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
参数说明
consistencyType: 优先级高于instances参数，如果进行配置，则忽略instances参数的值。当值为ephemeral，则对serviceName下的所有非持久化实例进行更新。当值为persist，则对serviceName下的所有持久化实例进行更新。当为其他值，没有实例进行更新。
instances: json数组。通过ip+port+ephemeral+cluster定位到某一实例。
示例请求
curl -X DELETE 'http://localhost:8848/nacos/v1/ns/instance/metadata/batch' -d 'namespaceId=public&serviceName=xxxx@@xxxx&instances=[{"ip":"3.3.3.3","port": "8080","ephemeral":"true","clusterName":"xxxx-cluster"},{"ip":"2.2.2.2","port":"8080","ephemeral":"true","clusterName":"xxxx-cluster"}]&metadata={"age":"20","name":"cocolan"}'
or
curl -X DELETE 'http://localhost:8848/nacos/v1/ns/instance/metadata/batch' -d 'namespaceId=public&serviceName=xxxx@@xxxx&consistencyType=ephemeral&metadata={"age":"20","name":"cocolan"}'
示例返回
{"updated":["2.2.2.2:8080:unknown:xxxx-cluster:ephemeral","3.3.3.3:8080:unknown:xxxx-cluster:ephemeral"]}
命名空间
查询命名空间列表
请求类型
GET
请求路径
/nacos/v1/console/namespaces
请求参数
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例请求
curl -X GET 'http://localhost:8848/nacos/v1/console/namespaces'
示例返回
{"code":200,"message":null,"data":[{"namespace":"","namespaceShowName":"public","quota":200,"configCount":0,"type":0}]}
创建命名空间
请求类型
POST
请求路径
/nacos/v1/console/namespaces
请求参数
名称
类型
是否必选
描述
customNamespaceId
字符串
命名空间ID
namespaceName
字符串
命名空间名
namespaceDesc
字符串
命名空间描述
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例请求
curl -X POST 'http://localhost:8848/nacos/v1/console/namespaces' -d 'customNamespaceId=&namespaceName=dev&namespaceDesc='
示例返回
true
修改命名空间
请求类型
PUT
请求路径
/nacos/v1/console/namespaces
请求参数
名称
类型
是否必选
描述
namespace
字符串
命名空间ID
namespaceShowName
字符串
命名空间名
namespaceDesc
字符串
命名空间描述
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例请求
curl -X PUT 'http://localhost:8848/nacos/v1/console/namespaces' -d 'namespace=dev&namespaceShowName=开发环境2&namespaceDesc=只用于开发2'
示例返回
true
删除命名空间
请求类型
DELETE
请求路径
/nacos/v1/console/namespaces
请求参数
名称
类型
是否必选
描述
namespaceId
字符串
命名空间ID
错误编码
错误代码
描述
语义
400
Bad Request
客户端请求中的语法错误
403
Forbidden
没有权限
404
Not Found
无法找到资源
500
Internal Server Error
服务器内部错误
200
OK
正常
示例请求
curl -X DELETE 'http://localhost:8848/nacos/v1/console/namespaces' -d 'namespaceId=dev'
示例返回
true
愿景Nacos 通过提供简单易用的动态服务发现、服务配置、服务共享与管理等服务基础设施，帮助用户在云原生时代，在私有云、混合云或者公有云等所有云环境中，更好的构建、交付、管理自己的微服务平台，更快的复用和组合业务服务，更快的交付商业创新的价值，从而为用户赢得市场。文档概览快速开始开发者指南资源社区云服务 MSE云服务 EDAS云服务 AHAS@ 2022 The Nacos Authors | An Alibaba Middleware (Aliware) Project