侧边栏壁纸
博主头像
码森林博主等级

一起走进码森林，享受编程的乐趣，发现科技的魅力，创造智能的未来!

  • 累计撰写 146 篇文章
  • 累计创建 74 个标签
  • 累计收到 4 条评论
标签搜索

目 录CONTENT

文章目录
微服务

Nacos（5）：Open API

码森林
码森林
2022-01-19 / 0 评论 / 0 点赞 / 650 阅读 / 15,273 字 / 正在检测是否收录...
温馨提示：
本文最后更新于 2022-01-19，若内容或图片失效，请留言反馈。部分素材来自网络，若不小心影响到您的利益，请联系我们删除。

本文主要介绍 Nacos 2.0.3 的 Open API。

配置管理

1、获取配置

描述

获取Nacos上的配置。

请求类型

GET

请求URL

/nacos/v1/cs/configs

请求参数

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

响应参数

参数类型描述
string配置值

请求示例

curl -X GET 'http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=spring-boot-nacos-config&group=DEFAULT_GROUP'

响应示例

useLocalCache=true

2、监听配置

描述

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

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

请求类型

POST

请求URL

/nacos/v1/cs/configs/listener

请求参数

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

Header参数

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

参数说明

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

响应参数

参数类型描述
string配置值

请求示例

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

# POST 请求体数据内容：
Listening-Configs=spring-boot-nacos-config^2DEFAULT_GROUP^2b54f63e58da12198344316a61a93add0^1

响应示例

如果配置变化

spring-boot-nacos-config^2DEFAULT_GROUP^25a822367cd73c79acc56da3c73fa07e^1

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

3、发布配置

描述

发布 Nacos 上的配置。

请求类型

POST

请求URL

/nacos/v1/cs/configs

请求参数

名称类型是否必须描述
tenantstring否租户信息，对应 Nacos 的命名空间ID字段
dataIdstring是配置 ID
groupstring是配置分组
contentstring是配置内容
typeString否配置类型

响应参数

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

请求示例

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

响应示例

true

4、删除配置

描述

删除 Nacos 上的配置。

请求类型

DELETE

请求URL

/nacos/v1/cs/configs

请求参数

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

响应参数

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

请求示例

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

响应示例

true

5、查询历史版本

描述

查询配置项历史版本。

请求类型

GET

请求URL

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

请求参数

名称类型是否必须描述
tenantstring否租户信息，对应 Naocs 的命名空间ID字段
dataIdstring是配置 ID
groupstring是配置分组
pageNointeger否当前页码
pageSizeinteger否分页条数(默认100条,最大为500)

请求示例

curl -X GET 'http://127.0.0.1:8848/nacos/v1/cs/history?search=accurate&dataId=spring-boot-nacos-config&group=DEFAULT_GROUP'

响应示例

{
    "totalCount": 3,
    "pageNumber": 1,
    "pagesAvailable": 1,
    "pageItems": [
        {
            "id": "42",
            "lastId": -1,
            "dataId": "spring-boot-nacos-config",
            "group": "DEFAULT_GROUP",
            "tenant": "",
            "appName": "",
            "md5": null,
            "content": null,
            "srcIp": "172.25.0.1",
            "srcUser": "",
            "opType": "U",
            "createdTime": "2021-08-31T11:48:22.000+08:00",
            "lastModifiedTime": "2021-08-31T11:48:22.000+08:00"
        },
        {
            "id": "41",
            "lastId": -1,
            "dataId": "spring-boot-nacos-config",
            "group": "DEFAULT_GROUP",
            "tenant": "",
            "appName": "",
            "md5": null,
            "content": null,
            "srcIp": "172.25.0.1",
            "srcUser": "",
            "opType": "U",
            "createdTime": "2021-08-31T11:40:53.000+08:00",
            "lastModifiedTime": "2021-08-31T11:40:53.000+08:00"
        },
        {
            "id": "40",
            "lastId": -1,
            "dataId": "spring-boot-nacos-config",
            "group": "DEFAULT_GROUP",
            "tenant": "",
            "appName": "",
            "md5": null,
            "content": null,
            "srcIp": "172.25.0.1",
            "srcUser": null,
            "opType": "I",
            "createdTime": "2021-08-31T10:27:52.000+08:00",
            "lastModifiedTime": "2021-08-31T10:27:53.000+08:00"
        }
    ]
}

