Open API 手册

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

For how to obtain and configure access credentials when using the default auth plugin, see How to configure auth for OpenAPI.

1. 文档规定

1.1. API 统一返回体格式

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

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

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

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

1.2. API 错误码汇总

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

2. 配置管理

2.1. 获取配置

接口描述

获取指定配置

请求方式

GET

请求URL

/nacos/v2/cs/config

请求参数

返回数据

示例

• 请求示例

  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

返回数据

示例

• 请求示例

  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

请求参数

返回数据

示例

• 请求示例

  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

请求参数

返回数据

示例

• 请求示例

  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

请求参数

返回数据

示例

• 请求示例

  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

请求参数

返回数据

示例

• 请求示例

  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

返回数据

示例

• 请求示例

  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

返回数据

示例

• 请求示例

  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-time及nacos.naming.clean.expired-metadata.interval对记忆时间进行修改

请求方式

PUT

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

请求URL

/nacos/v2/ns/instance

请求Body

返回数据

示例

• 请求示例

  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

请求参数

返回数据

示例

• 请求示例

  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

请求头

请求参数

返回数据

示例

• 请求示例

  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

参数说明

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

返回数据

示例

• 请求示例

  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

参数说明

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

返回数据

示例

• 请求示例

  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

返回数据

示例

• 请求示例

  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

请求参数

返回数据

示例

• 请求示例

  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

请求参数

返回数据

示例

• 请求示例

  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

请求参数

返回数据

示例

• 请求示例

  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

请求参数

返回数据

示例

• 请求示例

  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

返回数据

示例

• 请求示例

  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

返回数据

示例

• 请求示例

  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

请求参数

返回数据

只有当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"
          }
  }

3.16. 查询客户端的注册信息（新）

接口描述

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

客户端不存在时会报错

请求方式

GET

请求URL

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

请求参数

返回数据

示例

• 请求示例

  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

请求参数

返回数据

示例

• 请求示例

  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

请求参数

返回数据

示例

• 请求示例

  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

请求参数

返回数据

示例

• 请求示例

  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

返回数据

命名空间分为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
                  }
          ]
  }

4.2. 查询具体命名空间

接口描述

查询具体命名空间的信息

命名空间不存在时会报错

请求方式

GET

请求URL

/nacos/v2/console/namespace

请求参数

返回数据

命名空间分为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
          }
  }

4.3. 创建命名空间

接口描述

创建一个命名空间

命名空间已存在时会报错

请求方式

POST

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

请求URL

/nacos/v2/console/namespace

请求Body

返回数据

示例

• 请求示例

  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

返回数据

示例

• 请求示例

  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

请求参数

返回数据

示例

• 请求示例

  curl -d 'namespaceId=test_namespace' \
    -X DELETE 'http://127.0.0.1:8848/nacos/v2/console/namespace'

• 返回示例

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