Client API

客户端API

注意

Nacos 3.X 版本将不再兼容1.X版本的OpenAPI，同时不再兼容2.X版本的HTTP OpenAPI，请使用Nacos 3.X版本的OpenAPI进行替换。

Nacos 3.X 的 HTTP OpenAPI 主要面向不支持 gRPC 的编程语言开发客户端使用 ，其设计目的是为普通应用、微服务应用 ，以及其他 非管控类 和 非网关类 应用提供配置获取、服务注册与发现的功能支持。

该接口仅提供单服务或单配置级别的数据操作能力（例如对单个服务或配置项的增删改查），不支持范围型聚合操作（如查询全部服务列表、配置列表等批量数据接口）。

如有管控类和网关类的应用需求，需要使用范围型数据操作接口，请使用Admin 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. 配置管理

注意

Nacos 3.X 的HTTP OpenAPI 不提供配置的发布和删除接口，普通应用、微服务应用，以及其他 非管控类 和 非网关类 应用 应该 为配置的使用方而非发布方；若需要进行配置发布和删除操作，请使用运维 API。

另外，由于Nacos 3.X 即将移除配置长轮询监听相关的功能，仅保留通过长连接进行配置监听，因此Nacos 3.X 的HTTP OpenAPI 不提供配置的监听接口。您可以通过轮询获取配置，比对前后的md5来判断是否需要更新配置。

1.1. 获取配置

接口描述

获取指定配置

请求方式

GET

请求URL

/nacos/v3/client/cs/config

请求头

请求参数

返回数据

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

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

示例

• 请求示例

Terminal window

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. 服务发现

注意

Nacos 3.X 的HTTP OpenAPI 不提供查询所有服务列表等接口，普通应用、微服务应用，以及其他 非管控类 和 非网关类 应用 应该 仅需要注册为某一服务的实例，或从某一服务中注销自身，亦或获取已知的下游服务的实例列表进行实际的业务调用，不应该获取所有注册中心中的服务列表。

若需要获取所有服务列表，请使用运维 API。

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

请求头

请求Body

返回数据

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

示例

• 请求示例

Terminal window

## 注册实例
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

请求头

请求Body

返回数据

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

示例

• 请求示例

Terminal window

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. 查询指定服务的实例列表

接口描述

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

注意

由于Nacos3.X即将移除UDP类型的推送支持，因此对于不支持Grpc长连接推送的客户端，需要定期进行一次实例列表的拉取，以保证客户端能及时感知到实例列表的变化，以实现订阅服务的功能。

请求方式

GET

请求URL

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

请求头

请求参数

返回数据

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

示例

• 请求示例

Terminal window

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