Open API 手册

0. Swagger 类型文档

Nacos 3.X 的客户端 Open API 也提供了Swagger风格的文档，您可以通过访问Nacos Swagger HTTP 客户端 API查看。

1. 文档规定

1.1. API 统一返回体格式

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

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

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

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

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

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

2. 配置管理

2.1. 获取配置

接口描述

获取指定配置

请求方式

GET

请求URL

/nacos//v3/client/cs/config

请求头

参数名	参数类型	是否必填	描述说明
`User-Agent`	`String`	否	用户代理，默认为空，通常为`Nacos-${program-language}-Client ${version}
`Client-Version`	`String`	否	客户端版本，默认为空，通常为`Nacos-${program-language}-Client ${version}

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`String`	否	命名空间，默认为`public`与 `''`相同
`groupName`	`String`	是	配置分组名
`dataId`	`String`	是	配置名

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`content`	`String`	配置内容
`encryptedDataKey`	`String`	配置的加解密密钥，仅在使用配置加解密插件时有此值
`contentType`	`String`	配置的类型，如`TEXT`,`JSON`等
`md5`	`String`	配置的md5值
`lastModified`	`String`	配置的最后修改时间
`beta`	`boolean`	配置是否有灰度配置

其他字段为预留字段，暂时无用，忽略即可。

示例

请求示例

curl -X GET '127.0.0.1:8848/nacos/v3/client/cs/config?dataId=test&groupName=test'

返回示例

{
  "code": 0,
  "message": "success",
  "data": {
    "resultCode": 200,
    "errorCode": 0,
    "message": null,
    "requestId": null,
    "content": "test",
    "encryptedDataKey": null,
    "contentType": "text",
    "md5": "098f6bcd4621d373cade4e832627b4f6",
    "lastModified": 1743151634823,
    "tag": null,
    "beta": false,
    "success": true
  }
}

3. 服务发现

3.1. 注册实例/续约实例

接口描述

注册或续约一个实例

当通过HTTP OpenAPI注册的实例为临时实例时，需要定期对实例进行续约，在Nacos3.X的HTTP OpenAPI中，续约此实例的API和注册实例的API进行了合并，通过参数heartBeat进行区分。

当为续约请求时， Nacos不会对请求中的元数据等内容进行解析，即续约请求将会忽略传入的healthy,weight,enabled,metadata 字段。当续约请求返回的错误码为21003 时，说明该实例已过期被移除，需要重新进行注册，此时客户端应带上完整的信息，同时设置heartBeat=false进行重新注册，重新注册成功后再进行续约请求。

若连续调用注册请求，也可以起到续约实例的作用，但是是通过更新实例的方式进行续约，会耗费更多的性能，因此请在注册成功后进行续约操作而非继续进行注册更新。

请求方式

POST

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

请求URL

/nacos/v3/client/ns/instance

请求头

参数名	参数类型	是否必填	描述说明
`User-Agent`	`String`	否	用户代理，默认为空，通常为`Nacos-${program-language}-Client ${version}
`Client-Version`	`String`	否	客户端版本，默认为空，通常为`Nacos-${program-language}-Client ${version}

请求Body

参数名	参数类型	是否必填	描述说明
`namespaceId`	`String`	否	命名空间`Id`，默认为`public`
`groupName`	`String`	否	分组名，默认为`DEFAULT_GROUP`
`serviceName`	`String`	是	服务名
`ip`	`String`	是	`IP`地址
`port`	`int`	是	端口号
`clusterName`	`String`	否	集群名称，默认为`DEFAULT`
`healthy`	`boolean`	否	是否只查找健康实例，默认为`true`
`weight`	`double`	否	实例权重，默认为`1.0`
`enabled`	`boolean`	否	是否可用，默认为`true`
`metadata`	`JSON格式String`	否	实例元数据
`ephemeral`	`boolean`	否	是否为临时实例
`heartBeat`	`boolean`	否	是否为续约请求，默认为`false`

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`String`	是否注册、续约成功，成功时返回`ok`，失败时返回失败原因。

示例

