跳转到内容
开源沙龙,云原生安全零信任专场,4月13日_北京 点此了解

Open API 指南

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

1. 文档规定

1.1. API 统一返回体格式

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

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

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

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

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

1.2. 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其他内部错误

2. 配置管理

2.1. 获取配置

接口描述

获取指定配置

请求方式

GET

请求URL

/nacos/v2/cs/config

请求参数

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

返回数据

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

示例

  • 请求示例

    Terminal window
    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"
    }

2.2. 发布配置

接口描述

发布指定配置

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

请求方式

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是否执行成功

示例

  • 请求示例

    Terminal window
    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
    }

2.3. 删除配置

接口描述

删除指定配置

请求方式

DELETE

请求URL

/nacos/v2/cs/config

请求参数

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

返回数据

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

示例

  • 请求示例

    Terminal window
    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
    }

2.3. 查询配置历史列表

接口描述

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

请求方式

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[]历史配置项列表,参见历史配置项信息

示例

  • 请求示例

    Terminal window
    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"
    }
    ]
    }
    }

2.3. 查询具体版本的历史配置

接口描述

获取指定版本的历史配置

请求方式

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

示例

  • 请求示例

    Terminal window
    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"
    }
    }

2.6. 查询配置上一版本信息

接口描述

获取指定配置的上一版本

请求方式

GET

请求URL

/nacos/v2/cs/history/previous

请求参数

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

返回数据

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

示例

  • 请求示例

    Terminal window
    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"
    }
    }

3. 服务发现

3.1. 注册实例

接口描述

注册一个实例

请求方式

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是否执行成功

示例

  • 请求示例

    Terminal window
    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
    }

3.2. 注销实例

接口描述

注销指定实例

请求方式

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是否执行成功

示例

  • 请求示例

    Terminal window
    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
    }

3.3. 更新实例

接口描述

修改实例信息

通过该接口更新的元数据拥有更高的优先级,且具有记忆能力;会在对应实例删除后,依旧存在一段时间,如果在此期间实例重新注册,该元数据依旧生效;您可以通过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是否执行成功

示例

  • 请求示例

    Terminal window
    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
    }

3.4. 查询实例详情

接口描述

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

请求方式

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实例元数据

示例

  • 请求示例

    Terminal window
    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"
    }
    }
    }

3.5. 查询指定服务的实例列表

接口描述

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

请求方式

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是否有效

示例

  • 请求示例

    Terminal window
    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
    }
    }

3.6. 批量更新实例元数据

接口描述

批量更新实例的元数据,

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

请求方式

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是否执行成功

示例

  • 请求示例

    Terminal window
    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
    }

3.7. 批量删除实例元数据

接口描述

批量删除实例的元数据,

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

请求方式

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是否执行成功

示例

  • 请求示例

    Terminal window
    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
    }

3.8. 创建服务

接口描述

创建一个服务

服务已存在时会创建失败

请求方式

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是否执行成功

示例

  • 请求示例

    Terminal window
    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
    }

3.9. 删除服务

接口描述

删除指定服务

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

请求方式

DELETE

请求URL

/nacos/v2/ns/service

请求参数

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

返回数据

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

示例

  • 请求示例

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

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

3.10. 修改服务

接口描述

更新指定服务

服务不存在时会报错

请求方式

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是否执行成功

示例

  • 请求示例

    Terminal window
    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
    }

3.11. 查询服务详情

接口描述

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

服务不存在时会报错

请求方式

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是否为临时实例

示例

  • 请求示例

    Terminal window
    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
    }
    }

3.12. 查询服务列表

接口描述

查询符合条件的服务列表

请求方式

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[]分页后的服务列表

示例

  • 请求示例

    Terminal window
    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"
    ]
    }
    }

3.13. 更新实例健康状态

接口描述

更新实例的健康状态

请求方式

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”表示执行成功

示例

  • 请求示例

    Terminal window
    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"
    }

3.14. 查询客户端列表(新)

接口描述

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

请求方式

GET

请求URL

/nacos/v2/ns/client/list

返回数据

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

示例

  • 请求示例

    Terminal window
    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

3.15. 查询客户端信息(新)

接口描述

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

客户端不存在时会报错

请求方式

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字段

示例

  • 请求示例

    Terminal window
    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"
    }
    }

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

接口描述

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

客户端不存在时会报错

请求方式

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集群名

示例

  • 请求示例

    Terminal window
    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"
    }
    }
    ]
    }

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

接口描述

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

客户端不存在时会报错

请求方式

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地址

示例

  • 请求示例

    Terminal window
    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"
    }
    }
    ]
    }

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

接口描述

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

请求方式

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客户端端口

示例

  • 请求示例

    Terminal window
    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
    }
    ]
    }

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

接口描述

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

请求方式

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客户端端口

示例

  • 请求示例

    Terminal window
    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
    }
    ]
    }

4. 命名空间

4.1. 查询命名空间列表

接口描述

查询当前所有的命名空间

请求方式

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 - 自定义命名空间

示例

  • 请求示例

    Terminal window
    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
    }
    ]
    }

4.2. 查询具体命名空间

接口描述

查询具体命名空间的信息

命名空间不存在时会报错

请求方式

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 - 自定义命名空间

示例

  • 请求示例

    Terminal window
    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
    }
    }

4.3. 创建命名空间

接口描述

创建一个命名空间

命名空间已存在时会报错

请求方式

POST

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

请求URL

/nacos/v2/console/namespace

请求Body

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

返回数据

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

示例

  • 请求示例

    Terminal window
    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
    }

4.4. 编辑命名空间

接口描述

编辑命名空间信息

请求方式

PUT

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

请求URL

/nacos/v2/console/namespace

请求Body

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

返回数据

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

示例

  • 请求示例

    Terminal window
    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
    }

4.5. 删除命名空间

接口描述

删除指定命名空间

请求方式

DELETE

请求URL

/nacos/v2/console/namespace

请求参数

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

返回数据

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

示例

  • 请求示例

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

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