Skip to main content
Version: 2.X

Open API 指南

Nacos 2.X 版本兼容 Nacos1.X 版本的OpenAPI, 请参考文档Nacos1.X OpenAPI使用。

注意:未特殊注明支持版本的OpenAPI均从2.2.0版本开始支持。

文档规定

API 统一返回体格式

2.0版本Open API,所有接口请求的响应均为json类型的返回体,返回体具有相同的格式

{
"code": 0,
"message": "success",
"data": {}
}

返回体中各字段的含义如下表所示

名称类型描述
code int错误码,0代表执行成功,非0代表执行失败的某一种情况
messageString错误码提示信息,执行成功为"success"
data任意类型返回数据,执行失败时为详细出错信息

由于执行成功的情况下code字段与message字段相同,后续在介绍接口的返回结果时,只介绍返回数据的data字段

API 错误码汇总

API接口返回体中的错误码及对应提示信息汇总见下表

错误码提示信息含义
0success成功执行
10000parameter missing参数缺失
10001access denied访问拒绝
10002data access error数据访问错误
20001'tenant' parameter errortenant参数错误
20002parameter validate error参数验证错误
20003MediaType Error请求的MediaType错误
20004resource not found资源未找到
20005resource conflict资源访问冲突
20006config listener is null监听配置为空
20007config listener error监听配置错误
20008invalid dataId无效的dataId(鉴权失败)
20009parameter mismatch请求参数不匹配
21000service name errorserviceName服务名错误
21001weight errorweight权重参数错误
21002instance metadata error实例metadata元数据错误
21003instance not foundinstance实例不存在
21004instance errorinstance实例信息错误
21005service metadata error服务metadata元数据错误
21006selector error访问策略selector错误
21007service already exist服务已存在
21008service not exist服务不存在
21009service delete failure存在服务实例,服务删除失败
21010healthy param misshealthy参数缺失
21011health check still running健康检查仍在运行
22000illegal namespace命名空间namespace不合法
22001namespace not exist命名空间不存在
22002namespace already exist命名空间已存在
23000illegal state状态state不合法
23001node info error节点信息错误
23002node down failure节点离线操作出错
.........
30000server error其他内部错误

配置管理

获取配置

接口描述

获取指定配置

请求方式

GET

请求URL

/nacos/v2/cs/config

请求参数

参数名类型必填参数描述
namespaceIdString命名空间,默认为public''相同
groupString配置分组名
dataIdString配置名
tagString标签

返回数据

参数名参数类型描述
dataString配置内容

示例

  • 请求示例

    curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/config?dataId=nacos.example&group=DEFAULT_GROUP&namespaceId=public'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": "contentTest"
    }

发布配置

接口描述

发布指定配置

当配置已存在时,则对配置进行更新

请求方式

POST

Content-Type:application/x-www-form-urlencoded

请求URL

/nacos/v2/cs/config

请求Body

参数名类型必填参数描述
namespaceIdString命名空间,默认为public''相同
groupString配置组名
dataIdString配置名
contentString配置内容
tagString标签
appNameString应用名
srcUserString源用户
configTagsString配置标签列表,可多个,逗号分隔
descString配置描述
useString-
effectString-
typeString配置类型
schemaString-

返回数据

参数名参数类型描述
databoolean是否执行成功

示例

  • 请求示例

    curl -d 'dataId=nacos.example' \
    -d 'group=DEFAULT_GROUP' \
    -d 'namespaceId=public' \
    -d 'content=contentTest' \
    -X POST 'http://127.0.0.1:8848/nacos/v2/cs/config'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": true
    }

删除配置

接口描述

删除指定配置

请求方式

DELETE

请求URL

/nacos/v2/cs/config

请求参数

参数名类型必填参数描述
namespaceIdString命名空间,默认为public''相同
groupString配置分组名
dataIdString配置名
tagString标签

返回数据

参数名参数类型描述
databoolean是否执行成功

示例

  • 请求示例

    curl -X DELETE 'http://127.0.0.1:8848/nacos/v2/cs/config?dataId=nacos.example&group=DEFAULT_GROUP&namespaceId=public'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": true
    }

查询配置历史列表

接口描述

获取指定配置的历史版本列表

请求方式

GET

请求URL

/nacos/v2/cs/history/list

请求参数

参数名类型必填参数描述
namespaceIdString命名空间,默认为public''相同
groupString配置分组名
dataIdString配置名
pageNoint当前页,默认为1
pageSizeint页条目数,默认为100,最大为500

返回数据

参数名参数类型描述说明
dataObject分页查询结果
data.totalCountint总数
data.pageNumberint当前页
data.pagesAvailableint总页数
data.pageItemsObject[]历史配置项列表,参见历史配置项信息

示例

  • 请求示例

    curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history/list?dataId=nacos.example&group=com.alibaba.nacos&namespaceId='
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": {
    "totalCount": 1,
    "pageNumber": 1,
    "pagesAvailable": 1,
    "pageItems": [
    {
    "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"
    }
    ]
    }
    }

