版本：2.X（推荐）

Open API 指南

配置管理
服务发现
命名空间

配置管理

获取配置

描述

获取Nacos上的配置。

请求类型

GET

请求URL

/nacos/v1/cs/configs

请求参数

名称	类型	是否必须	描述
tenant	string	否	租户信息，对应 Nacos 的命名空间ID字段。
dataId	string	是	配置 ID。
group	string	是	配置分组。

返回参数

参数类型	描述
string	配置值

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例

请求示例

curl -X GET 'http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=nacos.example&group=com.alibaba.nacos'

返回示例
```
contentTest
```

监听配置

描述

监听 Nacos 上的配置，以便实时感知配置变更。如果配置变更，则用获取配置接口获取配置的最新值，动态刷新本地缓存。

注册监听采用的是异步 Servlet 技术。注册监听本质就是带着配置和配置值的 MD5 值和后台对比。如果 MD5 值不一致，就立即返回不一致的配置。如果值一致，就等待住 30 秒。返回值为空。

请求类型

POST

请求URL

/nacos/v1/cs/configs/listener

请求参数

名称	类型	是否必须	描述
Listening-Configs	string	是	监听数据报文。格式为 dataId^2Group^2contentMD5^2tenant^1或者dataId^2Group^2contentMD5^1。 dataId：配置 ID group：配置分组 contentMD5：配置内容 MD5 值 tenant：租户信息，对应 Nacos 的命名空间字段(非必填)

名称	类型	是否必须	描述
Long-Pulling-Timeout	string	是	长轮训等待 30s，此处填写 30000。

参数说明

