Open API 手册

Nacos 3.X 版本将不再兼容1.X版本的OpenAPI，同时不再兼容2.X版本的HTTP OpenAPI，请使用Nacos 3.X版本的OpenAPI进行替换。 Nacos 3.X 的HTTP OpenAPI 正在建设中，将在3.0.0-BETA版本中完成。

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
  }