查询具体版本的历史配置

接口描述

获取指定版本的历史配置

请求方式

GET

请求URL

/nacos/v2/cs/history

请求参数

参数名类型必填参数描述
namespaceIdString命名空间,默认为public''相同
groupString配置分组名
dataIdString配置名
nidlong历史配置id

返回数据

参数名参数类型描述说明
dataObject历史配置项
data.idString配置id
data.lastIdint
data.dataIdString配置名
data.groupString配置分组
data.tenantString租户信息(命名空间)
data.appNameString应用名
data.md5String配置内容的md5值
data.contentString配置内容
data.srcIpString源ip
data.srcUserString源用户
data.opTypeString操作类型
data.createdTimeString创建时间
data.lastModifiedTimeString上次修改时间
data.encryptedDataKeyString

示例

  • 请求示例

    curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history?dataId=nacos.example&group=com.alibaba.nacos&namespaceId=&nid=203'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": {
    "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"
    }
    }

查询配置上一版本信息

接口描述

获取指定配置的上一版本

请求方式

GET

请求URL

/nacos/v2/cs/history/previous

请求参数

参数名类型必填参数描述
namespaceIdString命名空间,默认为public''相同
groupString配置分组名
dataIdString配置名
idlong配置id

返回数据

参数名参数类型描述说明
dataObject历史配置项,参见历史配置项信息

示例

  • 请求示例

    curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history/previous?id=309135486247505920&dataId=nacos.example&group=com.alibaba.nacos&namespaceId='
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": {
    "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"
    }
    }

查询指定命名空间下的配置列表

接口描述

获取指定命名空间下的配置信息列表

请求方式

GET

请求URL

/nacos/v2/cs/history/configs

请求参数

参数名类型必填参数描述
namespaceIdString命名空间

返回数据

参数名参数类型描述说明
dataObject[]配置信息列表
data.idString配置id
data.dataIdString配置名
data.groupString配置分组
data.contentString配置内容
data.md5String配置内容的md5值
data.encryptedDataKeyString
data.tenantString租户信息(命名空间)
data.appNameString应用名
data.typeString配置文件类型
data.lastModifiedlong上次修改时间

返回数据中的配置信息只有dataId, group, tenant, appName, type字段有效,其他字段为默认值

示例

  • 请求示例

    curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history/configs?namespaceId='
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": [
    {
    "id": "0",
    "dataId": "nacos.example",
    "group": "com.alibaba.nacos",
    "content": null,
    "md5": null,
    "encryptedDataKey": null,
    "tenant": "",
    "appName": "",
    "type": "yaml",
    "lastModified": 0
    }
    ]
    }

服务发现

注册实例

接口描述

注册一个实例

请求方式

POST

Content-Type:application/x-www-form-urlencoded

请求URL

/nacos/v2/ns/instance

请求Body

参数名参数类型是否必填描述说明
namespaceIdString命名空间Id,默认为public
groupNameString分组名,默认为DEFAULT_GROUP
serviceNameString服务名
ipStringIP地址
portint端口号
clusterNameString集群名称,默认为DEFAULT
healthyboolean是否只查找健康实例,默认为true
weightdouble实例权重,默认为1.0
enabledboolean是否可用,默认为true
metadataJSON格式String实例元数据
ephemeralboolean是否为临时实例

返回数据

参数名参数类型描述
databoolean是否执行成功

示例

  • 请求示例

    curl -d 'serviceName=test_service' \
    -d 'ip=127.0.0.1' \
    -d 'port=8090' \
    -d 'weight=0.9' \
    -d 'ephemeral=true' \
    -X POST 'http://127.0.0.1:8848/nacos/v2/ns/instance'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": true
    }

注销实例

接口描述

注销指定实例

请求方式

DELETE

Content-Type:application/x-www-form-urlencoded

请求URL

/nacos/v2/ns/instance

请求Body

参数名参数类型是否必填描述说明
namespaceIdString命名空间Id,默认为public
groupNameString分组名,默认为DEFAULT_GROUP
serviceNameString服务名
ipStringIP地址
portint端口号
clusterNameString集群名称,默认为DEFAULT
healthyboolean是否只查找健康实例,默认为true
weightdouble实例权重,默认为1.0
enabledboolean是否可用,默认为true
metadataJSON格式String实例元数据
ephemeralboolean是否为临时实例

返回数据

参数名参数类型描述
databoolean是否执行成功

示例

  • 请求示例

    curl -d 'serviceName=test_service' \
    -d 'ip=127.0.0.1' \
    -d 'port=8090' \
    -d 'weight=0.9' \
    -d 'ephemeral=true' \
    -X DELETE 'http://127.0.0.1:8848/nacos/v2/ns/instance'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": true
    }

更新实例

接口描述

修改实例信息

