客户端API

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

0. 客户端API 相关说明

0.1. 适用边界

客户端 API 面向应用运行时和自定义客户端。调用者通常已经知道要访问的 namespaceId、groupName、dataId、serviceName 或实例信息。

适合使用	不适合使用
查询单个已知配置。	发布、删除、导入、导出配置。
注册、注销、查询和发现已知服务或实例。	查询全量配置列表、全量服务列表、订阅者列表等范围型数据。
在缺少合适 SDK 的语言中，通过 HTTP 完成少量运行时访问。	构建发布平台、运维平台、网关管控面或审计工具。

业务应用优先使用 SDK。需要范围型管理能力时，请使用运维 API或运维 SDK。

0.2. 统一路径格式

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.3. Swagger 类型文档

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

1. 配置管理

1.1. 获取配置

接口描述

获取指定配置

起始版本

3.0.0

请求方式

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`	`integer`	配置的最后修改时间
`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进行重新注册，重新注册成功后再进行续约请求。

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

起始版本

3.0.0

请求方式

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`	否	实例元数据，JSON 对象字符串
`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. 注销实例

接口描述

注销指定实例

起始版本

3.0.0

请求方式

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

接口描述

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

起始版本

3.0.0

请求方式

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`	否	集群名称，不传则查询所有集群的实例

返回数据

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

参数名	参数类型	描述说明
`data`	`array`	实例列表
`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<string, string>`	实例元数据
`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

接口描述

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

起始版本

3.2.0

请求方式

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 判断
`variables`	`array`	Prompt 变量列表

示例

请求示例

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 详情。

起始版本

3.2.0

请求方式

GET

请求URL

/nacos/v3/client/ai/agentspecs

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	命名空间，默认为`public`
`name`	`string`	是	AgentSpec 名称
`version`	`string`	否	AgentSpec 版本号
`label`	`string`	否	AgentSpec 标签
`md5`	`string`	否	AgentSpec 内容 MD5，用于精确匹配指定版本

返回数据

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

起始版本

3.2.0

请求方式

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 文件。

起始版本

3.2.0

请求方式

GET

请求URL

/nacos/v3/client/ai/skills

请求参数

参数名	类型	必填	参数描述
`namespaceId`	`string`	否	命名空间，默认为`public`
`name`	`string`	是	Skill 名称
`version`	`string`	否	Skill 版本号
`label`	`string`	否	Skill 标签
`md5`	`string`	否	Skill 内容 MD5，用于精确匹配指定版本

示例

请求示例

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

返回示例

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