6、查询历史版本详情

描述

查询配置项历史版本详情

请求类型

GET

请求URL

/nacos/v1/cs/history

请求参数

名称类型是否必须描述
nidInteger是配置项历史版本ID
tenantstring否租户信息，对应 Naocs 的命名空间ID字段 （2.0.3起）
dataIdstring是配置 ID （2.0.3起）
groupstring是配置分组 （2.0.3起）

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

请求示例

curl -X GET 'http://127.0.0.1:8848/nacos/v1/cs/history?nid=41&tenant=&dataId=spring-boot-nacos-config&group=DEFAULT_GROUP'

响应示例

{
    "id": "41",
    "lastId": -1,
    "dataId": "spring-boot-nacos-config",
    "group": "DEFAULT_GROUP",
    "tenant": "",
    "appName": "",
    "md5": "25a822367cd73c79acc56da3c73fa07e",
    "content": "useLocalCache=true",
    "srcIp": "172.25.0.1",
    "srcUser": "",
    "opType": "U",
    "createdTime": "2021-08-31T11:40:53.000+08:00",
    "lastModifiedTime": "2021-08-31T11:40:53.000+08:00"
}

7、查询配置上一版本信息

描述

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

请求类型

GET

请求 URL

/nacos/v1/cs/history/previous

请求参数

名称类型是否必须描述
idInteger是配置ID
tenantstring否租户信息，对应 Naocs 的命名空间ID字段 （2.0.3起）
dataIdstring是配置 ID （2.0.3起）
groupstring是配置分组 （2.0.3起）

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

请求示例

curl -X GET 'http://127.0.0.1:8848/nacos/v1/cs/history/previous?id=42&tenant=&dataId=spring-boot-nacos-config&group=DEFAULT_GROUP'

响应示例

{
    "id": "41",
    "lastId": -1,
    "dataId": "spring-boot-nacos-config",
    "group": "DEFAULT_GROUP",
    "tenant": "",
    "appName": "",
    "md5": "25a822367cd73c79acc56da3c73fa07e",
    "content": "useLocalCache=true",
    "srcIp": "172.25.0.1",
    "srcUser": "",
    "opType": "U",
    "createdTime": "2021-08-31T11:40:53.000+08:00",
    "lastModifiedTime": "2021-08-31T11:40:53.000+08:00"
}

服务发现

1、注册实例

描述

注册一个实例到服务。

请求类型

POST

请求URL

/nacos/v1/ns/instance

请求参数

名称类型是否必选描述
ip字符串是服务实例IP
portint是服务实例port
namespaceId字符串否命名空间ID
weightdouble否权重
enabledboolean否是否上线
healthyboolean否是否健康
metadata字符串否扩展信息
clusterName字符串否集群名
serviceName字符串是服务名
groupName字符串否分组名
ephemeralboolean否是否临时实例

请求示例

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

响应示例

ok

2、注销实例

描述

删除服务下的一个实例。

请求类型

DELETE

请求URL

/nacos/v1/ns/instance

请求参数

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

请求示例

curl -X DELETE 'http://127.0.0.1:8848/nacos/v1/ns/instance?serviceName=nacos.test.service&ip=127.0.0.1&port=8080&clusterName='

响应示例

ok

3、修改实例

描述

修改服务下的一个实例。

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

请求类型

PUT

请求URL

/nacos/v1/ns/instance

请求参数