通过该接口更新的元数据拥有更高的优先级,且具有记忆能力;会在对应实例删除后,依旧存在一段时间,如果在此期间实例重新注册,该元数据依旧生效;您可以通过nacos.naming.clean.expired-metadata.expired-timenacos.naming.clean.expired-metadata.interval对记忆时间进行修改

请求方式

PUT

Content-Type:application/x-www-form-urlencoded

请求URL

/nacos/v2/ns/instance

请求Body

参数名参数类型是否必填描述说明
namespaceIdString命名空间Id,默认为public
groupNameString分组名,默认为DEFAULT_GROUP
serviceNameString服务名
ipStringIP地址
portint端口号
clusterNameString集群名称,默认为DEFAULT
healthyboolean是否只查找健康实例,默认为true
weightdouble实例权重,默认为1.0
enabledboolean是否可用,默认为true
metadataJSON格式String实例元数据
ephemeralboolean是否为临时实例

返回数据

参数名参数类型描述
databoolean是否执行成功

示例

  • 请求示例

    curl -d 'serviceName=test_service' \
    -d 'ip=127.0.0.1' \
    -d 'port=8090' \
    -d 'weight=0.9' \
    -d 'ephemeral=true' \
    -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/instance'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": true
    }

查询实例详情

接口描述

查询某个具体实例的详情信息

请求方式

GET

请求URL

/nacos/v2/ns/instance

请求参数

参数名参数类型是否必填描述说明
namespaceIdString命名空间Id,默认为public
groupNameString分组名,默认为DEFAULT_GROUP
serviceNameString服务名
clusterNameString集群名称,默认为DEFAULT
ipStringIP地址
portint端口号

返回数据

参数名参数类型描述说明
dataObject实例详情信息
data.serviceNameString服务名
data.ipStringIP地址
data.portint端口号
data.clusterNameString集群名称
data.weightdouble实例权重
data.healthyboolean是否健康
data.instanceIdString实例id
data.metadatamap实例元数据

示例

  • 请求示例

    curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/instance?namespaceId=public&groupName=&serviceName=test_service&ip=127.0.0.1&port=8080'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": {
    "serviceName": "DEFAULT_GROUP@@test_service",
    "ip": "127.0.0.1",
    "port": 8080,
    "clusterName": "DEFAULT",
    "weight": 1.0,
    "healthy": true,
    "instanceId": null,
    "metadata": {
    "value": "1"
    }
    }
    }

查询指定服务的实例列表

接口描述

查询指定服务下的实例详情信息列表

请求方式

GET

请求URL

/nacos/v2/ns/instance/list

请求头

参数名参数类型是否必填描述说明
User-AgentString用户代理,默认为空
Client-VersionString客户端版本,默认为空

请求参数

参数名参数类型是否必填描述说明
namespaceIdString命名空间Id,默认为public
groupNameString分组名,默认为DEFAULT_GROUP
serviceNameString服务名
clusterNameString集群名称,默认为DEFAULT
ipStringIP地址,默认为空,表示不限制IP地址
portint端口号,默认为0,表示不限制端口号
healthyOnlyboolean是否只获取健康实例,默认为false
appString应用名,默认为空

返回数据

参数名参数类型描述说明
data指定服务的实例列表
data.nameString分组名@@服务名
data.groupNameString分组名
data.clustersString集群名
data.cacheMillisint缓存时间
data.hostsObject[]实例列表
data.hosts.ipString实例IP
data.hosts.portint实例端口号
data.hosts.weightdouble实例权重
data.hosts.healthyboolean实例是否健康
data.hosts.enabledboolean实例是否可用
data.hosts.ephemeralboolean是否为临时实例
data.hosts.clusterNameString实例所在的集群名称
data.hosts.serviceNameString服务名
data.hosts.metadatamap实例元数据
data.hosts.instanceHeartBeatTimeOutint实例心跳超时时间
data.hosts.ipDeleteTimeoutint实例删除超时时间
data.hosts.instanceHeartBeatIntervalint实例心跳间隔
data.lastRefTimeint上次刷新时间
data.checksumint校验码
data.allIPsboolean
data.reachProtectionThresholdboolean是否到达保护阈值
data.validboolean是否有效

示例

  • 请求示例

    curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/instance/list?serviceName=test_service&ip=127.0.0.1'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": {
    "name": "DEFAULT_GROUP@@test_service",
    "groupName": "DEFAULT_GROUP",
    "clusters": "",
    "cacheMillis": 10000,
    "hosts": [
    {
    "ip": "127.0.0.1",
    "port": 8080,
    "weight": 1.0,
    "healthy": true,
    "enabled": true,
    "ephemeral": true,
    "clusterName": "DEFAULT",
    "serviceName": "DEFAULT_GROUP@@test_service",
    "metadata": {
    "value": "1"
    },
    "instanceHeartBeatTimeOut": 15000,
    "ipDeleteTimeout": 30000,
    "instanceHeartBeatInterval": 5000
    }
    ],
    "lastRefTime": 1662554390814,
    "checksum": "",
    "allIPs": false,
    "reachProtectionThreshold": false,
    "valid": true
    }
    }

