目录
Open API 指南
配置管理
获取配置
描述
请求类型
请求URL
请求参数
返回参数
错误编码
示例
监听配置
描述
请求类型
请求URL
请求参数
Header 参数
参数说明
返回参数
错误编码
示例
发布配置
描述
请求类型
请求 URL
请求参数
返回参数
错误编码
示例
删除配置
描述
请求类型
请求 URL
请求参数
返回参数
错误编码
示例
服务发现
注册实例
描述
请求类型
请求路径
请求参数
示例请求
示例返回
注销实例
描述
请求类型
请求路径
请求参数
示例请求
示例返回
修改实例
描述
请求类型
请求路径
请求参数
示例请求
示例返回
查询实例列表
描述
请求类型
请求路径
请求参数
示例请求
示例返回
查询实例详情
描述
请求类型
请求路径
请求参数
示例请求
示例返回
发送实例心跳
描述
请求类型
请求路径
请求参数
示例请求
示例返回
创建服务
描述
请求类型
请求路径
请求参数
示例请求
示例返回
删除服务
描述
请求类型
请求路径
请求参数
示例请求
示例返回
修改服务
描述
请求类型
请求路径
请求参数
示例请求
示例返回
查询服务
描述
请求类型
请求路径
请求参数
示例请求
示例返回
查询服务列表
描述
请求类型
请求路径
请求参数
示例请求
示例返回
查询系统开关
描述
请求类型
请求路径
请求参数
示例请求
示例返回
修改系统开关
描述
请求类型
请求路径
请求参数
示例请求
示例返回
查看系统当前数据指标
描述
请求类型
请求路径
请求参数
示例请求
示例返回
查看当前集群Server列表
描述
请求类型
请求路径
请求参数
示例请求
示例返回
查看当前集群leader
描述
请求类型
请求路径
请求参数
示例请求
示例返回
更新实例的健康状态
描述
请求类型
请求路径
请求参数
示例请求
示例返回
获取Nacos上的配置。
GET
/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 | 正常 |
请求示例
http:serverIp:8848/nacos/v1/cs/configs?dataId=dataIdparam&group=groupParam&tenant=tenantParam
返回示例
contentTest
监听 Nacos 上的配置,以便实时感知配置变更。如果配置变更,则用获取配置接口获取配置的最新值,动态刷新本地缓存。
注册监听采用的是异步 Servlet 技术。注册监听本质就是带着配置和配置值的 MD5 值和后台对比。如果 MD5 值不一致,就立即返回不一致的配置。如果值一致,就等待住 30 秒。返回值为空。
POST
/nacos/v1/cs/configs/listener
名称 | 类型 | 是否必须 | 描述 |
---|---|---|---|
Listening-Configs | string | 是 | 监听数据报文。格式为 dataId^2Group^2contentMD5^2tenant^1或者dataId^2Group^2contentMD5^1。dataId:配置 IDgroup:配置分组contentMD5:配置内容 MD5 值tenant:租户信息,对应 Nacos 的命名空间字段(非必填) |
名称 | 类型 | 是否必须 | 描述 |
---|---|---|---|
Long-Pulling-Timeout | string | 是 | 长轮训等待 30s,此处填写 30000。 |
配置多个字段间分隔符:^2 = Character.toString((char) 2
配置间分隔符:^1 = Character.toString((char) 1)
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^2group^2contentMD5^2tenant^1
返回示例
如果配置变化 dataId^2group^2tenant^1 如果配置无变化:会返回空串
发布 Nacos 上的配置。
POST
/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 | 正常 |
请求示例
http:serverIp:8848/nacos/v1/cs/configs http body: dataId=dataIdparam&group=groupParam&tenant=tenantParam&content=contentParam&type=typeParam
返回示例
true
删除 Nacos 上的配置。
DELETE
/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 | 正常 |
请求示例
http:serverIp:8848/nacos/v1/cs/configs?dataId=dataIdparam&group=groupParam
返回示例
true
注册一个实例到服务。
POST
/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=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 | 否 | 是否临时实例 |
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
修改服务下的一个实例。
PUT
/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 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 | 是否只返回健康实例 |
curl -X GET 127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=nacos.test.1
{ "dom": "nacos.test.1", "cacheMillis": 1000, "useSpecifiedURL": false, "hosts": [{ "valid": true, "marked": false, "instanceId": "10.10.10.10-8888-DEFAULT-nacos.test.1", "port": 8888, "ip": "10.10.10.10", "weight": 1.0, "metadata": {} }], "checksum": "3bbcf6dd1175203a8afdade0e77a27cd1528787794594", "lastRefTime": 1528787794594, "env": "", "clusters": "" }
查询一个服务下个某个实例详情。
GET
/nacos/v1/ns/instance
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
serviceName | 字符串 | 是 | 服务名 |
groupName | 字符串 | 否 | 分组名 |
ip | 字符串 | 是 | 实例IP |
port | 字符串 | 是 | 实例端口 |
namespaceId | 字符串 | 否 | 命名空间ID |
cluster | 字符串 | 否 | 集群名称 |
healthyOnly | boolean | 否,默认为false | 是否只返回健康实例 |
ephemeral | boolean | 否 | 是否临时实例 |
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 | 字符串 | 是 | 服务名 |
groupName | 字符串 | 否 | 分组名 |
ephemeral | boolean | 否 | 是否临时实例 |
beat | JSON格式字符串 | 是 | 实例心跳内容 |
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格式字符串 | 否 | 访问策略 |
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 |
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格式字符串 | 否 | 访问策略 |
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 |
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 |
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
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表示集群生效 |
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
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列表
GET
/nacos/v1/ns/operator/servers
名称 | 类型 | 是否必选 | 描述 |
---|---|---|---|
healthy | boolean | 否 | 是否只返回健康Server节点 |
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
GET
/nacos/v1/ns/raft/leader
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 | 是 | 是否健康 |
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