【Nacos】 API 指南

Metadata

title: 【Nacos】 API 指南
date: 2023-01-03 22:14
tags:
  - 行动阶段/完成
  - 主题场景/组件
  - 笔记空间/KnowladgeSpace/ProgramSpace/ModuleSpace
  - 细化主题/Module/Nacos/用户指南
categories:
  - Nacos
keywords:
  - Nacos
description: 【Nacos】 API 指南

文档规定

API 统一返回体格式

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

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

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

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

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

API 错误码汇总

API 接口返回

错误码 提示信息 含义
0 success 成功执行
10000 parameter missing 参数缺失
10001 access denied 访问拒绝
10002 data access error 数据访问错误
20001 ‘tenant’ parameter error tenant参数错误
20002 parameter validate error 参数验证错误
20003 MediaType Error 请求的MediaType错误
20004 resource not found 资源未找到
20005 resource conflict 资源访问冲突
20006 config listener is null 监听配置为空
20007 config listener error 监听配置错误
20008 invalid dataId 无效的dataId（鉴权失败）
20009 parameter mismatch 请求参数不匹配
21000 service name error serviceName服务名错误
21001 weight error weight权重参数错误
21002 instance metadata error 实例metadata元数据错误
21003 instance not found instance实例不存在
21004 instance error instance实例信息错误
21005 service metadata error 服务metadata元数据错误
21006 selector error 访问策略selector错误
21007 service already exist 服务已存在
21008 service not exist 服务不存在
21009 service delete failure 存在服务实例，服务删除失败
21010 healthy param miss healthy参数缺失
21011 health check still running 健康检查仍在运行
22000 illegal namespace 命名空间namespace不合法
22001 namespace not exist 命名空间不存在
22002 namespace already exist 命名空间已存在
23000 illegal state 状态state不合法
23001 node info error 节点信息错误
23002 node down failure 节点离线操作出错
… … …
30000 server 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是服务名
ipString是IP地址
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是服务名
ipString是IP地址
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-time及nacos.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是服务名
ipString是IP地址
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
ipString是IP地址
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
ipString否IP地址，默认为空，表示不限制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表示集群生效

返回数据

参数名参数类型描述
dataString“ok” 表示执行成功

示例

  • 请求示例

    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
ipString是IP地址
portint是端口号
healthyboolean是是否健康

返回数据

参数名参数类型描述
dataString“ok” 表示执行成功

示例

  • 请求示例

    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客户端版本

只有当clientType为connection时，会显示connectType，appName和appName字段

示例

  • 请求示例

    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否是否为临时实例
ipString否IP地址，默认为空，不限制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否是否为临时实例
ipString否IP地址，默认为空，不限制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当前节点健康状态

节点共有 STARTING， UP，SUSPICIOUS，DOWN，ISOLATION五种状态

示例

  • 请求示例

    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
}