客户端API

使用默认鉴权插件时如何获取和配置访问凭据，请参见 OpenAPI 如何配置鉴权信息。

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

请求URL

/nacos/v3/client/ns/instance

请求头

参数名	参数类型	是否必填	描述说明
`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`	是	服务名
`ip`	`string`	是	`IP`地址
`port`	`integer`	是	端口号
`clusterName`	`string`	否	集群名称，默认为`DEFAULT`
`healthy`	`boolean`	否	是否只查找健康实例，默认为`true`
`weight`	`number`	否	实例权重，默认为`1.0`
`enabled`	`boolean`	否	是否可用，默认为`true`
`metadata`	`string`	否	实例元数据
`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

请求URL

/nacos/v3/client/ns/instance

请求头

参数名	参数类型	是否必填	描述说明
`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`	是	服务名
`ip`	`string`	是	`IP`地址
`port`	`integer`	是	端口号
`clusterName`	`string`	否	集群名称，默认为`DEFAULT`

返回数据

返回体遵循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`

返回数据

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

参数名	参数类型	描述说明
`data`	`Object[]`	实例列表
`data.[i].ip`	`string`	实例`IP`
`data.[i].port`	`integer`	实例端口号
`data.[i].weight`	`number`	实例权重
`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`	`integer`	实例心跳超时时间
`data.[i].ipDeleteTimeout`	`integer`	实例删除超时时间
`data.[i].instanceHeartBeatInterval`	`integer`	实例心跳间隔

示例

请求示例

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

3. AI 相关

3.1. 查询 Prompt

接口描述

通过该接口，可按 label、version 或 latest 查询 Prompt，优先级 label > version > latest；支持 md5 条件返回 304。

请求方式

GET

请求URL

/nacos/v3/client/ai/prompt

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	命名空间，默认为`public`
`promptKey`	`string`	是	Prompt 键名
`version`	`string`	否	版本号，与 label、latest 三选一
`label`	`string`	否	标签，与 version、latest 三选一
`md5`	`string`	否	若与服务端一致则返回 304

返回数据

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

参数名	参数类型	描述
`promptKey`	`string`	Prompt 键名
`version`	`string`	版本号
`template`	`string`	Prompt 模板内容
`md5`	`string`	内容 md5，用于 304 判断

示例

请求示例

curl -X GET '127.0.0.1:8848/nacos/v3/client/ai/prompt?promptKey=myPrompt'

返回示例

{
  "code": 0,
  "message": "success",
  "data": {
    "promptKey": "myPrompt",
    "version": "1.0",
    "template": "You are a helpful assistant.",
    "md5": "..."
  }
}

3.2. 获取 AgentSpec

接口描述

通过该接口，可按命名空间、名称、版本号或 label 获取指定 AgentSpec 详情。

请求方式

GET

请求URL

/nacos/v3/client/ai/agentspecs

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	命名空间，默认为`public`
`name`	`string`	是	AgentSpec 名称
`version`	`string`	否	AgentSpec 版本号
`label`	`string`	否	AgentSpec 标签

返回数据

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

参数名	参数类型	描述说明
`namespaceId`	`string`	AgentSpec 所属命名空间
`name`	`string`	AgentSpec 名称
`description`	`string`	AgentSpec 描述
`bizTags`	`string`	AgentSpec 业务标签
`content`	`string`	AgentSpec 内容
`resource`	`object`	AgentSpec 资源信息

示例

请求示例

curl -X GET '127.0.0.1:8848/nacos/v3/client/ai/agentspecs?name=my-agent'

返回示例

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

3.3. 搜索 AgentSpec

接口描述

通过该接口，可按命名空间和关键词分页搜索 AgentSpec。

请求方式

GET

请求URL

/nacos/v3/client/ai/agentspecs/search

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	命名空间，默认为`public`
`keyword`	`string`	否	搜索关键字
`pageNo`	`integer`	是	页码，通常从 `1` 开始
`pageSize`	`integer`	是	每页返回条数

返回数据

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

参数名	参数类型	描述说明
`data`	`string`	AgentSpec 搜索结果（分页结构，具体字段以实际返回为准）

示例

请求示例

curl -X GET '127.0.0.1:8848/nacos/v3/client/ai/agentspecs/search?keyword=agent&pageNo=1&pageSize=10'

返回示例

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

3.4. 下载 Skill

接口描述

通过该接口，可按命名空间、名称、版本号或 label 下载 Skill ZIP 文件。

请求方式

GET

请求URL

/nacos/v3/client/ai/skills

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	命名空间，默认为`public`
`name`	`string`	是	Skill 名称
`version`	`string`	否	Skill 版本号
`label`	`string`	否	Skill 标签

示例

请求示例

curl -X GET '127.0.0.1:8848/nacos/v3/client/ai/skills?name=my-skill'

返回示例

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