名称类型是否必选描述
serviceName字符串是服务名
groupName字符串否分组名
ip字符串是服务实例IP
portint是服务实例port
clusterName字符串否集群名称
namespaceId字符串否命名空间ID
weightdouble否权重
metadataJSON否扩展信息
enabledboolean否是否打开流量
ephemeralboolean否是否临时实例

请求示例

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

响应示例

ok

4、查询实例列表

描述

查询服务下的实例列表

请求类型

GET

请求URL

/nacos/v1/ns/instance/list

请求参数

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

请求示例

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

响应示例

{
    "name": "DEFAULT_GROUP@@nacos.test.service",
    "groupName": "DEFAULT_GROUP",
    "clusters": "",
    "cacheMillis": 10000,
    "hosts": [],
    "lastRefTime": 1630395849928,
    "checksum": "",
    "allIPs": false,
    "reachProtectionThreshold": false,
    "valid": true
}

5、发送实例心跳

描述

发送某个实例的心跳

请求类型

PUT

请求URL

/nacos/v1/ns/instance/beat

请求参数

名称类型是否必选描述
serviceName字符串是服务名
groupName字符串否分组名
ephemeralboolean否是否临时实例
beatJSON格式字符串是实例心跳内容

请求示例

curl -X PUT 'http://127.0.0.1:8848/nacos/v1/ns/instance/beat?serviceName=nacos.test.service&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%22nacos.test.service%22%2C%22weight%22%3A1%7D'

响应示例

{
    "clientBeatInterval": 5000,
    "code": 10200, # 10200源码中代表ok
    "lightBeatEnabled": true
}

6、创建服务

描述

创建一个服务

请求类型

POST

请求URL

/nacos/v1/ns/service

请求参数

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

请求示例

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

响应示例

ok

7、删除服务

描述

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

请求类型

DELETE

请求URL

/nacos/v1/ns/service

请求参数

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

请求示例

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

响应示例

ok

8、修改服务

描述

更新一个服务

请求类型

PUT

请求URL

/nacos/v1/ns/service

请求参数

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

请求示例

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

响应示例

ok

9、查询服务

描述

查询一个服务

请求类型

GET

请求URL

/nacos/v1/ns/service

请求参数

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

请求示例

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

响应示例

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

10、查询服务列表

描述

查询服务列表

请求类型

GET

请求URL

/nacos/v1/ns/service/list

请求参数

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

请求示例

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

响应示例

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

11、查询系统开关

描述

查询系统开关

请求类型

GET

请求URL

/nacos/v1/ns/operator/switches

请求参数

无

请求示例

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

响应示例

{
    "masters": null,
    "adWeightMap": {},
    "defaultPushCacheMillis": 10000,
    "clientBeatInterval": 5000,
    "defaultCacheMillis": 3000,
    "distroThreshold": 0.7,
    "healthCheckEnabled": true,
    "autoChangeHealthCheckEnabled": 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": 2000,
    "serviceStatusSynchronizationPeriodMillis": 5000,
    "disableAddIP": false,
    "sendBeatOnly": false,
    "lightBeatEnabled": true,
    "doubleWriteEnabled": true,
    "limitedUrlMap": {},
    "distroServerExpiredMillis": 10000,
    "pushGoVersion": "0.1.0",
    "pushJavaVersion": "0.1.0",
    "pushPythonVersion": "0.4.3",
    "pushCVersion": "1.0.12",
    "pushCSharpVersion": "0.9.0",
    "enableAuthentication": false,
    "overriddenServerStatus": null,
    "defaultInstanceEphemeral": true,
    "healthCheckWhiteList": [],
    "checksum": null,
    "name": "00-00---000-NACOS_SWITCH_DOMAIN-000---00-00"
}

12、修改系统开关

描述

修改系统开关

请求类型

PUT

请求URL

/nacos/v1/ns/operator/switches

请求参数

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

请求示例

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

响应示例

ok

13、查看系统当前数据指标

描述

查看系统当前数据指标

请求类型

GET

请求URL

/nacos/v1/ns/operator/metrics

请求参数

无

请求示例

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

响应示例