批量更新实例元数据

接口描述

批量更新实例的元数据,

对应元数据的键不存在时,则添加对应元数据

请求方式

PUT

Content-Type:application/x-www-form-urlencoded

请求URL

/nacos/v2/ns/instance/metadata/batch

请求Body

参数名参数类型是否必填描述说明
namespaceIdString命名空间Id,默认为public
groupNameString分组名,默认为DEFAULT_GROUP
serviceNameString服务名
consistencyTypeString持久化类型,默认为空
instancesJSON格式String需要更新的实例列表,默认为空
metadataJSON格式String实例元数据

参数说明

  • consistencyType: 实例的持久化类型,当为‘persist’,表示对持久化实例的元数据进行更新;否则表示对临时实例的元数据进行更新
  • instances: 待更新的实例列表,json数组,通过ip+port+ephemeral+cluster定位到某一实例,为空则表示更新指定服务下所有实例的元数据

返回数据

参数名参数类型描述
databoolean是否执行成功

示例

  • 请求示例

    curl -d 'serviceName=test_service' \
    -d 'consistencyType=ephemeral' \
    -d '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"}]' \
    -d 'metadata={"age":"20","name":"cocolan"}' \
    -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/instance/metadata/batch'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": true
    }

批量删除实例元数据

接口描述

批量删除实例的元数据,

对应元数据的键不存在时,则不做操作

请求方式

DELETE

Content-Type:application/x-www-form-urlencoded

请求URL

/nacos/v2/ns/instance/metadata/batch

请求Body

参数名参数类型是否必填描述说明
namespaceIdString命名空间Id,默认为public
groupNameString分组名,默认为DEFAULT_GROUP
serviceNameString服务名
consistencyTypeString持久化类型,默认为空
instancesJSON格式String需要更新的实例列表,默认为空
metadataJSON格式String实例元数据

参数说明

  • consistencyType: 实例的持久化类型,当为‘persist’,表示对持久化实例的元数据进行删除;否则表示对临时实例的元数据进行
  • instances: 待更新的实例列表,json数组,通过ip+port+ephemeral+cluster定位到某一实例,为空则表示更新指定服务下所有实例的元数据

返回数据

参数名参数类型描述
databoolean是否执行成功

示例

  • 请求示例

    curl -d 'serviceName=test_service' \
    -d 'consistencyType=ephemeral' \
    -d '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"}]' \
    -d 'metadata={"age":"20","name":"cocolan"}' \
    -X DELETE 'http://127.0.0.1:8848/nacos/v2/ns/instance/metadata/batch'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": true
    }

创建服务

接口描述

创建一个服务

服务已存在时会创建失败

请求方式

POST

Content-Type:application/x-www-form-urlencoded

请求URL

/nacos/v2/ns/service

请求Body

参数名参数类型是否必填描述说明
namespaceIdString命名空间Id,默认为public
groupNameString分组名,默认为DEFAULT_GROUP
serviceNameString服务名
metadataJSON格式String服务元数据,默认为空
ephemeralboolean是否为临时实例,默认为false
protectThresholdfloat保护阈值,默认为0
selectorJSON格式String访问策略,默认为空

返回数据

参数名参数类型描述
databoolean是否执行成功

示例

  • 请求示例

    curl -d 'serviceName=nacos.test.1' \
    -d 'ephemeral=true' \
    -d 'metadata={"k1":"v1"}' \
    -X POST 'http://127.0.0.1:8848/nacos/v2/ns/service'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": true
    }

删除服务

接口描述

删除指定服务

服务不存在时会报错,且服务还存在实例时会删除失败

请求方式

DELETE

请求URL

/nacos/v2/ns/service

请求参数

参数名参数类型是否必填描述说明
namespaceIdString命名空间Id,默认为public
groupNameString分组名,默认为DEFAULT_GROUP
serviceNameString服务名

返回数据

参数名参数类型描述
databoolean是否执行成功

示例

  • 请求示例

    curl -X DELETE 'http://127.0.0.1:8848/nacos/v2/ns/service?serviceName=nacos.test.1'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": true
    }

修改服务

接口描述

更新指定服务

服务不存在时会报错

请求方式

POST

Content-Type:application/x-www-form-urlencoded

请求URL

/nacos/v2/ns/service

请求参数

参数名参数类型是否必填描述说明
namespaceIdString命名空间Id,默认为public
groupNameString分组名,默认为DEFAULT_GROUP
serviceNameString服务名
metadataJSON格式String服务元数据,默认为空
protectThresholdfloat保护阈值,默认为0
selectorJSON格式String访问策略,默认为空

返回数据

参数名参数类型描述
databoolean是否执行成功

示例

  • 请求示例

    curl -d 'serviceName=nacos.test.1' \
    -d 'metadata={"k1":"v2"}' \
    -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/service'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": true
    }