配置多个字段间分隔符：^2 = Character.toString((char) 2，urlencode 后值为 %02
配置间分隔符：^1 = Character.toString((char) 1)，urlencode 后值为 %01
contentMD5: MD5(content)，第一次本地缓存为空，所以这块为空串

返回参数

参数类型	描述
string	配置值

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例

请求示例

http://serverIp:8848/nacos/v1/cs/configs/listener

POST 请求体数据内容：

Listening-Configs=dataId%02group%02contentMD5%02tenant%01

返回示例

如果配置变化

dataId%02group%02tenant%01

如果配置无变化：会返回空串

发布配置

描述

发布 Nacos 上的配置。

请求类型

POST

请求 URL

/nacos/v1/cs/configs

请求参数

名称	类型	是否必须	描述
tenant	string	否	租户信息，对应 Nacos 的命名空间ID字段
dataId	string	是	配置 ID
group	string	是	配置分组
content	string	是	配置内容
type	String	否	配置类型

返回参数

参数类型	描述
boolean	是否发布成功

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例

请求示例

curl -X POST 'http://127.0.0.1:8848/nacos/v1/cs/configs' -d 'dataId=nacos.example&group=com.alibaba.nacos&content=contentTest'

返回示例

true

删除配置

描述

删除 Nacos 上的配置。

请求类型

DELETE

请求 URL

/nacos/v1/cs/configs

请求参数

名称	类型	是否必须	描述
tenant	string	否	租户信息，对应 Naocs 的命名空间ID字段
dataId	string	是	配置 ID
group	string	是	配置分组

返回参数

参数类型	描述
boolean	是否删除成功

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例

请求示例

curl -X DELETE 'http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=nacos.example&group=com.alibaba.nacos'

返回示例

true

查询历史版本

描述

查询配置项历史版本。

请求类型

GET

请求 URL

/nacos/v1/cs/history?search=accurate

请求参数

名称	类型	是否必须	描述
tenant	string	否	租户信息，对应 Naocs 的命名空间ID字段
dataId	string	是	配置 ID
group	string	是	配置分组
pageNo	integer	否	当前页码
pageSize	integer	否	分页条数(默认100条,最大为500)

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例

请求示例

curl -X GET 'http://127.0.0.1:8848/nacos/v1/cs/history?search=accurate&dataId=nacos.example&group=com.alibaba.nacos'

返回示例

{
  "totalCount": 1,
  "pageNumber": 1,
  "pagesAvailable": 1,
  "pageItems": [
    {
      "id": "203",
      "lastId": -1,
      "dataId": "nacos.example",
      "group": "com.alibaba.nacos",
      "tenant": "",
      "appName": "",
      "md5": null,
      "content": null,
      "srcIp": "0:0:0:0:0:0:0:1",
      "srcUser": null,
      "opType": "I         ",
      "createdTime": "2010-05-04T16:00:00.000+0000",
      "lastModifiedTime": "2020-12-05T01:48:03.380+0000"
    }
  ]
}

查询历史版本详情

描述

查询配置项历史版本详情

请求类型

GET

请求 URL

/nacos/v1/cs/history

请求参数

名称	类型	是否必须	描述
nid	Integer	是	配置项历史版本ID
tenant	string	否	租户信息，对应 Naocs 的命名空间ID字段（2.0.3起）
dataId	string	是	配置 ID （2.0.3起）
group	string	是	配置分组（2.0.3起）

注意：2.0.3版本起，此接口需要新增字段tenant、dataId和group，其中tenant非必填。

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例

请求示例

curl -X GET 'http://127.0.0.1:8848/nacos/v1/cs/history?nid=203&tenant=&dataId=nacos.example&group=com.alibaba.nacos'

返回示例

{
  "id": "203",
  "lastId": -1,
  "dataId": "nacos.example",
  "group": "com.alibaba.nacos",
  "tenant": "",
  "appName": "",
  "md5": "9f67e6977b100e00cab385a75597db58",
  "content": "contentTest",
  "srcIp": "0:0:0:0:0:0:0:1",
  "srcUser": null,
  "opType": "I         ",
  "createdTime": "2010-05-04T16:00:00.000+0000",
  "lastModifiedTime": "2020-12-05T01:48:03.380+0000"
}

查询配置上一版本信息

描述

查询配置上一版本信息(1.4起)

请求类型

GET

请求 URL

/nacos/v1/cs/history/previous

请求参数

名称	类型	是否必须	描述
id	Integer	是	配置ID
tenant	string	否	租户信息，对应 Naocs 的命名空间ID字段（2.0.3起）
dataId	string	是	配置 ID （2.0.3起）
group	string	是	配置分组（2.0.3起）

说明：2.0.3版本起，此接口需要新增字段tenant、dataId和group，其中tenant非必填。

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例

请求示例

curl -X GET 'http://127.0.0.1:8848/nacos/v1/cs/history/previous?id=309135486247505920&tenant=&dataId=nacos.example&group=com.alibaba.nacos'

返回示例

{
  "id": "203",
  "lastId": -1,
  "dataId": "nacos.example",
  "group": "com.alibaba.nacos",
  "tenant": "",
  "appName": "",
  "md5": "9f67e6977b100e00cab385a75597db58",
  "content": "contentTest",
  "srcIp": "0:0:0:0:0:0:0:1",
  "srcUser": null,
  "opType": "I         ",
  "createdTime": "2010-05-04T16:00:00.000+0000",
  "lastModifiedTime": "2020-12-05T01:48:03.380+0000"
}

服务发现

注册实例

描述

注册一个实例到服务。

请求类型

POST

请求路径

/nacos/v1/ns/instance

请求参数

名称	类型	是否必选	描述
ip	字符串	是	服务实例IP
port	int	是	服务实例port
namespaceId	字符串	否	命名空间ID
weight	double	否	权重
enabled	boolean	否	是否上线
healthy	boolean	否	是否健康
metadata	字符串	否	扩展信息
clusterName	字符串	否	集群名
serviceName	字符串	是	服务名
groupName	字符串	否	分组名
ephemeral	boolean	否	是否临时实例

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例请求

curl -X POST 'http://127.0.0.1:8848/nacos/v1/ns/instance?port=8848&healthy=true&ip=11.11.11.11&weight=1.0&serviceName=nacos.test.3&encoding=GBK&namespaceId=n1'

示例返回

注销实例

描述

删除服务下的一个实例。

请求类型

DELETE

请求路径

/nacos/v1/ns/instance

请求参数

名称	类型	是否必选	描述
serviceName	字符串	是	服务名
groupName	字符串	否	分组名
ip	字符串	是	服务实例IP
port	int	是	服务实例port
clusterName	字符串	否	集群名称
namespaceId	字符串	否	命名空间ID
ephemeral	boolean	否	是否临时实例

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例请求

curl -X DELETE '127.0.0.1:8848/nacos/v1/ns/instance?serviceName=nacos.test.1&ip=1.1.1.1&port=8888&clusterName=TEST1'

示例返回

修改实例

描述

修改服务下的一个实例。

注意：在Nacos2.0版本后，通过该接口更新的元数据拥有更高的优先级，且具有记忆能力；会在对应实例删除后，依旧存在一段时间，如果在此期间实例重新注册，该元数据依旧生效；您可以通过nacos.naming.clean.expired-metadata.expired-time及nacos.naming.clean.expired-metadata.interval对记忆时间进行修改

请求类型

PUT

请求路径

/nacos/v1/ns/instance

请求参数

名称	类型	是否必选	描述
serviceName	字符串	是	服务名
groupName	字符串	否	分组名
ip	字符串	是	服务实例IP
port	int	是	服务实例port
clusterName	字符串	否	集群名称
namespaceId	字符串	否	命名空间ID
weight	double	否	权重
metadata	JSON	否	扩展信息
enabled	boolean	否	是否打开流量
ephemeral	boolean	否	是否临时实例

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例请求

curl -X PUT '127.0.0.1:8848/nacos/v1/ns/instance?serviceName=nacos.test.1&ip=1.1.1.1&port=8888&clusterName=TEST1&weight=8&metadata={}'

示例返回

查询实例列表

描述

查询服务下的实例列表

请求类型

GET

请求路径

/nacos/v1/ns/instance/list

请求参数

名称	类型	是否必选	描述
serviceName	字符串	是	服务名
groupName	字符串	否	分组名
namespaceId	字符串	否	命名空间ID
clusters	字符串，多个集群用逗号分隔	否	集群名称
healthyOnly	boolean	否，默认为false	是否只返回健康实例

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例请求

curl -X GET '127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=nacos.test.1'

示例返回

{
  "name": "DEFAULT_GROUP@@nacos.test.1", 
  "groupName": "DEFAULT_GROUP", 
  "clusters": "", 
  "cacheMillis": 10000, 
  "hosts": [
    {
      "instanceId": "10.10.10.10#8888#DEFAULT#DEFAULT_GROUP@@nacos.test.1", 
      "ip": "10.10.10.10", 
      "port": 8888, 
      "weight": 1, 
      "healthy": false, 
      "enabled": true, 
      "ephemeral": false, 
      "clusterName": "DEFAULT", 
      "serviceName": "DEFAULT_GROUP@@nacos.test.1", 
      "metadata": { }, 
      "instanceHeartBeatInterval": 5000, 
      "instanceIdGenerator": "simple", 
      "instanceHeartBeatTimeOut": 15000, 
      "ipDeleteTimeout": 30000
    }
  ], 
  "lastRefTime": 1528787794594, 
  "checksum": "", 
  "allIPs": false, 
  "reachProtectionThreshold": false, 
  "valid": true
}

查询实例详情

描述

查询一个服务下个某个实例详情。

请求类型

GET

请求路径

/nacos/v1/ns/instance

请求参数

名称	类型	是否必选	描述
serviceName	字符串	是	服务名
groupName	字符串	否	分组名
ip	字符串	是	实例IP
port	字符串	是	实例端口
namespaceId	字符串	否	命名空间ID
cluster	字符串	否	集群名称
healthyOnly	boolean	否，默认为false	是否只返回健康实例
ephemeral	boolean	否	是否临时实例

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例请求

curl -X GET '127.0.0.1:8848/nacos/v1/ns/instance?serviceName=nacos.test.2&ip=10.10.10.10&port=8888&cluster=DEFAULT'

示例返回

{
    "metadata": {},
    "instanceId": "10.10.10.10-8888-DEFAULT-nacos.test.2",
    "port": 8888,
    "service": "nacos.test.2",
    "healthy": false,
    "ip": "10.10.10.10",
    "clusterName": "DEFAULT",
    "weight": 1.0
}

发送实例心跳

描述

发送某个实例的心跳

请求类型

PUT

请求路径

/nacos/v1/ns/instance/beat

请求参数

名称	类型	是否必选	描述
serviceName	字符串	是	服务名
ip	字符串	是	服务实例IP
port	int	是	服务实例PORT
namespaceId	字符串	否	命名空间ID
groupName	字符串	否	分组名
ephemeral	boolean	否	是否临时实例
beat	JSON格式字符串	是	实例心跳内容

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例请求

curl -X PUT '127.0.0.1:8848/nacos/v1/ns/instance/beat?serviceName=nacos.test.2&beat=%7b%22cluster%22%3a%22c1%22%2c%22ip%22%3a%22127.0.0.1%22%2c%22metadata%22%3a%7b%7d%2c%22port%22%3a8080%2c%22scheduled%22%3atrue%2c%22serviceName%22%3a%22jinhan0Fx4s.173TL.net%22%2c%22weight%22%3a1%7d'

示例返回

ok

创建服务

描述

创建一个服务

请求类型

POST

请求路径

/nacos/v1/ns/service

请求参数

名称	类型	是否必选	描述
serviceName	字符串	是	服务名
groupName	字符串	否	分组名
namespaceId	字符串	否	命名空间ID
protectThreshold	浮点数	否	保护阈值,取值0到1,默认0
metadata	字符串	否	元数据
selector	JSON格式字符串	否	访问策略

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例请求

curl -X POST '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2&metadata=k1%3dv1'

示例返回

ok

删除服务

描述

删除一个服务,只有当服务下实例数为0时允许删除

请求类型

DELETE

请求路径

/nacos/v1/ns/service

请求参数

名称	类型	是否必选	描述
serviceName	字符串	是	服务名
groupName	字符串	否	分组名
namespaceId	字符串	否	命名空间ID

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例请求

curl -X DELETE '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2'

示例返回

ok

修改服务

描述

更新一个服务

请求类型

PUT

请求路径

/nacos/v1/ns/service

请求参数

名称	类型	是否必选	描述
serviceName	字符串	是	服务名
groupName	字符串	否	分组名
namespaceId	字符串	否	命名空间ID
protectThreshold	浮点数	否	保护阈值,取值0到1,默认0
metadata	字符串	否	元数据
selector	JSON格式字符串	否	访问策略

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例请求

curl -X PUT '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2&metadata=k1%3dv1'

示例返回

ok

查询服务

描述

查询一个服务

请求类型

GET

请求路径

/nacos/v1/ns/service

请求参数

名称	类型	是否必选	描述
serviceName	字符串	是	服务名
groupName	字符串	否	分组名
namespaceId	字符串	否	命名空间ID

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例请求

curl -X GET '127.0.0.1:8848/nacos/v1/ns/service?serviceName=nacos.test.2'

示例返回

{
    metadata: { },
    groupName: "DEFAULT_GROUP",
    namespaceId: "public",
    name: "nacos.test.2",
    selector: {
        type: "none"
    },
    protectThreshold: 0,
    clusters: [
        {
            healthChecker: {
                type: "TCP"
            },
            metadata: { },
            name: "c1"
        }
    ]
}

查询服务列表

描述

查询服务列表

请求类型

GET

请求路径

/nacos/v1/ns/service/list

请求参数

名称	类型	是否必选	描述
pageNo	int	是	当前页码
pageSize	int	是	分页大小
groupName	字符串	否	分组名
namespaceId	字符串	否	命名空间ID

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例请求

curl -X GET '127.0.0.1:8848/nacos/v1/ns/service/list?pageNo=1&pageSize=2'

示例返回

{
    "count":148,
    "doms": [
        "nacos.test.1",
        "nacos.test.2"
    ]
}

查询系统开关

描述

查询系统开关

请求类型

GET

请求路径

/nacos/v1/ns/operator/switches

请求参数

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例请求

curl -X GET '127.0.0.1:8848/nacos/v1/ns/operator/switches'

示例返回

{
    name: "00-00---000-NACOS_SWITCH_DOMAIN-000---00-00",
    masters: null,
    adWeightMap: { },
    defaultPushCacheMillis: 10000,
    clientBeatInterval: 5000,
    defaultCacheMillis: 3000,
    distroThreshold: 0.7,
    healthCheckEnabled: true,
    distroEnabled: true,
    enableStandalone: true,
    pushEnabled: true,
    checkTimes: 3,
    httpHealthParams: {
        max: 5000,
        min: 500,
        factor: 0.85
    },
    tcpHealthParams: {
        max: 5000,
        min: 1000,
        factor: 0.75
    },
    mysqlHealthParams: {
        max: 3000,
        min: 2000,
        factor: 0.65
    },
    incrementalList: [ ],
    serverStatusSynchronizationPeriodMillis: 15000,
    serviceStatusSynchronizationPeriodMillis: 5000,
    disableAddIP: false,
    sendBeatOnly: false,
    limitedUrlMap: { },
    distroServerExpiredMillis: 30000,
    pushGoVersion: "0.1.0",
    pushJavaVersion: "0.1.0",
    pushPythonVersion: "0.4.3",
    pushCVersion: "1.0.12",
    enableAuthentication: false,
    overriddenServerStatus: "UP",
    defaultInstanceEphemeral: true,
    healthCheckWhiteList: [ ],
    checksum: null
}

修改系统开关

描述

修改系统开关

请求类型

PUT

请求路径

/nacos/v1/ns/operator/switches

请求参数

名称	类型	是否必选	描述
entry	字符串	是	开关名
value	字符串	是	开关值
debug	boolean	否	是否只在本机生效,true表示本机生效,false表示集群生效

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例请求

curl -X PUT '127.0.0.1:8848/nacos/v1/ns/operator/switches?entry=pushEnabled&value=false&debug=true'

示例返回

ok

查看系统当前数据指标

描述

查看系统当前数据指标

请求类型

GET

请求路径

/nacos/v1/ns/operator/metrics

请求参数

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例请求

curl -X GET '127.0.0.1:8848/nacos/v1/ns/operator/metrics'

示例返回

{
    serviceCount: 336,
    load: 0.09,
    mem: 0.46210432,
    responsibleServiceCount: 98,
    instanceCount: 4,
    cpu: 0.010242796,
    status: "UP",
    responsibleInstanceCount: 0
}

查看当前集群Server列表

描述

查看当前集群Server列表

请求类型

GET

请求路径

/nacos/v1/ns/operator/servers

请求参数

名称	类型	是否必选	描述
healthy	boolean	否	是否只返回健康Server节点

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例请求

curl -X GET '127.0.0.1:8848/nacos/v1/ns/operator/servers'

示例返回

{
    servers: [
        {
            ip: "1.1.1.1",
            servePort: 8848,
            site: "unknown",
            weight: 1,
            adWeight: 0,
            alive: false,
            lastRefTime: 0,
            lastRefTimeStr: null,
            key: "1.1.1.1:8848"
        },
        {
            ip: "1.1.1.2",
            servePort: 8848,
            site: "unknown",
            weight: 1,
            adWeight: 0,
            alive: false,
            lastRefTime: 0,
            lastRefTimeStr: null,
            key: "1.1.1.2:8848"
        },
        {
            ip: "1.1.1.3",
            servePort: 8848,
            site: "unknown",
            weight: 1,
            adWeight: 0,
            alive: false,
            lastRefTime: 0,
            lastRefTimeStr: null,
            key: "1.1.1.3:8848"
        }
    ]
}

查看当前集群leader

描述

查看当前集群leader

请求类型

GET

请求路径

/nacos/v1/ns/raft/leader

请求参数

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例请求

curl -X GET '127.0.0.1:8848/nacos/v1/ns/raft/leader'

示例返回

{
    leader: "{"heartbeatDueMs":2500,"ip":"1.1.1.1:8848","leaderDueMs":12853,"state":"LEADER","term":54202,"voteFor":"1.1.1.1:8848"}"
}

更新实例的健康状态

描述

更新实例的健康状态,仅在集群的健康检查关闭时才生效,当集群配置了健康检查时,该接口会返回错误

请求类型

PUT

请求路径

/nacos/v1/ns/health/instance

请求参数

名称	类型	是否必选	描述
namespaceId	字符串	否	命名空间ID
serviceName	字符串	是	服务名
groupName	字符串	否	分组名
clusterName	字符串	否	集群名
ip	字符串	是	服务实例IP
port	int	是	服务实例port
healthy	boolean	是	是否健康

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例请求

curl -X PUT 'http://127.0.0.1:8848/nacos/v1/ns/health/instance?port=8848&healthy=true&ip=11.11.11.11&serviceName=nacos.test.3&namespaceId=n1'

示例返回

批量更新实例元数据(Beta)

描述

批量更新实例元数据(1.4起)

注意：该接口为Beta接口，后续版本可能有所修改，甚至删除，请谨慎使用。

请求类型

PUT

请求路径

/nacos/v1/ns/instance/metadata/batch

请求参数

名称	类型	是否必选	描述
namespaceId	字符串	是	命名空间ID
serviceName	字符串	是	服务名(group@@serviceName)
consistencyType	字符串	否	实例的类型(ephemeral/persist)
instances	JSON格式字符串	否	需要更新的实例
metadata	JSON格式字符串	是	元数据信息

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

参数说明

consistencyType: 优先级高于instances参数，如果进行配置，则忽略instances参数的值。当值为'ephemeral'，则对serviceName下的所有非持久化实例进行更新。当值为'persist'，则对serviceName下的所有持久化实例进行更新。当为其他值，没有实例进行更新。
instances: json数组。通过ip+port+ephemeral+cluster定位到某一实例。

示例请求

curl -X PUT 'http://localhost:8848/nacos/v1/ns/instance/metadata/batch' -d 'namespaceId=public&serviceName=xxxx@@xxxx&instances=[{"ip":"3.3.3.3","port": "8080","ephemeral":"true","clusterName":"xxxx-cluster"},{"ip":"2.2.2.2","port":"8080","ephemeral":"true","clusterName":"xxxx-cluster"}]&metadata={"age":"20","name":"cocolan"}' 
or
curl -X PUT 'http://localhost:8848/nacos/v1/ns/instance/metadata/batch' -d 'namespaceId=public&serviceName=xxxx@@xxxx&consistencyType=ephemeral&metadata={"age":"20","name":"cocolan"}'

示例返回

{"updated":["2.2.2.2:8080:unknown:xxxx-cluster:ephemeral","3.3.3.3:8080:unknown:xxxx-cluster:ephemeral"]}

批量删除实例元数据(Beta)

描述

批量删除实例元数据(1.4起)

注意：该接口为Beta接口，后续版本可能有所修改，甚至删除，请谨慎使用。

请求类型

DELETE

请求路径

/nacos/v1/ns/instance/metadata/batch

请求参数

名称	类型	是否必选	描述
namespaceId	字符串	是	命名空间ID
serviceName	字符串	是	服务名(group@@serviceName)
consistencyType	字符串	否	实例的类型(ephemeral/persist)
instances	JSON格式字符串	否	需要更新的实例
metadata	JSON格式字符串	是	元数据信息

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

参数说明

consistencyType: 优先级高于instances参数，如果进行配置，则忽略instances参数的值。当值为ephemeral，则对serviceName下的所有非持久化实例进行更新。当值为persist，则对serviceName下的所有持久化实例进行更新。当为其他值，没有实例进行更新。
instances: json数组。通过ip+port+ephemeral+cluster定位到某一实例。

示例请求

curl -X DELETE 'http://localhost:8848/nacos/v1/ns/instance/metadata/batch' -d 'namespaceId=public&serviceName=xxxx@@xxxx&instances=[{"ip":"3.3.3.3","port": "8080","ephemeral":"true","clusterName":"xxxx-cluster"},{"ip":"2.2.2.2","port":"8080","ephemeral":"true","clusterName":"xxxx-cluster"}]&metadata={"age":"20","name":"cocolan"}' 
or
curl -X DELETE 'http://localhost:8848/nacos/v1/ns/instance/metadata/batch' -d 'namespaceId=public&serviceName=xxxx@@xxxx&consistencyType=ephemeral&metadata={"age":"20","name":"cocolan"}'

示例返回

{"updated":["2.2.2.2:8080:unknown:xxxx-cluster:ephemeral","3.3.3.3:8080:unknown:xxxx-cluster:ephemeral"]}

命名空间

查询命名空间列表

请求类型

GET

请求路径

/nacos/v1/console/namespaces

请求参数

无

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例请求

curl -X GET 'http://localhost:8848/nacos/v1/console/namespaces'

示例返回

{"code":200,"message":null,"data":[{"namespace":"","namespaceShowName":"public","quota":200,"configCount":0,"type":0}]}

创建命名空间

请求类型

POST

请求路径

/nacos/v1/console/namespaces

请求参数

名称	类型	是否必选	描述
customNamespaceId	字符串	是	命名空间ID
namespaceName	字符串	是	命名空间名
namespaceDesc	字符串	否	命名空间描述

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例请求

curl -X POST 'http://localhost:8848/nacos/v1/console/namespaces' -d 'customNamespaceId=&namespaceName=dev&namespaceDesc='

示例返回

true

修改命名空间

请求类型

PUT

请求路径

/nacos/v1/console/namespaces

请求参数

名称	类型	是否必选	描述
namespace	字符串	是	命名空间ID
namespaceShowName	字符串	是	命名空间名
namespaceDesc	字符串	是	命名空间描述

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例请求

curl -X PUT 'http://localhost:8848/nacos/v1/console/namespaces' -d 'namespace=dev&namespaceShowName=开发环境2&namespaceDesc=只用于开发2'

示例返回

true

删除命名空间

请求类型

DELETE

请求路径

/nacos/v1/console/namespaces

请求参数

名称	类型	是否必选	描述
namespaceId	字符串	是	命名空间ID

错误编码

错误代码	描述	语义
400	Bad Request	客户端请求中的语法错误
403	Forbidden	没有权限
404	Not Found	无法找到资源
500	Internal Server Error	服务器内部错误
200	OK	正常

示例请求

curl -X DELETE 'http://localhost:8848/nacos/v1/console/namespaces' -d 'namespaceId=dev'

示例返回

true

Open API 指南

配置管理​

获取配置​

描述​

请求类型​

请求URL​

请求参数​

返回参数​

错误编码​

示例​

监听配置​

描述​

请求类型​

请求URL​

请求参数​

Header 参数​

参数说明​

返回参数​

错误编码​

示例​

发布配置​

描述​

请求类型​

请求 URL​

请求参数​

返回参数​

错误编码​

示例​

删除配置​

描述​

请求类型​

请求 URL​

请求参数​

返回参数​

错误编码​

示例​

查询历史版本​

描述​

请求类型​

请求 URL​

请求参数​

错误编码​

示例​

查询历史版本详情​

描述​

请求类型​

请求 URL​

请求参数​

错误编码​

示例​

查询配置上一版本信息​

描述​

请求类型​

请求 URL​

请求参数​

错误编码​

示例​

服务发现​

注册实例​

描述​

请求类型​

请求路径​

请求参数​

错误编码​

示例请求​

示例返回​

注销实例​

描述​

请求类型​

请求路径​

请求参数​

错误编码​

示例请求​

示例返回​

修改实例​

描述​

请求类型​

请求路径​

请求参数​

错误编码​

配置管理

获取配置

描述

请求类型

请求URL

请求参数

返回参数

错误编码

示例

监听配置

描述

请求类型

请求URL

请求参数

Header 参数

参数说明

返回参数

错误编码

示例

发布配置

描述

请求类型

请求 URL

请求参数

返回参数

错误编码

示例

删除配置

描述

请求类型

请求 URL

请求参数

返回参数

错误编码

示例

查询历史版本

描述

请求类型

请求 URL

请求参数

错误编码

示例

查询历史版本详情

描述

请求类型

请求 URL

请求参数

错误编码

示例

查询配置上一版本信息

描述

请求类型

请求 URL

请求参数

错误编码

示例

服务发现

注册实例

描述

请求类型

请求路径

请求参数

错误编码

示例请求

示例返回

注销实例

描述

请求类型

请求路径

请求参数

错误编码

示例请求

示例返回

修改实例

描述

请求类型

请求路径

请求参数

错误编码

示例请求