{
    "status": "UP"
}

14、查看当前集群Server列表

描述

查看当前集群Server列表

请求类型

GET

请求URL

/nacos/v1/ns/operator/servers

请求参数

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

请求示例

curl -X GET 'http://127.0.0.1:8848/nacos/v1/ns/operator/servers?healthy=false'

响应示例

{
    "servers": [
        {
            "ip": "1095a768f287",
            "port": 8848,
            "state": "UP",
            "extendInfo": {
                "lastRefreshTime": 1630373352190,
                "raftMetaData": {
                    "metaDataMap": {
                        "naming_instance_metadata": {
                            "leader": "1095a768f287:7848",
                            "raftGroupMember": [
                                "1095a768f287:7848"
                            ],
                            "term": 2
                        },
                        "naming_persistent_service_v2": {
                            "leader": "1095a768f287:7848",
                            "raftGroupMember": [
                                "1095a768f287:7848"
                            ],
                            "term": 2
                        },
                        "naming_service_metadata": {
                            "raftGroupMember": [
                                "1095a768f287:7848"
                            ]
                        }
                    }
                },
                "raftPort": "7848",
                "version": "2.0.3"
            },
            "address": "1095a768f287:8848",
            "failAccessCnt": 0,
            "abilities": {
                "remoteAbility": {
                    "supportRemoteConnection": true
                },
                "configAbility": {
                    "supportRemoteMetrics": false
                },
                "namingAbility": {
                    "supportJraft": true
                }
            }
        }
    ]
}

15、更新实例的健康状态

描述

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

请求类型

PUT

请求URL

/nacos/v1/ns/health/instance

请求参数

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

请求示例

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

响应示例

ok

命名空间

1、查询命名空间列表

描述

查询命名空间列表

请求类型

GET

请求URL

/nacos/v1/console/namespaces

请求参数

无

请求示例

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

响应示例

{
    "code": 200,
    "message": null,
    "data": [
        {
            "namespace": "",
            "namespaceShowName": "public",
            "quota": 200,
            "configCount": 8,
            "type": 0
        },
        {
            "namespace": "dev",
            "namespaceShowName": "dev",
            "quota": 200,
            "configCount": 1,
            "type": 2
        },
        {
            "namespace": "prod",
            "namespaceShowName": "prod",
            "quota": 200,
            "configCount": 0,
            "type": 2
        },
        {
            "namespace": "test",
            "namespaceShowName": "test",
            "quota": 200,
            "configCount": 0,
            "type": 2
        }
    ]
}

2、创建命名空间

描述

创建命名空间

请求类型

POST

请求URL

/nacos/v1/console/namespaces

请求参数

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

请求示例

curl -X POST 'http://127.0.0.1:8848/nacos/v1/console/namespaces?customNamespaceId=qa&namespaceName=qa&namespaceDesc=ceshi'

响应示例

true

3、修改命名空间

描述

修改命名空间

请求类型

PUT

请求URL

/nacos/v1/console/namespaces

请求参数

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

请求示例

curl -X PUT 'http://127.0.0.1:8848/nacos/v1/console/namespaces?namespaceId=qa&namespaceName=测试环境&namespaceDesc=测试环境'

响应示例

true

4、删除命名空间

描述

删除命名空间

请求类型

DELETE

请求URL

/nacos/v1/console/namespaces

请求参数

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

请求示例

curl -X DELETE 'http://127.0.0.1:8848/nacos/v1/console/namespaces?namespaceId=qa'

响应示例

true

错误编码

错误代码描述语义
400Bad Request客户端请求中的语法错误
403Forbidden没有权限
404Not Found无法找到资源
500Internal Server Error服务器内部错误
200OK正常
0
Nacos
版权归属： 码森林
本文链接： https://www.masenlin.com/archives/nacos5openapi
许可协议： 本文使用《署名-非商业性使用-相同方式共享 4.0 国际 (CC BY-NC-SA 4.0)》协议授权

评论区