查询服务详情

接口描述

查询某个具体服务的详情信息

服务不存在时会报错

请求方式

GET

请求URL

/nacos/v2/ns/service

请求参数

参数名参数类型是否必填描述说明
namespaceIdString命名空间Id,默认为public
groupNameString分组名,默认为DEFAULT_GROUP
serviceNameString服务名

返回数据

参数名参数类型描述说明
data服务信息
data.namespaceString命名空间
data.groupNameString分组名
data.serviceNameString服务名
data.clusterMapmap集群信息
data.metadatamap服务元数据
data.protectThresholdfloat保护阈值
data.selectorObject访问策略
data.ephemeralBoolean是否为临时实例

示例

  • 请求示例

    curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/service?serviceName=nacos.test.1'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": {
    "namespace": "public",
    "serviceName": "nacos.test.1",
    "groupName": "DEFAULT_GROUP",
    "clusterMap": {},
    "metadata": {},
    "protectThreshold": 0,
    "selector": {
    "type": "none",
    "contextType": "NONE"
    },
    "ephemeral": false
    }
    }

查询服务列表

接口描述

查询符合条件的服务列表

请求方式

GET

请求URL

/nacos/v2/ns/service/list

请求参数

参数名参数类型是否必填描述说明
namespaceIdString命名空间Id,默认为public
groupNameString分组名,默认为DEFAULT_GROUP
selectorJSON格式String访问策略
pageNoint当前页,默认为1
pageSizeint页条目数,默认为20,最大为500

返回数据

参数名参数类型描述说明
data服务列表信息
data.countString服务数目
data.servicesString[]分页后的服务列表

示例

  • 请求示例

    curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/service/list'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": {
    "count": 2,
    "services": [
    "nacos.test.1",
    "nacos.test.2"
    ]
    }
    }

查询系统开关

接口描述

查询系统开关

请求方式

GET

请求URL

/nacos/v2/ns/operator/switches

返回数据

参数名参数类型描述说明
dataObject系统开关信息

示例

  • 请求示例

    curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/operator/switches'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": {
    "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": false,
    "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": [],
    "name": "00-00---000-NACOS_SWITCH_DOMAIN-000---00-00",
    "checksum": null
    }
    }

修改系统开关

接口描述

修改系统开关

请求方式

PUT

Content-Type:application/x-www-form-urlencoded

请求URL

/nacos/v2/ns/operator/switches

请求Body

参数名参数类型是否必填描述说明
entryString开关名
valueString开关值
debugboolean是否只在本机生效,true表示本机生效,false表示集群生效

返回数据

参数名参数类型描述
dataStringok”表示执行成功

示例

  • 请求示例

    curl -d 'entry=pushEnabled' \
    -d 'value=false' \
    -d 'debug=true' \
    -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/operator/switches'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": "ok"
    }

查询系统当前数据指标

接口描述

查询系统当前数据指标

请求方式

GET

请求URL

/nacos/v2/ns/operator/metrics

请求参数

参数名参数类型是否必填描述说明
onlyStatusboolean只显示状态,默认为true

onlyStatus设置为true时,只返回表示系统状态的字符串

返回数据

参数名参数类型描述说明
dataObject系统当前数据指标
data.statusString系统状态
data.serviceCountint服务数量
data.instanceCountint实例数量
data.subscribeCountint订阅数量
data.raftNotifyTaskCountintRaft通知任务数量
data.responsibleServiceCountint
data.responsibleInstanceCountint
data.clientCountint客户端数量
data.connectionBasedClientCountint连接数量
data.ephemeralIpPortClientCountint临时客户端数量
data.persistentIpPortClientCountint持久客户端数量
data.responsibleClientCountint
data.cpufloatcpu使用率
data.loadfloat负载
data.memfloat内存使用率

示例

  • 请求示例

    curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/operator/metrics'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": {
    "status": "UP",
    "serviceCount": 2,
    "instanceCount": 2,
    "subscribeCount": 2,
    "raftNotifyTaskCount": 0,
    "responsibleServiceCount": 0,
    "responsibleInstanceCount": 0,
    "clientCount": 2,
    "connectionBasedClientCount": 2,
    "ephemeralIpPortClientCount": 0,
    "persistentIpPortClientCount": 0,
    "responsibleClientCount": 2,
    "cpu": 0,
    "load": -1,
    "mem": 1
    }
    }

更新实例健康状态

接口描述

更新实例的健康状态

请求方式

PUT

Content-Type:application/x-www-form-urlencoded

请求URL

/nacos/v2/ns/health/instance

请求Body

参数名参数类型是否必填描述说明
namespaceIdString命名空间Id,默认为public
groupNameString分组名,默认为DEFAULT_GROUP
serviceNameString服务名
clusterNameString集群名,默认为DEFAULT
ipStringIP地址
portint端口号
healthyboolean是否健康

