Open API 指南

配置管理

获取配置

描述

获取Nacos上的配置。

请求类型

GET

请求URL

/nacos/v1/cs/configs

请求参数

名称类型是否必须描述
tenantstring否租户信息，对应 Nacos 的命名空间ID字段。
dataIdstring是配置 ID。
groupstring是配置分组。

返回参数

参数类型描述
string配置值

错误编码

错误代码描述语义
400Bad Request客户端请求中的语法错误
403Forbidden没有权限
404Not Found无法找到资源
500Internal Server Error服务器内部错误
200OK正常

示例

  • 请求示例 
    1. http:serverIp:8848/nacos/v1/cs/configs?dataId=dataIdparam&group=groupParam&tenant=tenantParam
  • 返回示例 
    1. 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-Timeoutstring是长轮训等待 30s，此处填写 30000。

参数说明

  • 配置多个字段间分隔符：^2 = Character.toString((char) 2
  • 配置间分隔符：^1 = Character.toString((char) 1)
  • contentMD5: MD5(content)，第一次本地缓存为空，所以这块为空串

返回参数

参数类型描述
string配置值

错误编码

错误代码描述语义
400Bad Request客户端请求中的语法错误
403Forbidden没有权限
404Not Found无法找到资源
500Internal Server Error服务器内部错误
200OK正常

示例

  • 请求示例
  1. http://serverIp:8848/nacos/v1/cs/configs/listener
  3. POST 请求体数据内容：
  5. Listening-Configs=dataId^2group^2contentMD5^2tenant^1
  • 返回示例
  1. 如果配置变化
  3. dataId^2group^2tenant^1
  5. 如果配置无变化：会返回空串

发布配置

描述

发布 Nacos 上的配置。

请求类型

POST

请求 URL

/nacos/v1/cs/configs

请求参数

名称类型是否必须描述
tenantstring否租户信息，对应 Nacos 的命名空间ID字段
dataIdstring是配置 ID
groupstring是配置分组
contentstring是配置内容
typeString否配置类型

返回参数

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

错误编码

错误代码描述语义
400Bad Request客户端请求中的语法错误
403Forbidden没有权限
404Not Found无法找到资源
500Internal Server Error服务器内部错误
200OK正常

示例

  • 请求示例
  1. http:serverIp:8848/nacos/v1/cs/configs
  3. http body：
  4. dataId=dataIdparam&group=groupParam&tenant=tenantParam&content=contentParam&type=typeParam
  • 返回示例
  1. true

删除配置

描述

删除 Nacos 上的配置。

请求类型

DELETE

请求 URL

/nacos/v1/cs/configs

请求参数

名称类型是否必须描述
tenantstring否租户信息，对应 Naocs 的命名空间ID字段
dataIdstring是配置 ID
groupstring是配置分组

返回参数

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

错误编码

错误代码描述语义
400Bad Request客户端请求中的语法错误
403Forbidden没有权限
404Not Found无法找到资源
500Internal Server Error服务器内部错误
200OK正常

示例

  • 请求示例
  1. http:serverIp:8848/nacos/v1/cs/configs?dataId=dataIdparam&group=groupParam
  • 返回示例
  1. true

服务发现

注册实例

描述

注册一个实例到服务。

请求类型

POST

请求路径

  1. /nacos/v1/ns/instance

请求参数

名称类型是否必选描述
ip字符串是服务实例IP
portint是服务实例port
namespaceId字符串否命名空间ID
weightdouble否权重
enabledboolean否是否上线
healthyboolean否是否健康
metadata字符串否扩展信息
clusterName字符串否集群名
serviceName字符串是服务名
groupName字符串否分组名
ephemeralboolean否是否临时实例

示例请求

  1. 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

请求路径

  1. /nacos/v1/ns/instance

请求参数

名称类型是否必选描述
serviceName字符串是服务名
groupName字符串否分组名
ip字符串是服务实例IP
portint是服务实例port
clusterName字符串否集群名称
namespaceId字符串否命名空间ID
ephemeralboolean否是否临时实例

示例请求

  1. 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

请求路径

  1. /nacos/v1/ns/instance

请求参数

名称类型是否必选描述
serviceName字符串是服务名
groupName字符串否分组名
ip字符串是服务实例IP
portint是服务实例port
clusterName字符串否集群名称
namespaceId字符串否命名空间ID
weightdouble否权重
metadataJSON否扩展信息
enabledboolean否是否打开流量
ephemeralboolean否是否临时实例

示例请求

  1. 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

请求路径

  1. /nacos/v1/ns/instance/list

请求参数

名称类型是否必选描述
serviceName字符串是服务名
groupName字符串否分组名
namespaceId字符串否命名空间ID
clusters字符串，多个集群用逗号分隔否集群名称
healthyOnlyboolean否，默认为false是否只返回健康实例

示例请求

  1. curl -X GET 127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=nacos.test.1

示例返回

  1. {
  2.     "dom": "nacos.test.1",
  3.     "cacheMillis": 1000,
  4.     "useSpecifiedURL": false,
  5.     "hosts": [{
  6.         "valid": true,
  7.         "marked": false,
  8.         "instanceId": "10.10.10.10-8888-DEFAULT-nacos.test.1",
  9.         "port": 8888,
  10.         "ip": "10.10.10.10",
  11.         "weight": 1.0,
  12.         "metadata": {}
  13.     }],
  14.     "checksum": "3bbcf6dd1175203a8afdade0e77a27cd1528787794594",
  15.     "lastRefTime": 1528787794594,
  16.     "env": "",
  17.     "clusters": ""
  18. }

查询实例详情

描述

查询一个服务下个某个实例详情。

请求类型

GET

请求路径

  1. /nacos/v1/ns/instance

请求参数

名称类型是否必选描述
serviceName字符串是服务名
groupName字符串否分组名
ip字符串是实例IP
port字符串是实例端口
namespaceId字符串否命名空间ID
cluster字符串否集群名称
healthyOnlyboolean否，默认为false是否只返回健康实例
ephemeralboolean否是否临时实例

示例请求

  1. 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'

示例返回

  1. {
  2.     "metadata": {},
  3.     "instanceId": "10.10.10.10-8888-DEFAULT-nacos.test.2",
  4.     "port": 8888,
  5.     "service": "nacos.test.2",
  6.     "healthy": false,
  7.     "ip": "10.10.10.10",
  8.     "clusterName": "DEFAULT",
  9.     "weight": 1.0
  10. }

发送实例心跳

描述

发送某个实例的心跳

请求类型

PUT

请求路径

  1. /nacos/v1/ns/instance/beat

请求参数

名称类型是否必选描述
serviceName字符串是服务名
groupName字符串否分组名
ephemeralboolean否是否临时实例
beatJSON格式字符串是实例心跳内容

示例请求

  1. 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'

示例返回

  1. ok

创建服务

描述

创建一个服务

请求类型

POST

请求路径

  1. /nacos/v1/ns/service

请求参数

名称类型是否必选描述
serviceName字符串是服务名
groupName字符串否分组名
namespaceId字符串否命名空间ID
protectThreshold浮点数否保护阈值,取值0到1,默认0
metadata字符串否元数据
selectorJSON格式字符串否访问策略

示例请求

  1. curl -X POST '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2&metadata=k1%3dv1'

示例返回

  1. ok

删除服务

描述

删除一个服务,只有当服务下实例数为0时允许删除

请求类型

DELETE

请求路径

  1. /nacos/v1/ns/service

请求参数

名称类型是否必选描述
serviceName字符串是服务名
groupName字符串否分组名
namespaceId字符串否命名空间ID

示例请求

  1. curl -X DELETE '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2'

示例返回

  1. ok

修改服务

描述

更新一个服务

请求类型

PUT

请求路径

  1. /nacos/v1/ns/service

请求参数

名称类型是否必选描述
serviceName字符串是服务名
groupName字符串否分组名
namespaceId字符串否命名空间ID
protectThreshold浮点数否保护阈值,取值0到1,默认0
metadata字符串否元数据
selectorJSON格式字符串否访问策略

示例请求

  1. curl -X PUT '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2&metadata=k1%3dv1'

示例返回

  1. ok

查询服务

描述

查询一个服务

请求类型

GET

请求路径

  1. /nacos/v1/ns/service

请求参数

名称类型是否必选描述
serviceName字符串是服务名
groupName字符串否分组名
namespaceId字符串否命名空间ID

示例请求

  1. curl -X GET '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2'

示例返回

  1. {
  2.     metadata: { },
  3.     groupName: "DEFAULT_GROUP",
  4.     namespaceId: "public",
  5.     name: "nacos.test.2",
  6.     selector: {
  7.         type: "none"
  8.     },
  9.     protectThreshold: 0,
  10.     clusters: [
  11.         {
  12.             healthChecker: {
  13.                 type: "TCP"
  14.             },
  15.             metadata: { },
  16.             name: "c1"
  17.         }
  18.     ]
  19. }

查询服务列表

描述

查询服务列表

请求类型

GET

请求路径

  1. /nacos/v1/ns/service/list

请求参数

名称类型是否必选描述
pageNoint是当前页码
pageSizeint是分页大小
groupName字符串否分组名
namespaceId字符串否命名空间ID

示例请求

  1. curl -X GET '127.0.0.1:8848/nacos/v1/ns/service/list?pageNo=1&pageSize=2'

示例返回

  1. {
  2.     "count":148,
  3.     "doms": [
  4.         "nacos.test.1",
  5.         "nacos.test.2"
  6.     ]
  7. }

查询系统开关

描述

查询系统开关

请求类型

GET

请求路径

  1. /nacos/v1/ns/operator/switches

请求参数

示例请求

  1. curl -X GET '127.0.0.1:8848/nacos/v1/ns/operator/switches'

示例返回

  1. {
  2.     name: "00-00---000-NACOS_SWITCH_DOMAIN-000---00-00",
  3.     masters: null,
  4.     adWeightMap: { },
  5.     defaultPushCacheMillis: 10000,
  6.     clientBeatInterval: 5000,
  7.     defaultCacheMillis: 3000,
  8.     distroThreshold: 0.7,
  9.     healthCheckEnabled: true,
  10.     distroEnabled: true,
  11.     enableStandalone: true,
  12.     pushEnabled: true,
  13.     checkTimes: 3,
  14.     httpHealthParams: {
  15.         max: 5000,
  16.         min: 500,
  17.         factor: 0.85
  18.     },
  19.     tcpHealthParams: {
  20.         max: 5000,
  21.         min: 1000,
  22.         factor: 0.75
  23.     },
  24.     mysqlHealthParams: {
  25.         max: 3000,
  26.         min: 2000,
  27.         factor: 0.65
  28.     },
  29.     incrementalList: [ ],
  30.     serverStatusSynchronizationPeriodMillis: 15000,
  31.     serviceStatusSynchronizationPeriodMillis: 5000,
  32.     disableAddIP: false,
  33.     sendBeatOnly: false,
  34.     limitedUrlMap: { },
  35.     distroServerExpiredMillis: 30000,
  36.     pushGoVersion: "0.1.0",
  37.     pushJavaVersion: "0.1.0",
  38.     pushPythonVersion: "0.4.3",
  39.     pushCVersion: "1.0.12",
  40.     enableAuthentication: false,
  41.     overriddenServerStatus: "UP",
  42.     defaultInstanceEphemeral: true,
  43.     healthCheckWhiteList: [ ],
  44.     checksum: null
  45. }

修改系统开关

描述

修改系统开关

请求类型

PUT

请求路径

  1. /nacos/v1/ns/operator/switches

请求参数

名称类型是否必选描述
entry字符串是开关名
value字符串是开关值
debugboolean否是否只在本机生效,true表示本机生效,false表示集群生效

示例请求

  1. curl -X PUT '127.0.0.1:8848/nacos/v1/ns/operator/switches?entry=pushEnabled&value=false&debug=true'

示例返回

  1. ok

查看系统当前数据指标

描述

查看系统当前数据指标

请求类型

GET

请求路径

  1. /nacos/v1/ns/operator/metrics

请求参数

示例请求

  1. curl -X GET '127.0.0.1:8848/nacos/v1/ns/operator/metrics'

示例返回

  1. {
  2.     serviceCount: 336,
  3.     load: 0.09,
  4.     mem: 0.46210432,
  5.     responsibleServiceCount: 98,
  6.     instanceCount: 4,
  7.     cpu: 0.010242796,
  8.     status: "UP",
  9.     responsibleInstanceCount: 0
  10. }

查看当前集群Server列表

描述

查看当前集群Server列表

请求类型

GET

请求路径

  1. /nacos/v1/ns/operator/servers

请求参数

名称类型是否必选描述
healthyboolean否是否只返回健康Server节点

示例请求

  1. curl -X GET '127.0.0.1:8848/nacos/v1/ns/operator/servers'

示例返回

  1. {
  2.     servers: [
  3.         {
  4.             ip: "1.1.1.1",
  5.             servePort: 8848,
  6.             site: "unknown",
  7.             weight: 1,
  8.             adWeight: 0,
  9.             alive: false,
  10.             lastRefTime: 0,
  11.             lastRefTimeStr: null,
  12.             key: "1.1.1.1:8848"
  13.         },
  14.         {
  15.             ip: "1.1.1.2",
  16.             servePort: 8848,
  17.             site: "unknown",
  18.             weight: 1,
  19.             adWeight: 0,
  20.             alive: false,
  21.             lastRefTime: 0,
  22.             lastRefTimeStr: null,
  23.             key: "1.1.1.2:8848"
  24.         },
  25.         {
  26.             ip: "1.1.1.3",
  27.             servePort: 8848,
  28.             site: "unknown",
  29.             weight: 1,
  30.             adWeight: 0,
  31.             alive: false,
  32.             lastRefTime: 0,
  33.             lastRefTimeStr: null,
  34.             key: "1.1.1.3:8848"
  35.         }
  36.     ]
  37. }

查看当前集群leader

描述

查看当前集群leader

请求类型

GET

请求路径

  1. /nacos/v1/ns/raft/leader

请求参数

示例请求

  1. curl -X GET '127.0.0.1:8848/nacos/v1/ns/raft/leader'

示例返回

  1. {
  2.     leader: "{"heartbeatDueMs":2500,"ip":"1.1.1.1:8848","leaderDueMs":12853,"state":"LEADER","term":54202,"voteFor":"1.1.1.1:8848"}"
  3. }

更新实例的健康状态

描述

更新实例的健康状态,仅在集群的健康检查关闭时才生效,当集群配置了健康检查时,该接口会返回错误

请求类型

PUT

请求路径

  1. /nacos/v1/ns/health/instance

请求参数

名称类型是否必选描述
namespaceId字符串否命名空间ID
serviceName字符串是服务名
groupName字符串否分组名
clusterName字符串否集群名
ip字符串是服务实例IP
portint是服务实例port
healthyboolean是是否健康

示例请求

  1. 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