本文主要介绍 Nacos 2.0.3 的 Open API。
配置管理
1、获取配置
描述
获取Nacos上的配置。
请求类型
GET
请求URL
/nacos/v1/cs/configs
请求参数
名称 | 类型 | 是否必须 | 描述 |
---|---|---|---|
tenant | string | 否 | 租户信息,对应 Nacos 的命名空间ID字段。 |
dataId | string | 是 | 配置 ID。 |
group | string | 是 | 配置分组。 |
响应参数
参数类型 | 描述 |
---|---|
string | 配置值 |
请求示例
curl -X GET 'http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=spring-boot-nacos-config&group=DEFAULT_GROUP'
响应示例
useLocalCache=true
2、监听配置
描述
监听 Nacos 上的配置,以便实时感知配置变更。如果配置变更,则用获取配置接口获取配置的最新值,动态刷新本地缓存。
注册监听采用的是异步 Servlet 技术。注册监听本质就是带着配置和配置值的 MD5 值和后台对比。如果 MD5 值不一致,就立即返回不一致的配置。如果值一致,就等待住 30 秒。返回值为空。
请求类型
POST
请求URL
/nacos/v1/cs/configs/listener
请求参数
名称 | 类型 | 是否必须 | 描述 |
---|---|---|---|
Listening-Configs | string | 是 | 监听数据报文。格式为 dataId2Group2contentMD52tenant1或者dataId2Group2contentMD5^1。dataId:配置 ID,Group:配置分组,contentMD5:配置内容 MD5值,tenant:租户信息,对应 Nacos 的命名空间字段(非必填) |
Header参数
名称 | 类型 | 是否必须 | 描述 |
---|---|---|---|
Long-Pulling-Timeout | string | 是 | 长轮询等待 30s,此处填写 30000。 |
参数说明
- 配置多个字段间分隔符:^2 = Character.toString((char) 2
- 配置间分隔符:^1 = Character.toString((char) 1)
- contentMD5: MD5(content),第一次本地缓存为空,所以这块为空串
响应参数
参数类型 | 描述 |
---|---|
string | 配置值 |
请求示例
http://127.0.0.1:8848/nacos/v1/cs/configs/listener
# POST 请求体数据内容:
Listening-Configs=spring-boot-nacos-config^2DEFAULT_GROUP^2b54f63e58da12198344316a61a93add0^1
响应示例
如果配置变化
spring-boot-nacos-config^2DEFAULT_GROUP^25a822367cd73c79acc56da3c73fa07e^1
如果配置无变化:会返回空串
3、发布配置
描述
发布 Nacos 上的配置。
请求类型
POST
请求URL
/nacos/v1/cs/configs
请求参数
名称 | 类型 | 是否必须 | 描述 |
---|---|---|---|
tenant | string | 否 | 租户信息,对应 Nacos 的命名空间ID字段 |
dataId | string | 是 | 配置 ID |
group | string | 是 | 配置分组 |
content | string | 是 | 配置内容 |
type | String | 否 | 配置类型 |
响应参数
参数类型 | 描述 |
---|---|
boolean | 是否发布成功 |
请求示例
curl -X POST 'http://127.0.0.1:8848/nacos/v1/cs/configs' -d 'dataId=nacos-example&group=cn.zwqh&content=contentTest'
响应示例
true
4、删除配置
描述
删除 Nacos 上的配置。
请求类型
DELETE
请求URL
/nacos/v1/cs/configs
请求参数
名称 | 类型 | 是否必须 | 描述 |
---|---|---|---|
tenant | string | 否 | 租户信息,对应 Naocs 的命名空间ID字段 |
dataId | string | 是 | 配置 ID |
group | string | 是 | 配置分组 |
响应参数
参数类型 | 描述 |
---|---|
boolean | 是否删除成功 |
请求示例
curl -X DELETE 'http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=nacos-example&group=cn.zwqh'
响应示例
true
5、查询历史版本
描述
查询配置项历史版本。
请求类型
GET
请求URL
/nacos/v1/cs/history?search=accurate
请求参数
名称 | 类型 | 是否必须 | 描述 |
---|---|---|---|
tenant | string | 否 | 租户信息,对应 Naocs 的命名空间ID字段 |
dataId | string | 是 | 配置 ID |
group | string | 是 | 配置分组 |
pageNo | integer | 否 | 当前页码 |
pageSize | integer | 否 | 分页条数(默认100条,最大为500) |
请求示例
curl -X GET 'http://127.0.0.1:8848/nacos/v1/cs/history?search=accurate&dataId=spring-boot-nacos-config&group=DEFAULT_GROUP'
响应示例
{
"totalCount": 3,
"pageNumber": 1,
"pagesAvailable": 1,
"pageItems": [
{
"id": "42",
"lastId": -1,
"dataId": "spring-boot-nacos-config",
"group": "DEFAULT_GROUP",
"tenant": "",
"appName": "",
"md5": null,
"content": null,
"srcIp": "172.25.0.1",
"srcUser": "",
"opType": "U",
"createdTime": "2021-08-31T11:48:22.000+08:00",
"lastModifiedTime": "2021-08-31T11:48:22.000+08:00"
},
{
"id": "41",
"lastId": -1,
"dataId": "spring-boot-nacos-config",
"group": "DEFAULT_GROUP",
"tenant": "",
"appName": "",
"md5": null,
"content": null,
"srcIp": "172.25.0.1",
"srcUser": "",
"opType": "U",
"createdTime": "2021-08-31T11:40:53.000+08:00",
"lastModifiedTime": "2021-08-31T11:40:53.000+08:00"
},
{
"id": "40",
"lastId": -1,
"dataId": "spring-boot-nacos-config",
"group": "DEFAULT_GROUP",
"tenant": "",
"appName": "",
"md5": null,
"content": null,
"srcIp": "172.25.0.1",
"srcUser": null,
"opType": "I",
"createdTime": "2021-08-31T10:27:52.000+08:00",
"lastModifiedTime": "2021-08-31T10:27:53.000+08:00"
}
]
}
6、查询历史版本详情
描述
查询配置项历史版本详情
请求类型
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非必填。
请求示例
curl -X GET 'http://127.0.0.1:8848/nacos/v1/cs/history?nid=41&tenant=&dataId=spring-boot-nacos-config&group=DEFAULT_GROUP'
响应示例
{
"id": "41",
"lastId": -1,
"dataId": "spring-boot-nacos-config",
"group": "DEFAULT_GROUP",
"tenant": "",
"appName": "",
"md5": "25a822367cd73c79acc56da3c73fa07e",
"content": "useLocalCache=true",
"srcIp": "172.25.0.1",
"srcUser": "",
"opType": "U",
"createdTime": "2021-08-31T11:40:53.000+08:00",
"lastModifiedTime": "2021-08-31T11:40:53.000+08:00"
}
7、查询配置上一版本信息
描述
查询配置上一版本信息(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非必填。
请求示例
curl -X GET 'http://127.0.0.1:8848/nacos/v1/cs/history/previous?id=42&tenant=&dataId=spring-boot-nacos-config&group=DEFAULT_GROUP'
响应示例
{
"id": "41",
"lastId": -1,
"dataId": "spring-boot-nacos-config",
"group": "DEFAULT_GROUP",
"tenant": "",
"appName": "",
"md5": "25a822367cd73c79acc56da3c73fa07e",
"content": "useLocalCache=true",
"srcIp": "172.25.0.1",
"srcUser": "",
"opType": "U",
"createdTime": "2021-08-31T11:40:53.000+08:00",
"lastModifiedTime": "2021-08-31T11:40:53.000+08:00"
}
服务发现
1、注册实例
描述
注册一个实例到服务。
请求类型
POST
请求URL
/nacos/v1/ns/instance
请求参数
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
ip | 字符串 | 是 | 服务实例IP |
port | int | 是 | 服务实例port |
namespaceId | 字符串 | 否 | 命名空间ID |
weight | double | 否 | 权重 |
enabled | boolean | 否 | 是否上线 |
healthy | boolean | 否 | 是否健康 |
metadata | 字符串 | 否 | 扩展信息 |
clusterName | 字符串 | 否 | 集群名 |
serviceName | 字符串 | 是 | 服务名 |
groupName | 字符串 | 否 | 分组名 |
ephemeral | boolean | 否 | 是否临时实例 |
请求示例
curl -X POST 'http://127.0.0.1:8848/nacos/v1/ns/instance?port=8080&healthy=true&ip=127.0.0.1&weight=1.0&serviceName=nacos.test.service&encoding=GBK&namespaceId=dev'
响应示例
ok
2、注销实例
描述
删除服务下的一个实例。
请求类型
DELETE
请求URL
/nacos/v1/ns/instance
请求参数
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
serviceName | 字符串 | 是 | 服务名 |
groupName | 字符串 | 否 | 分组名 |
ip | 字符串 | 是 | 服务实例IP |
port | int | 是 | 服务实例port |
clusterName | 字符串 | 否 | 集群名称 |
namespaceId | 字符串 | 否 | 命名空间ID |
ephemeral | boolean | 否 | 是否临时实例 |
请求示例
curl -X DELETE 'http://127.0.0.1:8848/nacos/v1/ns/instance?serviceName=nacos.test.service&ip=127.0.0.1&port=8080&clusterName='
响应示例
ok
3、修改实例
描述
修改服务下的一个实例。
注意:在Nacos2.0版本后,通过该接口更新的元数据拥有更高的优先级,且具有记忆能力;会在对应实例删除后,依旧存在一段时间,如果在此期间实例重新注册,该元数据依旧生效;您可以通过nacos.naming.clean.expired-metadata.expired-time
及nacos.naming.clean.expired-metadata.interval
对记忆时间进行修改
请求类型
PUT
请求URL
/nacos/v1/ns/instance
请求参数
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
serviceName | 字符串 | 是 | 服务名 |
groupName | 字符串 | 否 | 分组名 |
ip | 字符串 | 是 | 服务实例IP |
port | int | 是 | 服务实例port |
clusterName | 字符串 | 否 | 集群名称 |
namespaceId | 字符串 | 否 | 命名空间ID |
weight | double | 否 | 权重 |
metadata | JSON | 否 | 扩展信息 |
enabled | boolean | 否 | 是否打开流量 |
ephemeral | boolean | 否 | 是否临时实例 |
请求示例
curl -X PUT 'http://127.0.0.1:8848/nacos/v1/ns/instance?serviceName=nacos.test.service&ip=127.0.0.1&port=8080&clusterName=TEST1&weight=8&metadata={}'
响应示例
ok
4、查询实例列表
描述
查询服务下的实例列表
请求类型
GET
请求URL
/nacos/v1/ns/instance/list
请求参数
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
serviceName | 字符串 | 是 | 服务名 |
groupName | 字符串 | 否 | 分组名 |
namespaceId | 字符串 | 否 | 命名空间ID |
clusters | 字符串,多个集群用逗号分隔 | 否 | 集群名称 |
healthyOnly | boolean | 否,默认为false | 是否只返回健康实例 |
请求示例
curl -X GET 'http://127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=nacos.test.service'
响应示例
{
"name": "DEFAULT_GROUP@@nacos.test.service",
"groupName": "DEFAULT_GROUP",
"clusters": "",
"cacheMillis": 10000,
"hosts": [],
"lastRefTime": 1630395849928,
"checksum": "",
"allIPs": false,
"reachProtectionThreshold": false,
"valid": true
}
5、发送实例心跳
描述
发送某个实例的心跳
请求类型
PUT
请求URL
/nacos/v1/ns/instance/beat
请求参数
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
serviceName | 字符串 | 是 | 服务名 |
groupName | 字符串 | 否 | 分组名 |
ephemeral | boolean | 否 | 是否临时实例 |
beat | JSON格式字符串 | 是 | 实例心跳内容 |
请求示例
curl -X PUT 'http://127.0.0.1:8848/nacos/v1/ns/instance/beat?serviceName=nacos.test.service&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%22nacos.test.service%22%2C%22weight%22%3A1%7D'
响应示例
{
"clientBeatInterval": 5000,
"code": 10200, # 10200源码中代表ok
"lightBeatEnabled": true
}
6、创建服务
描述
创建一个服务
请求类型
POST
请求URL
/nacos/v1/ns/service
请求参数
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
serviceName | 字符串 | 是 | 服务名 |
groupName | 字符串 | 否 | 分组名 |
namespaceId | 字符串 | 否 | 命名空间ID |
protectThreshold | 浮点数 | 否 | 保护阈值,取值0到1,默认0 |
metadata | 字符串 | 否 | 元数据 |
selector | JSON格式字符串 | 否 | 访问策略 |
请求示例
curl -X POST 'http://127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.service&metadata=k1%3dv1'
响应示例
ok
7、删除服务
描述
删除一个服务,只有当服务下实例数为0时允许删除
请求类型
DELETE
请求URL
/nacos/v1/ns/service
请求参数
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
serviceName | 字符串 | 是 | 服务名 |
groupName | 字符串 | 否 | 分组名 |
namespaceId | 字符串 | 否 | 命名空间ID |
请求示例
curl -X DELETE 'http://127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.service'
响应示例
ok
8、修改服务
描述
更新一个服务
请求类型
PUT
请求URL
/nacos/v1/ns/service
请求参数
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
serviceName | 字符串 | 是 | 服务名 |
groupName | 字符串 | 否 | 分组名 |
namespaceId | 字符串 | 否 | 命名空间ID |
protectThreshold | 浮点数 | 是 | 保护阈值,取值0到1,默认0 |
metadata | 字符串 | 否 | 元数据 |
selector | JSON格式字符串 | 否 | 访问策略 |
请求示例
curl -X PUT 'http://127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.service&protectThreshold=0&metadata=k1%3dv1'
响应示例
ok
9、查询服务
描述
查询一个服务
请求类型
GET
请求URL
/nacos/v1/ns/service
请求参数
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
serviceName | 字符串 | 是 | 服务名 |
groupName | 字符串 | 否 | 分组名 |
namespaceId | 字符串 | 否 | 命名空间ID |
请求示例
curl -X GET 'http://127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.service'
响应示例
{
"namespaceId": "public",
"groupName": "DEFAULT_GROUP",
"name": "nacos.test.service",
"protectThreshold": 0,
"metadata": {},
"selector": {
"type": "none"
},
"clusters": []
}
10、查询服务列表
描述
查询服务列表
请求类型
GET
请求URL
/nacos/v1/ns/service/list
请求参数
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
pageNo | int | 是 | 当前页码 |
pageSize | int | 是 | 分页大小 |
groupName | 字符串 | 否 | 分组名 |
namespaceId | 字符串 | 否 | 命名空间ID |
请求示例
curl -X GET 'http://127.0.0.1:8848/nacos/v1/ns/service/list?pageNo=1&pageSize=2'
响应示例
{
"doms": [
"nacos.test.service"
],
"count": 1
}
11、查询系统开关
描述
查询系统开关
请求类型
GET
请求URL
/nacos/v1/ns/operator/switches
请求参数
无
请求示例
curl -X GET 'http://127.0.0.1:8848/nacos/v1/ns/operator/switches'
响应示例
{
"masters": null,
"adWeightMap": {},
"defaultPushCacheMillis": 10000,
"clientBeatInterval": 5000,
"defaultCacheMillis": 3000,
"distroThreshold": 0.7,
"healthCheckEnabled": true,
"autoChangeHealthCheckEnabled": 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": 2000,
"serviceStatusSynchronizationPeriodMillis": 5000,
"disableAddIP": false,
"sendBeatOnly": false,
"lightBeatEnabled": true,
"doubleWriteEnabled": true,
"limitedUrlMap": {},
"distroServerExpiredMillis": 10000,
"pushGoVersion": "0.1.0",
"pushJavaVersion": "0.1.0",
"pushPythonVersion": "0.4.3",
"pushCVersion": "1.0.12",
"pushCSharpVersion": "0.9.0",
"enableAuthentication": false,
"overriddenServerStatus": null,
"defaultInstanceEphemeral": true,
"healthCheckWhiteList": [],
"checksum": null,
"name": "00-00---000-NACOS_SWITCH_DOMAIN-000---00-00"
}
12、修改系统开关
描述
修改系统开关
请求类型
PUT
请求URL
/nacos/v1/ns/operator/switches
请求参数
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
entry | 字符串 | 是 | 开关名 |
value | 字符串 | 是 | 开关值 |
debug | boolean | 否 | 是否只在本机生效,true表示本机生效,false表示集群生效 |
请求示例
curl -X PUT 'http://127.0.0.1:8848/nacos/v1/ns/operator/switches?entry=pushEnabled&value=false&debug=true'
响应示例
ok
13、查看系统当前数据指标
描述
查看系统当前数据指标
请求类型
GET
请求URL
/nacos/v1/ns/operator/metrics
请求参数
无
请求示例
curl -X GET 'http://127.0.0.1:8848/nacos/v1/ns/operator/metrics'
响应示例
{
"status": "UP"
}
14、查看当前集群Server列表
描述
查看当前集群Server列表
请求类型
GET
请求URL
/nacos/v1/ns/operator/servers
请求参数
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
healthy | boolean | 否 | 是否只返回健康Server节点 |
请求示例
curl -X GET 'http://127.0.0.1:8848/nacos/v1/ns/operator/servers?healthy=false'
响应示例
{
"servers": [
{
"ip": "1095a768f287",
"port": 8848,
"state": "UP",
"extendInfo": {
"lastRefreshTime": 1630373352190,
"raftMetaData": {
"metaDataMap": {
"naming_instance_metadata": {
"leader": "1095a768f287:7848",
"raftGroupMember": [
"1095a768f287:7848"
],
"term": 2
},
"naming_persistent_service_v2": {
"leader": "1095a768f287:7848",
"raftGroupMember": [
"1095a768f287:7848"
],
"term": 2
},
"naming_service_metadata": {
"raftGroupMember": [
"1095a768f287:7848"
]
}
}
},
"raftPort": "7848",
"version": "2.0.3"
},
"address": "1095a768f287:8848",
"failAccessCnt": 0,
"abilities": {
"remoteAbility": {
"supportRemoteConnection": true
},
"configAbility": {
"supportRemoteMetrics": false
},
"namingAbility": {
"supportJraft": true
}
}
}
]
}
15、更新实例的健康状态
描述
更新实例的健康状态,仅在集群的健康检查关闭时才生效,当集群配置了健康检查时,该接口会返回错误
请求类型
PUT
请求URL
/nacos/v1/ns/health/instance
请求参数
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
namespaceId | 字符串 | 否 | 命名空间ID |
serviceName | 字符串 | 是 | 服务名 |
groupName | 字符串 | 否 | 分组名 |
clusterName | 字符串 | 否 | 集群名 |
ip | 字符串 | 是 | 服务实例IP |
port | int | 是 | 服务实例port |
healthy | boolean | 是 | 是否健康 |
请求示例
curl -X PUT 'http://127.0.0.1:8848/nacos/v1/ns/health/instance?port=8080&healthy=true&ip=127.0.0.1&serviceName=nacos.test.service&namespaceId=public'
响应示例
ok
命名空间
1、查询命名空间列表
描述
查询命名空间列表
请求类型
GET
请求URL
/nacos/v1/console/namespaces
请求参数
无
请求示例
curl -X GET 'http://127.0.0.1:8848/nacos/v1/console/namespaces'
响应示例
{
"code": 200,
"message": null,
"data": [
{
"namespace": "",
"namespaceShowName": "public",
"quota": 200,
"configCount": 8,
"type": 0
},
{
"namespace": "dev",
"namespaceShowName": "dev",
"quota": 200,
"configCount": 1,
"type": 2
},
{
"namespace": "prod",
"namespaceShowName": "prod",
"quota": 200,
"configCount": 0,
"type": 2
},
{
"namespace": "test",
"namespaceShowName": "test",
"quota": 200,
"configCount": 0,
"type": 2
}
]
}
2、创建命名空间
描述
创建命名空间
请求类型
POST
请求URL
/nacos/v1/console/namespaces
请求参数
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
customNamespaceId | 字符串 | 是 | 命名空间ID |
namespaceName | 字符串 | 是 | 命名空间名 |
namespaceDesc | 字符串 | 否 | 命名空间描述 |
请求示例
curl -X POST 'http://127.0.0.1:8848/nacos/v1/console/namespaces?customNamespaceId=qa&namespaceName=qa&namespaceDesc=ceshi'
响应示例
true
3、修改命名空间
描述
修改命名空间
请求类型
PUT
请求URL
/nacos/v1/console/namespaces
请求参数
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
namespace | 字符串 | 是 | 命名空间ID |
namespaceShowName | 字符串 | 是 | 命名空间名 |
namespaceDesc | 字符串 | 是 | 命名空间描述 |
请求示例
curl -X PUT 'http://127.0.0.1:8848/nacos/v1/console/namespaces?namespaceId=qa&namespaceName=测试环境&namespaceDesc=测试环境'
响应示例
true
4、删除命名空间
描述
删除命名空间
请求类型
DELETE
请求URL
/nacos/v1/console/namespaces
请求参数
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
namespaceId | 字符串 | 是 | 命名空间ID |
请求示例
curl -X DELETE 'http://127.0.0.1:8848/nacos/v1/console/namespaces?namespaceId=qa'
响应示例
true
错误编码
错误代码 | 描述 | 语义 |
---|---|---|
400 | Bad Request | 客户端请求中的语法错误 |
403 | Forbidden | 没有权限 |
404 | Not Found | 无法找到资源 |
500 | Internal Server Error | 服务器内部错误 |
200 | OK | 正常 |
评论区