返回数据

参数名参数类型描述
dataStringok”表示执行成功

示例

  • 请求示例

    curl -d 'serviceName=nacos.test.1' \
    -d 'ip=127.0.0.1' \
    -d 'port=8080' \
    -d 'healthy=false' \
    -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/health/instance'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": "ok"
    }

查询客户端列表(新)

接口描述

查询当前所有的客户端列表

请求方式

GET

请求URL

/nacos/v2/ns/client/list

返回数据

参数名参数类型描述说明
dataString[]客户端id列表

示例

  • 请求示例

    curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/list'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": [
    "10.128.164.35:9956#true",
    "1664358687402_127.0.0.1_2300",
    "1664358642902_127.0.0.1_2229",
    "192.168.139.1:49825#true",
    "10.128.164.35:9954#true",
    "192.168.139.1:53556#true"
    ]
    }

对于不同版本的nacos client,建立客户端的方式不同。

对于1.x版本,每个实例会建立两个基于ip+port的客户端,分别对应实例注册与服务订阅,clientId格式为 ip:port#ephemeral

对于2.x版本的nacos client, 每个实例会建立一个RPC连接,对应一个基于RPC连接的客户端,兼具注册与订阅功能,clientId 格式为time_ip_port

查询客户端信息(新)

接口描述

查询指定客户端的详细信息

客户端不存在时会报错

请求方式

GET

请求URL

/nacos/v2/ns/client

请求参数

参数名参数类型是否必填描述说明
clientIdString客户端id

返回数据

参数名参数类型描述说明
dataObject客户端信息
data.clientIdString客户端id
data.ephemeralboolean是否为临时实例
data.lastUpdatedTimeint上次更新时间
data.clientTypeString客户端类型
data.clientIpString客户端IP
data.clientPortString客户端端口
data.connectTypeString连接类型
data.appNameString应用名
data.VersionString客户端版本

只有当clientTypeconnection时,会显示connectTypeappNameappName字段

示例

  • 请求示例

    curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client?clientId=1664527081276_127.0.0.1_4400'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": {
    "clientId": "1664527081276_127.0.0.1_4400",
    "ephemeral": true,
    "lastUpdatedTime": 1664527081642,
    "clientType": "connection",
    "connectType": "GRPC",
    "appName": "-",
    "version": "Nacos-Java-Client:v2.1.0",
    "clientIp": "10.128.164.35",
    "clientPort": "4400"
    }
    }

查询客户端的注册信息(新)

接口描述

查询指定客户端的注册信息

客户端不存在时会报错

请求方式

GET

请求URL

/nacos/v2/ns/client/publish/list

请求参数

参数名参数类型是否必填描述说明
clientIdString客户端id

返回数据

参数名参数类型描述说明
dataObject[]客户端注册的服务列表
data.namespaceString命名空间
data.groupString分组名
data.serviceNameString服务名
data.registeredInstanceObject该服务下注册的实例
data.registeredInstance.ipStringIP地址
data.registeredInstance.portint端口号
data.registeredInstance.clusterString集群名

示例

  • 请求示例

    curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/publish/list?clientId=1664527081276_127.0.0.1_4400'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": [
    {
    "namespace": "public",
    "group": "DEFAULT_GROUP",
    "serviceName": "nacos.test.1",
    "registeredInstance": {
    "ip": "10.128.164.35",
    "port": 9950,
    "cluster": "DEFAULT"
    }
    }
    ]
    }

查询客户端的订阅信息(新)

接口描述

查询指定客户端的订阅信息

客户端不存在时会报错

请求方式

GET

请求URL

/nacos/v2/ns/client/subscribe/list

请求参数

参数名参数类型是否必填描述说明
clientIdString客户端id

返回数据

参数名参数类型描述说明
dataObject[]客户端订阅的服务列表
data.namespaceString命名空间
data.groupString分组名
data.serviceNameString服务名
data.subscriberInfoObject订阅信息
data.subscriberInfo.appString应用
data.subscriberInfo.agentString客户端信息
data.subscriberInfo.addrString地址

示例

  • 请求示例

    curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/subscribe/list?clientId=1664527081276_127.0.0.1_4400'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": [
    {
    "namespace": "public",
    "group": "DEFAULT_GROUP",
    "serviceName": "nacos.test.1",
    "subscriberInfo": {
    "app": "unknown",
    "agent": "Nacos-Java-Client:v2.1.0",
    "addr": "10.128.164.35"
    }
    }
    ]
    }

查询注册指定服务的客户端信息(新)

接口描述

查询注册指定服务的客户端信息

请求方式

GET

请求URL

/nacos/v2/ns/client/service/publisher/list

请求参数

参数名参数类型是否必填描述说明
namespaceIdString命名空间Id,默认为public
groupNameString分组名,默认为DEFAULT_GROUP
serviceNameString服务名
ephemeralboolean是否为临时实例
ipStringIP地址,默认为空,不限制IP地址
portint端口号,默认为空,表示不限制端口号

