Open API 指南

• 配置管理

  • 获取配置
  • 监听配置
  • 发布配置
  • 删除配置
  • 查询历史版本
  • 查询历史版本详情
  • 查询配置上一版本信息

• 服务发现

  • 注册实例
  • 注销实例
  • 修改实例
  • 查询实例列表
  • 查询实例详情
  • 发送实例心跳
  • 创建服务
  • 删除服务
  • 修改服务
  • 查询服务
  • 查询服务列表
  • 查询系统开关
  • 修改系统开关
  • 查看系统当前数据指标
  • 查看当前集群Server列表
  • 查看当前集群leader
  • 更新实例的健康状态
  • 批量更新实例元数据(Beta)
  • 批量删除实例元数据(Beta)

• 命名空间

  • 查询命名空间列表
  • 创建命名空间
  • 修改命名空间
  • 删除命名空间

配置管理

获取配置

描述

获取Nacos上的配置。

请求类型

GET

请求URL

/nacos/v1/cs/configs

请求参数

返回参数

错误编码

示例

• 请求示例

  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

请求参数

Header 参数

参数说明

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

返回参数

错误编码

示例

• 请求示例

http://serverIp:8848/nacos/v1/cs/configs/listener
POST 请求体数据内容：
Listening-Configs=dataId^2group^2contentMD5^2tenant^1

• 返回示例

如果配置变化
dataId^2group^2tenant^1
如果配置无变化：会返回空串

发布配置

描述

发布 Nacos 上的配置。

请求类型

POST

请求 URL

/nacos/v1/cs/configs

请求参数

返回参数

错误编码

示例

• 请求示例

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

请求参数

返回参数

错误编码

示例

• 请求示例

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

请求参数

错误编码

示例

• 请求示例

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

请求参数

错误编码

示例

• 请求示例

curl -X GET 'http://127.0.0.1:8848/nacos/v1/cs/history?nid=203'

• 返回示例

{
  "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

请求参数

错误编码

示例

• 请求示例

curl -X GET 'http://127.0.0.1:8848/nacos/v1/cs/history/previous?id=309135486247505920'

• 返回示例

{
  "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

请求参数

错误编码

示例请求

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'

示例返回

ok

注销实例

描述

删除服务下的一个实例。

请求类型

DELETE

请求路径

/nacos/v1/ns/instance

请求参数

错误编码

示例请求

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'

示例返回

ok

修改实例

描述

修改服务下的一个实例。

请求类型

PUT

请求路径

/nacos/v1/ns/instance

请求参数

错误编码

示例请求

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={}'

示例返回

ok

查询实例列表

描述

查询服务下的实例列表

请求类型

GET

请求路径

/nacos/v1/ns/instance/list

请求参数

错误编码

示例请求

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

示例返回

{
    "dom": "nacos.test.1",
    "cacheMillis": 1000,
    "useSpecifiedURL": false,
    "hosts": [{
        "valid": true,
        "marked": false,
        "instanceId": "10.10.10.10-8888-DEFAULT-nacos.test.1",
        "port": 8888,
        "ip": "10.10.10.10",
        "weight": 1.0,
        "metadata": {}
    }],
    "checksum": "3bbcf6dd1175203a8afdade0e77a27cd1528787794594",
    "lastRefTime": 1528787794594,
    "env": "",
    "clusters": ""
}

查询实例详情

描述

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

请求类型

GET

请求路径

/nacos/v1/ns/instance

请求参数

错误编码

示例请求

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

请求参数

错误编码

示例请求

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

请求参数

错误编码

示例请求

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

请求参数

错误编码

示例请求

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

示例返回

ok

修改服务

描述

更新一个服务

请求类型

PUT

请求路径

/nacos/v1/ns/service

请求参数

错误编码

示例请求

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

请求参数

错误编码

示例请求

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

请求参数

错误编码

示例请求

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

请求参数

错误编码

示例请求

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

请求参数

错误编码

示例请求

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

请求参数

错误编码

示例请求

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

请求参数

错误编码

示例请求

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

请求参数

错误编码

示例请求

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

请求参数

错误编码

示例请求

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'

示例返回

ok

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

描述

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

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

请求类型

PUT

请求路径

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

请求参数

错误编码

参数说明

• 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

请求参数

错误编码

参数说明

• 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

请求参数

无

错误编码

示例请求

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

请求参数

错误编码

示例请求

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

示例返回

true

修改命名空间

请求类型

PUT

请求路径

/nacos/v1/console/namespaces

请求参数

错误编码

示例请求

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

示例返回

true

删除命名空间

请求类型

DELETE

请求路径

/nacos/v1/console/namespaces

请求参数

错误编码

示例请求

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

示例返回

true