请求示例

# 注册实例
curl -X POST "127.0.0.1:8848/nacos/v3/client/ns/instance" -d "serviceName=test1&ip=127.0.0.1&port=3306"

# 续约实例
curl -X POST "127.0.0.1:8848/nacos/v3/client/ns/instance" -d "serviceName=test1&ip=127.0.0.1&port=3306&heartBeat=true"

返回示例

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

3.2. 注销实例

接口描述

注销指定实例

请求方式

DELETE

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

请求URL

/nacos/v3/client/ns/instance

请求头

参数名	参数类型	是否必填	描述说明
`User-Agent`	`String`	否	用户代理，默认为空，通常为`Nacos-${program-language}-Client ${version}
`Client-Version`	`String`	否	客户端版本，默认为空，通常为`Nacos-${program-language}-Client ${version}

请求Body

参数名	参数类型	是否必填	描述说明
`namespaceId`	`String`	否	命名空间`Id`，默认为`public`
`groupName`	`String`	否	分组名，默认为`DEFAULT_GROUP`
`serviceName`	`String`	是	服务名
`ip`	`String`	是	`IP`地址
`port`	`int`	是	端口号
`clusterName`	`String`	否	集群名称，默认为`DEFAULT`
`ephemeral`	`boolean`	否	是否为临时实例

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述
`data`	`String`	是否注销成功，成功时返回`ok`，失败时返回失败原因。

示例

请求示例

curl -X DELETE "127.0.0.1:8848/nacos/v3/client/ns/instance?serviceName=test1&ip=127.0.0.1&port=3306"

返回示例

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

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

接口描述

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

请求方式

GET

请求URL

/nacos/v3/client/ns/instance/list

请求头

参数名	参数类型	是否必填	描述说明
`User-Agent`	`String`	否	用户代理，默认为空，通常为`Nacos-${program-language}-Client ${version}
`Client-Version`	`String`	否	客户端版本，默认为空，通常为`Nacos-${program-language}-Client ${version}

请求参数

参数名	参数类型	是否必填	描述说明
`namespaceId`	`String`	否	命名空间`Id`，默认为`public`
`groupName`	`String`	否	分组名，默认为`DEFAULT_GROUP`
`serviceName`	`String`	是	服务名
`clusterName`	`String`	否	集群名称，默认为`DEFAULT`
`healthyOnly`	`boolean`	否	是否只获取健康实例，默认为`false`

返回数据

返回体遵循Nacos open API 统一返回体格式，下表只阐述data字段中的返回参数。

参数名	参数类型	描述说明
`data`	`Object[]`	实例列表
`data.[i].ip`	`String`	实例`IP`
`data.[i].port`	`int`	实例端口号
`data.[i].weight`	`double`	实例权重
`data.[i].healthy`	`boolean`	实例是否健康
`data.[i].enabled`	`boolean`	实例是否可用
`data.[i].ephemeral`	`boolean`	是否为临时实例
`data.[i].clusterName`	`String`	实例所在的集群名称
`data.[i].serviceName`	`String`	服务名
`data.[i].metadata`	`map`	实例元数据
`data.[i].instanceHeartBeatTimeOut`	`int`	实例心跳超时时间
`data.[i].ipDeleteTimeout`	`int`	实例删除超时时间
`data.[i].instanceHeartBeatInterval`	`int`	实例心跳间隔

示例

请求示例

curl -X GET '127.0.0.1:8848/nacos/v3/client/ns/instance/list?serviceName=test1'

返回示例

{
  "code": 0,
  "message": "success",
  "data": [
    {
      "ip": "127.0.0.1",
      "port": 3306,
      "weight": 1.0,
      "healthy": true,
      "enabled": true,
      "ephemeral": true,
      "clusterName": "DEFAULT",
      "serviceName": "DEFAULT_GROUP@@test1",
      "metadata": {},
      "ipDeleteTimeout": 30000,
      "instanceIdGenerator": "simple",
      "instanceHeartBeatInterval": 5000,
      "instanceHeartBeatTimeOut": 15000
    }
  ]
}