返回数据

参数名参数类型描述说明
data客户端列表
data.clientIdString客户端id
data.ipString客户端IP
data.portint客户端端口

示例

  • 请求示例

    curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/service/publisher/list?serviceName=nacos.test.1&ip=&port='
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": [
    {
    "clientId": "1664527081276_127.0.0.1_4400",
    "ip": "10.128.164.35",
    "port": 9950
    },
    {
    "clientId": "10.128.164.35:9954#true",
    "ip": "10.128.164.35",
    "port": 9954
    }
    ]
    }

查询订阅指定服务的客户端信息(新)

接口描述

查询订阅指定服务的客户端信息

请求方式

GET

请求URL

/nacos/v2/ns/client/service/subscriber/list

请求参数

参数名参数类型是否必填描述说明
namespaceIdString命名空间Id,默认为public
groupNameString分组名,默认为DEFAULT_GROUP
serviceNameString服务名
ephemeralboolean是否为临时实例
ipStringIP地址,默认为空,不限制IP地址
portint端口号,默认为空,表示不限制端口号

返回数据

参数名参数类型描述说明
data客户端列表
data.clientIdString客户端id
data.ipString客户端IP
data.portint客户端端口

示例

  • 请求示例

    curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/service/subscriber/list?serviceName=nacos.test.1&ip=&port='
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": [
    {
    "clientId": "1664527125645_127.0.0.1_4443",
    "ip": "10.128.164.35",
    "port": 0
    },
    {
    "clientId": "172.24.144.1:54126#true",
    "ip": "172.24.144.1",
    "port": 54126
    }
    ]
    }

命名空间

查询命名空间列表

接口描述

查询当前所有的命名空间

请求方式

GET

请求URL

/nacos/v2/console/namespace/list

返回数据

参数名参数类型描述说明
dataObject[]命名空间列表
data.namespaceString命名空间ID
data.namespaceShowNameString命名空间名称
data.namespaceDescString命名空间描述
data.quotaint命名空间的容量
data.configCountint命名空间下的配置数量
data.typeint命名空间类型

命名空间分为3种类型,0 - 全局命名空间 1 - 默认私有命名空间 2 - 自定义命名空间

示例

  • 请求示例

    curl -X GET 'http://127.0.0.1:8848/nacos/v2/console/namespace/list'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": [
    {
    "namespace": "",
    "namespaceShowName": "public",
    "namespaceDesc": null,
    "quota": 200,
    "configCount": 1,
    "type": 0
    }
    ]
    }

查询具体命名空间

接口描述

查询具体命名空间的信息

命名空间不存在时会报错

请求方式

GET

请求URL

/nacos/v2/console/namespace

请求参数

参数名参数类型是否必填描述说明
namespaceIdString命名空间Id

返回数据

参数名参数类型描述说明
dataObject命名空间信息
data.namespaceString命名空间ID
data.namespaceShowNameString命名空间名称
data.namespaceDescString命名空间描述
data.quotaint命名空间的容量
data.configCountint命名空间下的配置数量
data.typeint命名空间类型

命名空间分为3种类型,0 - 全局命名空间 1 - 默认私有命名空间 2 - 自定义命名空间

示例

  • 请求示例

    curl -X GET 'http://127.0.0.1:8848/nacos/v2/console/namespace?namespaceId=test_namespace'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": {
    "namespace": "test_namespace",
    "namespaceShowName": "test",
    "namespaceDesc": null,
    "quota": 200,
    "configCount": 0,
    "type": 2
    }
    }

创建命名空间

接口描述

创建一个命名空间

命名空间已存在时会报错

请求方式

POST

Content-Type:application/x-www-form-urlencoded

请求URL

/nacos/v2/console/namespace

请求Body

参数名参数类型是否必填描述说明
namespaceIdString命名空间Id
namespaceNameString命名空间名称
namespaceDescString命名空间描述

返回数据

参数名参数类型描述
databoolean是否执行成功

示例

  • 请求示例

    curl -d 'namespaceId=test_namespace' \
    -d 'namespaceName=test' \
    -X POST 'http://127.0.0.1:8848/nacos/v2/console/namespace'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": true
    }

编辑命名空间

接口描述

编辑命名空间信息

请求方式

PUT

Content-Type:application/x-www-form-urlencoded

请求URL

/nacos/v2/console/namespace

请求Body

参数名参数类型是否必填描述说明
namespaceIdString命名空间Id
namespaceNameString命名空间名称
namespaceDescString命名空间描述

返回数据

参数名参数类型描述
databoolean是否执行成功

示例

  • 请求示例

    curl -d 'namespaceId=test_namespace' \
    -d 'namespaceName=test.nacos' \
    -X PUT 'http://127.0.0.1:8848/nacos/v2/console/namespace'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": true
    }

删除命名空间

接口描述

删除指定命名空间

请求方式

DELETE

