客户端API

0. 客户端API 相关说明

0.1. 统一路径格式

Nacos的运维API，使用统一的Path格式进行的规范。格式为[/$nacos.server.contextPath]/v3/client/[module]/[subPath]..., 其中

$nacos.server.contextPath：运维API的根路径，默认为/nacos，可以通过nacos.server.contextPath配置项进行修改。
module：运维API模块名称，例如server、cs、ns、core等。
subPath：运维API的子路径，例如state、namespace、config等，可能有多层子路径。

下列列出的运维API，采用默认$nacos.server.contextPath的情况进行展示，若已修改部署环境中的$nacos.server.contextPath 配置项，请自行修改调用API时的请求URL。

同时下列列出的运维API样例中，均采用默认Nacos Web Server的端口进行展示，若已修改部署环境中的$nacos.server.main.port 配置项，请自行修改调用API时的请求URL。

0.2. Swagger 类型文档

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

1. 配置管理

1.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
  }
}

2. 服务发现

2.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"
}

2.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"
}

2.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
    }
  ]
}