请求URL

/nacos/v2/console/namespace

请求参数

参数名参数类型是否必填描述说明
namespaceIdString命名空间Id

返回数据

参数名参数类型描述
databoolean是否执行成功

示例

  • 请求示例

    curl -d 'namespaceId=test_namespace' \
    -X DELETE 'http://127.0.0.1:8848/nacos/v2/console/namespace'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": true
    }

集群管理

查询当前节点信息

接口描述

查询当前nacos节点信息

请求方式

GET

请求URL

/nacos/v2/core/cluster/node/self

返回数据

参数名参数类型描述说明
dataObject当前节点信息
data.ipString节点IP地址
data.portint节点端口
data.stateString节点状态
data.extendInfoObject节点扩展信息
data.addressString节点地址(IP:port
data.failAccessCntint失败访问次数
data.abilitiesObject

示例

  • 请求示例

    curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/cluster/node/self'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": {
    "ip": "10.128.164.35",
    "port": 8848,
    "state": "UP",
    "extendInfo": {
    "lastRefreshTime": 1664521263623,
    "raftMetaData": {
    "metaDataMap": {
    "naming_instance_metadata": {
    "leader": "10.128.164.35:7848",
    "raftGroupMember": [
    "10.128.164.35:7848"
    ],
    "term": 12
    },
    "naming_persistent_service_v2": {
    "leader": "10.128.164.35:7848",
    "raftGroupMember": [
    "10.128.164.35:7848"
    ],
    "term": 12
    },
    "naming_service_metadata": {
    "leader": "10.128.164.35:7848",
    "raftGroupMember": [
    "10.128.164.35:7848"
    ],
    "term": 12
    }
    }
    },
    "raftPort": "7848",
    "readyToUpgrade": true,
    "version": "2.1.0"
    },
    "address": "10.128.164.35:8848",
    "failAccessCnt": 0,
    "abilities": {
    "remoteAbility": {
    "supportRemoteConnection": true
    },
    "configAbility": {
    "supportRemoteMetrics": false
    },
    "namingAbility": {
    "supportJraft": true
    }
    }
    }
    }

查询集群节点列表

接口描述

查询集群节点列表

请求方式

GET

请求URL

/nacos/v2/core/cluster/node/list

请求参数

参数名参数类型是否必填描述说明
addressString节点地址,默认为空
stateString节点状态,默认为空

address 对应于需要查询的节点地址的前缀匹配条件,为空时不做限制

state对应节点状态的筛选条件,为空时不做限制

返回数据

参数名参数类型描述说明
dataObject[]节点列表,详情参见节点详情

示例

  • 请求示例

    curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/cluster/node/list'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": [
    {
    "ip": "10.128.164.35",
    "port": 8848,
    "state": "UP",
    "extendInfo": {
    "lastRefreshTime": 1664521263623,
    "raftMetaData": {
    "metaDataMap": {
    "naming_instance_metadata": {
    "leader": "10.128.164.35:7848",
    "raftGroupMember": [
    "10.128.164.35:7848"
    ],
    "term": 12
    },
    "naming_persistent_service_v2": {
    "leader": "10.128.164.35:7848",
    "raftGroupMember": [
    "10.128.164.35:7848"
    ],
    "term": 12
    },
    "naming_service_metadata": {
    "leader": "10.128.164.35:7848",
    "raftGroupMember": [
    "10.128.164.35:7848"
    ],
    "term": 12
    }
    }
    },
    "raftPort": "7848",
    "readyToUpgrade": true,
    "version": "2.1.0"
    },
    "address": "10.128.164.35:8848",
    "failAccessCnt": 0,
    "abilities": {
    "remoteAbility": {
    "supportRemoteConnection": true
    },
    "configAbility": {
    "supportRemoteMetrics": false
    },
    "namingAbility": {
    "supportJraft": true
    }
    }
    }
    ]
    }

查询当前节点健康状态

接口描述

查询当前nacos节点健康状态

请求方式

GET

请求URL

/nacos/v2/core/cluster/node/self/health

返回数据

参数名参数类型描述说明
dataString当前节点健康状态

节点共有 STARTINGUPSUSPICIOUSDOWNISOLATION五种状态

示例

  • 请求示例

    curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/cluster/node/self/health'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": "UP"
    }

切换集群寻址模式

接口描述

切换集群寻址模式

请求方式

PUT

Content-Type:application/x-www-form-urlencoded

请求URL

/nacos/v2/core/cluster/lookup

请求Body

参数名参数类型是否必填描述说明
typeString寻址模式

寻址模式有两种:file(文件配置)和 address-server(地址服务器)

返回数据

参数名参数类型描述
databoolean是否执行成功

示例

  • 请求示例

    curl -d 'type=file' \
    -X PUT 'http://127.0.0.1:8848/nacos/v2/core/cluster/lookup'
  • 返回示例

    {
    "code": 0,
    "message": "success",
    "data": true
    }