What is Nacos
+ +Nacos dedicated to help you find, micro configuration and management services. Nacos provides a set of simple and easy to use feature set, help you quickly realize dynamic service discovery, service configuration, service metadata, and traffic management. Details you can refer to [Nacos website](../../what-is-nacos.md). + +Nacos how to support more than the environment
+ +In daily use are often need different environment, such as daily, pretest, online environment, if it is a logical isolation, can use the namespace Nacos support namespace to support more environmental isolation, can create multiple namespaces in Nacos console. If you need physical isolation, will deploy more sets of Nacos environment. + +Nacos whether production is available
+ +Nacos in January 2019 issued a Pre - GA version, to support the security isolation, monitoring and service migration on the last mile of production, in a more stable support the user's production environment. Details you can refer to [Nacos release v0.8.0 Pre - GA version, the safe and stable production](https://www.oschina.net/news/104019/nacos-0-8-0-pre-ga). + +Nacos dependent
+ +In stand-alone mode, Nacos without any rely on, in cluster mode, Nacos rely on Mysql storage, details you can refer to [Nacos deployment](../admin/deployment.md). + +Nacos using open source licenses
+ +Nacos using [Apache 2.0](https://github.com/alibaba/nacos/blob/master/LICENSE). + +## Nacos operational questions +Nacos standalone deployment
+ +You can refer to the manual Nacos website deployment [quick start](../../quickstart/quick-start.mdx). + +Nacos standalone deployment using Mysql
+ +Nacos stand-alone mode defaults to using the embedded database as the storage engine, if you want to change your mysql installation, you can refer to [website document](../admin/deployment.md). + +Nacos production deployment
+ +Production environment using Nacos in order to achieve high availability cannot use stand-alone mode, need to build Nacos cluster, specific details can refer to [the manual cluster deployment](../admin/cluster-mode-quick-start.md). + +Nacos Docker deployment
+ +In addition to using compressed package deployment Nacos, Nacos also provides a corresponding Docker image, when Nacos release new versions, Nacos will release the corresponding image version supports Docker deployment.Specific details you can refer to [Nacos Docker](../../quickstart/quick-start-docker.mdx). + +How to deploy in k8s Nacos
+ +In production deployment Nacos cluster, if for Nacos expansion operation, need to manually change the cluster IP file, start a new Nacos service.In order to automate operations, k8s Nacos and combined use of StatefulSets provides automatic operations plan, to dynamic scalability Nacos capacity, specific details reference [Kubernetes Nacos](https://github.com/nacos-group/nacos-k8s/blob/master/README.md). + +How to monitor Nacos
+ +Nacos0.8 version provides the Metrics data exposed ability, can pass the Metrics data to monitor the running status of Nacos, the content of the details you can refer to [Nacos monitor](../admin/monitor-guide.md). + +Nacos cannot start in Docker, always print Nacos is starting...
+ +The reason may be due to insufficient memory in the Docker environment, causing other services to fail to start normally, and finally causing the service to report an error and keep restarting. You can try to solve it by increasing the Docker memory limit. + +## Nacos used questions +Zookeeper service can be migrated to Nacos?
+ +Can through the Nacos - Sync moved the Zookeeper service and Nacos, can also be migrated from Nacos Zookeeper, specific details can be used as [Nacos Sync reference](https://github.com/paderlol/nacos-sync-example). + +Nacos support multiple configuration files
+ +Nacos through Spring Cloud Alibaba Nacos Config support multiple configuration files, configuration can be stored in a separate configuration file.The associated [issue](https://github.com/alibaba/nacos/issues/320), details refer to the document [Spring Cloud Alibaba Nacos Config](https://github.com/spring-cloud-incubator/spring-cloud-alibaba/wiki/Nacos-config). + +Nacos support Dubbo
+ +Nacos version 0.6 and Dubbo integration, support the use of Nacos as registry, related [issue](https://github.com/alibaba/nacos/issues/390), details refer to the document [Nacos and Dubbo fusion become registry](../../ecology/use-nacos-with-dubbo.md). + +Nacos support Spring system
+ +Nacos perfect supports the Sping technology stack, details refer to the document [Nacos Spring](../../ecology/use-nacos-with-spring.md)、[Nacos Spring Boot](../../ecology/use-nacos-with-spring-boot.md)、[Spring Cloud](../../ecology/use-nacos-with-spring-cloud.md). + +Don't use Nacos SDK how to access the Nacos
+ +Nacos network interaction is implemented based on Http protocol, provides the [Open-API](./open-api.md) can easily achieve Nacos access. + +Nacos support for multiple languages
+ +Nacos currently only supports Java, support for other languages are being developed, also need your support to build together. + +Nacos 0.8 version logon failure
+ +Nacos version 0.8 when using its and no `JAVA_HOME` environment variable, Nacos can launch successful, because `yum install` installed its the Java command to register a beneath `/bin` directory, and so can cause abnormal `SignatureException`.This problem has been repair, version 0.9 release, the specific details can refer to the [issue](https://github.com/alibaba/nacos/issues/711). + +Server error java.lang.IllegalStateException: unable to find local peer: 127.0.0.1:8848
+ +This problem because Nacos get native IP, don't get to the correct external IP. The need to guarantee the `InetAddress.getLocalHost().getHostAddress()` or the result of the `hostname -i` was with the cluster. The conf configuration of IP is the same. + +Nacos configuration for encryption
+ +Nacos plan in 1.X version's ability to provide encryption, currently does not support encryption, can only rely on the SDK prepared encryption endures Nacos again. + +Nacos at 401 error
+ +Nacos server error, check the server logs, refer to the [issue](https://github.com/alibaba/nacos/issues/816). + +Nacos weight not to take effect
+ +Nacos console editors weights, at present from SpringCloud client and Dubbo client didn't get through, so can't take effect. For SpringCloud client application can realize the load balancer Ribbon for weighting filter. + +Nacos how to enlarge shrinks capacity
+ +Currently supported modify the `cluster.conf` file in a way that expanding capacity, after the change without restart, the Server will automatically refresh the new content to the file. + +Nacos client modify the log level
+ +Configuration - D parameters `com.alibaba.nacos.naming.log.level` set naming the client log level, such as setting for the error:`-Dcom.alibaba.nacos.naming.log.level=error` Similarly, - D parameters `com.alibaba.nacos.config.log.level` is used to set the config client log level. + +Nacos and Zipkin integration Service not found error
+ +Configuration `spring-cloud-seluth` parameters: `spring.zipkin.discovery-client-enabled=false`. + +If there is still a `Service not found` error, is recommended to use the open-api will Zipkin-server instance is registered as a permanent Service: + +`curl -X POST 'http://127.0.0.1:8848/nacos/v1/ns/instance?port=9411&healthy=true&ip=127.0.0.1&weight=1.0&serviceName=zipkin-server&ephemeral=false&namespaceId=public'` + +Then, went to nacos console, find a service called `zipkin-server` service, find the cluster configuration, set the health examination mode to `TCP`, port number of `9411` (zipkin-server port). + +Why service registration is successful, the console can't see
+ +This problem appeared in cluster mode, in the use of nacos cluster pattern, ensure that all of the machine time is consistent, can appear otherwise unable to synchronize data. + +`com.alibaba.nacos.consistency.entity` can't be found in source codes
+ +This package will be auto-generated by `protobuf`, so if you want to read source code or do some develop, you can use `mvn compile` to generate them. If you are using IDEA, you can also use IDEA's protobuf plugin. + +java.lang.IllegalArgumentException: the length of secret key must great than or equal 32 bytes...
+java.lang.IllegalArgumentException: The specified key byte array is x bits which is not secure enough for any JWT HMAC-SHA algorithm.
+ +The default authentication plugin needs a secret key to generate an access token, and the secret key format needs to have a length greater than 32. If the length of `secret.key` after BASE64 decryption is less than 32, this error will occur during the startup process. +You can set the correct `secret.key` in `application.properties`, see [User Guide - Authorization Authentication](./auth.md) for details. + +Error：Empty identity, Please set `nacos.core.auth.server.identity.key` and `nacos.core.auth.server.identity.value`
+ +Since 2.2.1, the default value of `nacos.core.auth.server.identity.key` and `nacos.core.auth.server.identity.value` has been removed and will be checked during server starting. +If the auth feature enabled but no `nacos.core.auth.server.identity.key` and `nacos.core.auth.server.identity.value` configured, nacos server will stop bootstrap and hint with the error message. +Please see [User Guide - Authorization Authentication](./auth.md) to configure them and restart. + + +## Nacos principle questions diff --git a/src/content/docs/v3.0/en/guide/user/open-api.md b/src/content/docs/v3.0/en/guide/user/open-api.md new file mode 100644 index 00000000000..70dff4f93b6 --- /dev/null +++ b/src/content/docs/v3.0/en/guide/user/open-api.md @@ -0,0 +1,2807 @@ +--- +title: Open API Guide +keywords: [Open API,Guide] +description: Open API Guide +sidebar: + order: 3 +--- + +# Open API Guide + +Nacos 2.X is compatible with Nacos 1.X OpenAPI, please refer to the document [Nacos1.X OpenAPI](https://nacos.io/en/docs/v1/open-api/). + +> Attension: OpenAPIs which do not specify a supported version, will be supported since 2.2.0. + +- Documentation Conventions + - [API unified return body format](#0.1) + - [API error code summary](#0.2) + +- Configuration Management + - [Get configuration](#1.1) + - [Publish configuration](#1.2) + - [Delete configuration](#1.3) + - [Query list of history configuration](#1.4) + - [Query the history details of the configuration](#1.5) + - [Query the previous version of the configuration](#1.6) + - [Query the list of configurations under the specified namespace](#1.7) + +- Service Discovery + - [Register instance](#2.1) + - [Deregister instance](#2.2) + - [Modify instance](#2.3) + - [Query instance detail](#2.4) + - [Query instances](#2.5) + - [Batch update instance metadata(Beta)](#2.6) + - [Batch delete instance metadata(Beta)](#2.7) + - [Create service](#2.8) + - [Delete service](#2.9) + - [Update service](#2.10) + - [Query service](#2.11) + - [Query service list](#2.12) + - [Query system switches](#2.13) + - [Update system switch](#2.14) + - [Query system metrics](#2.15) + - [Update instance health status](#2.16) + - [Query client list (new)](#2.17) + - [Query client (new)](#2.18) + - [Query the registration information of the client (new)](#2.19) + - [Query the subscription information of the client (new)](#2.20) + - [Query the client that registered the specified service (new)](#2.21) + - [Query the information of clients subscribed to the specified service (new)](#2.22) + +- Namespace + - [Query namespaces](#3.1) + - [Query namespace](#3.2) + - [Create namespace](#3.3) + - [Update namespace](#3.4) + - [Delete namespace](#3.5) + +- Cluster + - [Query the current node](#4.1) + - [Query the list of cluster nodes](#4.2) + - [Query the current node health status](#4.3) + - [Switch addressing modes](#4.4) +- Connection Load Management + - [Query the List of Current Node Client Connections](#5.1) + - [Reload the Number of Current Node Client Connections](#5.2) + - [Intelligently Balance the Number of Client Connections in the Cluster](#5.3) + - [Reset a Specific Client Connection](#5.4) + - [Get SDK Metrics for the Cluster](#5.5) + + +## Documentation Conventions + +API unified return body format
+ +In Nacos 2.X, the response to all interface requests is a return body of type `json`, which has the same format + +```json +{ + "code": 0, + "message": "success", + "data": {} +} +``` + +The meanings of the fields in the return body are shown in the following table + +| name | type | description | +|:---------:|:--------:|------------------------------------------------------------------------------------------------------| +| `code ` | `int` | Error code，`0` means the execution succeeded, non-`0` means the execution failed in one of the cases | +| `message` | `String` | Error code prompt message, execution success as "`success`" | +| `data` | `Any` | Return data, detailed error message in case of execution failure | + +> Since the `code` field is the same as the message field in case of successful execution, only the `data` field of the returned data will be introduced in the subsequent introduction of the returned results of the interface + +API error code summary
+ +The error codes and corresponding prompt messages in the return body of the API interface are summarized in the following table + +| Error Code | message | meaning | +|------------|------------------------------|--------------------------------------------------| +| `0` | `success` | Successful execution | +| `10000` | `parameter missing` | Missing parameters | +| `10001` | `access denied` | Access Denied | +| `10002` | `data access error` | Data access error | +| `20001` | `'tenant' parameter error` | `tenant` parameter error | +| `20002` | `parameter validate error` | Parameter validation error | +| `20003` | `MediaType Error` | `MediaType` error for HTTP requests | +| `20004` | `resource not found` | Resource not found | +| `20005` | `resource conflict` | Resource access conflicts | +| `20006` | `config listener is null` | Listening configuration is empty | +| `20007` | `config listener error` | Listening configuration error | +| `20008` | `invalid dataId` | Invalid `dataId` (authentication failure) | +| `20009` | `parameter mismatch` | Request parameter mismatch | +| `21000` | `service name error` | `serviceName` error | +| `21001` | `weight error` | `weight` error | +| `21002` | `instance metadata error` | Instance `metadata` error | +| `21003` | `instance not found` | `instance` not found | +| `21004` | `instance error` | `instance` error | +| `21005` | `service metadata error` | Service `metadata` error | +| `21006` | `selector error` | `selector` error | +| `21007` | `service already exist` | Service already exists | +| `21008` | `service not exist` | Service does not exist | +| `21009` | `service delete failure` | Service instance exists, service deletion failed | +| `21010` | `healthy param miss` | `healthy` parameter miss | +| `21011` | `health check still running` | Health check is still running | +| `22000` | `illegal namespace` | `namespace` is illegal | +| `22001` | `namespace not exist` | Namespace does not exist | +| `22002` | `namespace already exist` | Namespace already exists | +| `23000` | `illegal state` | `state` is illegal | +| `23001` | `node info error` | Node information error | +| `23002` | `node down failure` | Node offline operation error | +| ... | ... | ... | +| 30000 | `server error` | Other internal errors | + +## Configuration Management + +Get configuration
+ +### Description + +Get the specified configuration + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/cs/config` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|----------|----------|--------------------------------| +| `namespaceId` | `String` | N | Namespace, default is `public` | +| `group` | `String` | **Y** | Config group name | +| `dataId` | `String` | **Y** | Config name | +| `tag` | `String` | N | Tag | + +### Return Data + +| Parameter | Type | Description | +|-----------|----------|----------------| +| `data` | `String` | Config content | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/config?dataId=nacos.example&group=DEFAULT_GROUP&namespaceId=public' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": "contentTest" + } + ``` + +Publish configuration
+ +### Description + +Publish the specified configuration + +> Update the configuration when it already exists + +### Request Method + +`POST` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/cs/config` + +### Request Body + +| Parameter | Type | Required | Description | +|---------------|----------|----------|------------------------------------------------------| +| `namespaceId` | `String` | N | Namespace, default is `public` | +| `group` | `String` | **Y** | Config group | +| `dataId` | `String` | **Y** | Config name | +| `content` | `String` | **Y** | Config content | +| `tag` | `String` | N | Tag | +| `appName` | `String` | N | Application name | +| `srcUser` | `String` | N | Source user | +| `configTags` | `String` | N | Configure Tag list, can be multiple, comma separated | +| `desc` | `String` | N | Config description | +| `use` | `String` | N | - | +| `effect` | `String` | N | - | +| `type` | `String` | N | Config type | +| `schema` | `String` | N | - | + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -d 'dataId=nacos.example' \ + -d 'group=DEFAULT_GROUP' \ + -d 'namespaceId=public' \ + -d 'content=contentTest' \ + -X POST 'http://127.0.0.1:8848/nacos/v2/cs/config' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +Delete configuration
+ +### Description + +Delete the specified configuration + +### Request Method + +`DELETE` + +### Request URL + +`/nacos/v2/cs/config` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|----------|----------|--------------------------------| +| `namespaceId` | `String` | N | Namespace, default is `public` | +| `group` | `String` | **Y** | Config group name | +| `dataId` | `String` | **Y** | Config name | +| `tag` | `String` | N | Tag | + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -X DELETE 'http://127.0.0.1:8848/nacos/v2/cs/config?dataId=nacos.example&group=DEFAULT_GROUP&namespaceId=public' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +Query list of history configuration
+ +### Description + +Get a list of historical versions of the specified configuration + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/cs/history/list` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|----------|----------|------------------------------------------------------------| +| `namespaceId` | `String` | N | Namespace, default is `public` | +| `group` | `String` | **Y** | Config group name | +| `dataId` | `String` | **Y** | Config name | +| `pageNo` | `int` | N | Current page, default is `1` | +| `pageSize` | `int` | N | Number of page entries, default is `100`, maximum is `500` | + +### Return Data + +| Parameter | Type | Description | +|-----------------------|------------|--------------------------------------------------------------------------------| +| `data` | `Object` | Paging Search Results | +| `data.totalCount` | `int` | Total | +| `data.pageNumber` | `int` | Current page | +| `data.pagesAvailable` | `int` | Total number of pages | +| `data.pageItems` | `Object[]` | List of historical configuration items, refer to [Historical configuration item](#ConfigHistoryInfo) | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history/list?dataId=nacos.example&group=com.alibaba.nacos&namespaceId=' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": { + "totalCount": 1, + "pageNumber": 1, + "pagesAvailable": 1, + "pageItems": [ + { + "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" + } + ] + } + } + ``` + +Query the history details of the configuration
+ +### Description + +Get the historical configuration of the specified version + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/cs/history` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|----------|----------|--------------------------------| +| `namespaceId` | `String` | N | Namespace, default is `public` | +| `group` | `String` | **Y** | Config group name | +| `dataId` | `String` | **Y** | Config name | +| `nid` | `long` | **Y** | History configuration id | + +Return Data
+ +| Parameter | Type | Description | +|-------------------------|----------|---------------------------------| +| `data` | `Object` | Historical configuration item | +| `data.id` | `String` | Config `id` | +| `data.lastId` | `int` | | +| `data.dataId` | `String` | Config name | +| `data.group` | `String` | config group | +| `data.tenant` | `String` | Tenant (namespace) | +| `data.appName` | `String` | Application name | +| `data.md5` | `String` | The md5 value of config content | +| `data.content` | `String` | Config content | +| `data.srcIp` | `String` | Source ip | +| `data.srcUser` | `String` | Source user | +| `data.opType` | `String` | Operator type | +| `data.createdTime` | `String` | Creation time | +| `data.lastModifiedTime` | `String` | Last modified time | +| `data.encryptedDataKey` | `String` | | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history?dataId=nacos.example&group=com.alibaba.nacos&namespaceId=&nid=203' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": { + "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" + } + } + ``` + +Query the previous version of the configuration
+ +### Description + +Get the previous version of the specified configuration + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/cs/history/previous` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|----------|----------|--------------------------------| +| `namespaceId` | `String` | N | Namespace, default is `public` | +| `group` | `String` | **Y** | Config group name | +| `dataId` | `String` | **Y** | Config name | +| `id` | `long` | **Y** | config id | + +Return Data
+ +| Parameter | Type | Description | +|-----------|----------|---------------------------------------------------------------------------------------------| +| `data` | `Object` | Historical configuration item, refer to [Historical configuration item](#ConfigHistoryInfo) | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history/previous?id=309135486247505920&dataId=nacos.example&group=com.alibaba.nacos&namespaceId=' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": { + "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" + } + } + ``` + +Query the list of configurations under the specified namespace
+ +### Description + +Get the list of configurations under the specified namespace + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/cs/history/configs` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|----------|----------|-------------| +| `namespaceId` | `String` | **Y** | Namespace | + +### Return Data + +| Parameter | Type | Description | +|-------------------------|------------|---------------------------------| +| `data` | `Object[]` | Config list | +| `data.id` | `String` | config `id` | +| `data.dataId` | `String` | Config name | +| `data.group` | `String` | Config group | +| `data.content` | `String` | Config content | +| `data.md5` | `String` | the md5 value of config content | +| `data.encryptedDataKey` | `String` | | +| `data.tenant` | `String` | Tenant (namespace) | +| `data.appName` | `String` | Application name | +| `data.type` | `String` | config file Type | +| `data.lastModified` | `long` | Last modified time | + +> Only the `dataId`, `group`, `tenant`, `appName`, `type` fields are valid for the configuration information in the returned data, the other fields are default values + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history/configs?namespaceId=' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "id": "0", + "dataId": "nacos.example", + "group": "com.alibaba.nacos", + "content": null, + "md5": null, + "encryptedDataKey": null, + "tenant": "", + "appName": "", + "type": "yaml", + "lastModified": 0 + } + ] + } + ``` + +## Service Discovery + +Register instance
+ +### Description + +Register an instance + +### Request Method + +`POST` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/ns/instance` + +### Request Body + +| Parameter | Type | Required | Description | +|---------------|----------------------|----------|-----------------------------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is `DEFAULT_GROUP` | +| `serviceName` | `String` | **Y** | Service name | +| `ip` | `String` | **Y** | `IP` address | +| `port` | `int` | **Y** | Port number | +| `clusterName` | `String` | N | Cluster name, default is `DEFAULT` | +| `healthy` | `boolean` | N | Whether to find only healthy instances, default is `true` | +| `weight` | `double` | N | Instance weights, default is `1.0` | +| `enabled` | `boolean` | N | Enable or not, default is `true` | +| `metadata` | `JSON format String` | N | Instance metadata | +| `ephemeral` | `boolean` | N | Whether it is a temporary instance | + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -d 'serviceName=test_service' \ + -d 'ip=127.0.0.1' \ + -d 'port=8090' \ + -d 'weight=0.9' \ + -d 'ephemeral=true' \ + -X POST 'http://127.0.0.1:8848/nacos/v2/ns/instance' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +Deregister instance
+ +### Description + +Deregister a specified instance + +### Request Method + +`DELETE` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/ns/instance` + +### Request Body + +| Parameter | Type | Required | Description | +|---------------|----------------------|----------|-----------------------------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is `DEFAULT_GROUP` | +| `serviceName` | `String` | **Y** | Service name | +| `ip` | `String` | **Y** | `IP` address | +| `port` | `int` | **Y** | Port number | +| `clusterName` | `String` | N | Cluster name, default is `DEFAULT` | +| `healthy` | `boolean` | N | Whether to find only healthy instances, default is `true` | +| `weight` | `double` | N | Instance weights, default is `1.0` | +| `enabled` | `boolean` | N | Enable or not, default is `true` | +| `metadata` | `JSON format String` | N | Instance metadata | +| `ephemeral` | `boolean` | N | Whether it is a temporary instance | + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -d 'serviceName=test_service' \ + -d 'ip=127.0.0.1' \ + -d 'port=8090' \ + -d 'weight=0.9' \ + -d 'ephemeral=true' \ + -X DELETE 'http://127.0.0.1:8848/nacos/v2/ns/instance' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +Modify instance
+ +### Description + +Modify instance information + +> The metadata updated through this interface has a higher priority and has the ability to remember. After the instance removed, it will still exist for a period of time. If the instance is re-registered during this period, the metadata will still be Effective. You can modify the memory time through `nacos.naming.clean.expired-metadata.expired-time` **and** `nacos.naming.clean.expired-metadata.interval` + +### Request Method + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/ns/instance` + +### Request Body + +| Parameter | Type | Required | Description | +|---------------|----------------------|----------|-----------------------------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is `DEFAULT_GROUP` | +| `serviceName` | `String` | **Y** | Service name | +| `ip` | `String` | **Y** | `IP` address | +| `port` | `int` | **Y** | Port number | +| `clusterName` | `String` | N | Cluster name, default is `DEFAULT` | +| `healthy` | `boolean` | N | Whether to find only healthy instances, default is `true` | +| `weight` | `double` | N | Instance weights, default is `1.0` | +| `enabled` | `boolean` | N | Enable or not, default is `true` | +| `metadata` | `JSON format String` | N | Instance metadata | +| `ephemeral` | `boolean` | N | Whether it is a temporary instance | + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -d 'serviceName=test_service' \ + -d 'ip=127.0.0.1' \ + -d 'port=8090' \ + -d 'weight=0.9' \ + -d 'ephemeral=true' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/instance' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +Query instance detail
+ +### Description + +Query the details of a specific instance + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/ns/instance` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|----------|----------|----------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is `DEFAULT_GROUP` | +| `serviceName` | `String` | **Y** | Service name | +| `clusterName` | `String` | N | Cluster name, default is `DEFAULT` | +| `ip` | `String` | **Y** | `IP` address | +| `port` | `int` | **Y** | Port number | + +### Return Data + +| Parameter | Type | Description | +|--------------------|-----------|------------------------------| +| `data` | `Object` | Instance details information | +| `data.serviceName` | `String` | Service name | +| `data.ip` | `String` | `IP` address | +| `data.port` | `int` | Port number | +| `data.clusterName` | `String` | Cluster name | +| `data.weight` | `double` | Instance weight | +| `data.healthy` | `boolean` | healthy | +| `data.instanceId` | `String` | Instance `id` | +| `data.metadata` | `map` | Instance metadata | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/instance?namespaceId=public&groupName=&serviceName=test_service&ip=127.0.0.1&port=8080' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": { + "serviceName": "DEFAULT_GROUP@@test_service", + "ip": "127.0.0.1", + "port": 8080, + "clusterName": "DEFAULT", + "weight": 1.0, + "healthy": true, + "instanceId": null, + "metadata": { + "value": "1" + } + } + } + ``` + +Query instances
+ +### Description + +Query the list of instances under the specified service + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/ns/instance/list` + +### Request Header + +| Parameter | Type | Required | Description | +|------------------|----------|----------|----------------------------------| +| `User-Agent` | `String` | N | User agent, default is empty | +| `Client-Version` | `String` | N | Client version, default is empty | + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|-----------|----------|---------------------------------------------------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is empty | +| `serviceName` | `String` | **Y** | Service name | +| `clusterName` | `String` | N | Cluster name, default is `DEFAULT` | +| `ip` | `String` | N | `IP` address, the default is empty, which means no restrictions on `IP` address | +| `port` | `int` | N | Port numberThe default is `0`, which means no restriction on port number | +| `healthyOnly` | `boolean` | N | Whether to get only healthy instances, default is `false` | +| `app` | `String` | N | Application name, default is empty | + +### Return Data + +| Parameter | Type | Description | +|----------------------------------------|------------|---------------------------------------------------| +| `data` | | List of instances of the specified service | +| `data.name` | `String` | Group name@@Service name | +| `data.groupName` | `String` | Group name | +| `data.clusters` | `String` | Cluster name | +| `data.cacheMillis` | `int` | Cache name | +| `data.hosts` | `Object[]` | Instance list | +| `data.hosts.ip` | `String` | Instance `IP` | +| `data.hosts.port` | `int` | Instance Port number | +| `data.hosts.weight` | `double` | Instance weight | +| `data.hosts.healthy` | `boolean` | Instance healthy | +| `data.hosts.enabled` | `boolean` | Instance is enabled | +| `data.hosts.ephemeral` | `boolean` | Whether it is a temporary instance | +| `data.hosts.clusterName` | `String` | Name of the cluster where the instance is located | +| `data.hosts.serviceName` | `String` | Service name | +| `data.hosts.metadata` | `map` | Instance metadata | +| `data.hosts.instanceHeartBeatTimeOut` | `int` | Instance heartbeat timeout time | +| `data.hosts.ipDeleteTimeout` | `int` | Instance delete timeout time | +| `data.hosts.instanceHeartBeatInterval` | `int` | Instance heartbeat interval | +| `data.lastRefTime` | `int` | last refresh time | +| `data.checksum` | `int` | checksum | +| `data.allIPs` | `boolean` | | +| `data.reachProtectionThreshold` | `boolean` | Whether the protection threshold is reached | +| `data.valid` | `boolean` | Valid | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/instance/list?serviceName=test_service&ip=127.0.0.1' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": { + "name": "DEFAULT_GROUP@@test_service", + "groupName": "DEFAULT_GROUP", + "clusters": "", + "cacheMillis": 10000, + "hosts": [ + { + "ip": "127.0.0.1", + "port": 8080, + "weight": 1.0, + "healthy": true, + "enabled": true, + "ephemeral": true, + "clusterName": "DEFAULT", + "serviceName": "DEFAULT_GROUP@@test_service", + "metadata": { + "value": "1" + }, + "instanceHeartBeatTimeOut": 15000, + "ipDeleteTimeout": 30000, + "instanceHeartBeatInterval": 5000 + } + ], + "lastRefTime": 1662554390814, + "checksum": "", + "allIPs": false, + "reachProtectionThreshold": false, + "valid": true + } + } + ``` + +Batch update instance metadata
+ +### Description + +Batch update instance metadata + +> If the key corresponding to the metadata does not exist, add the corresponding metadata. + +### Request Method + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/ns/instance/metadata/batch` + +### Request Body + +| Parameter | Type | Required | Description | +|-------------------|----------------------|----------|----------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is `DEFAULT_GROUP` | +| `serviceName` | `String` | **Y** | Service name | +| `consistencyType` | `String` | N | Persistence type, default is empty | +| `instances` | `JSON format String` | N | Instance list, default is empty | +| `metadata` | `JSON format String` | **Y** | Instance metadata | + +### Parameter Description + +> - `consistencyType`: Persistence type of Instance, when ``persist`'' means update the metadata of persistent Instance; otherwise means update the metadata of temporary Instance +> - `instances`: Instance list to be updated, `json` array, locate an instance by `ip+port+ephemeral+cluster`, null means update the metadata of all instances under the specified service + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -d 'serviceName=test_service' \ + -d 'consistencyType=ephemeral' \ + -d '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"}]' \ + -d 'metadata={"age":"20","name":"cocolan"}' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/instance/metadata/batch' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +Batch delete instance metadata
+ +### Description + +Batch delete instance metadata + +> If the key corresponding to the metadata does not exist, then no operation is performed + +### Request Method + +`DELETE` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/ns/instance/metadata/batch` + +### Request Body + +| Parameter | Type | Required | Description | +|-------------------|----------------------|----------|----------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is `DEFAULT_GROUP` | +| `serviceName` | `String` | **Y** | Service name | +| `consistencyType` | `String` | N | Persistence type, default is empty | +| `instances` | `JSON format String` | N | Instance list, default is empty | +| `metadata` | `JSON format String` | **Y** | Instance metadata | + +### Parameter Description + +> - `consistencyType`: Persistence type of Instance, when ``persist`'' means update the metadata of persistent Instance; otherwise means update the metadata of temporary Instance +> - `instances`: Instance list to be updated, `json` array, locate an instance by `ip+port+ephemeral+cluster`, null means update the metadata of all instances under the specified service + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -d 'serviceName=test_service' \ + -d 'consistencyType=ephemeral' \ + -d '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"}]' \ + -d 'metadata={"age":"20","name":"cocolan"}' \ + -X DELETE 'http://127.0.0.1:8848/nacos/v2/ns/instance/metadata/batch' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +Create service
+ +### Description + +Create a service + +> Failed to create when service already exists + +### Request Method + +`POST` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/ns/service` + +### Request Body + +| Parameter | Type | Required | Description | +|--------------------|----------------------|----------|--------------------------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is `DEFAULT_GROUP` | +| `serviceName` | `String` | **Y** | Service name | +| `metadata` | `JSON format String` | N | Service metadata, default is empty | +| `ephemeral` | `boolean` | N | Whether it is a temporary instance, default is `false` | +| `protectThreshold` | `float` | N | Protection threshold, default is `0` | +| `selector` | `JSON format String` | N | Selector, default is empty | + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -d 'serviceName=nacos.test.1' \ + -d 'ephemeral=true' \ + -d 'metadata={"k1":"v1"}' \ + -X POST 'http://127.0.0.1:8848/nacos/v2/ns/service' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +Delete service
+ +### Description + +Delete the specified service + +> An error is reported when the service does not exist, and deletion fails when an instance of the service still exists + +### Request Method + +`DELETE` + +### Request URL + +`/nacos/v2/ns/service` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|----------|----------|----------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is `DEFAULT_GROUP` | +| `serviceName` | `String` | **Y** | Service name | + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -X DELETE 'http://127.0.0.1:8848/nacos/v2/ns/service?serviceName=nacos.test.1' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +Update service
+ +### Description + +Update the specified service + +> Error when service does not exist + +### Request Method + +`POST` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/ns/service` + +### Request Parameters + +| Parameter | Type | Required | Description | +|--------------------|----------------------|----------|----------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is `DEFAULT_GROUP` | +| `serviceName` | `String` | **Y** | Service name | +| `metadata` | `JSON format String` | N | Service metadata, default is empty | +| `protectThreshold` | `float` | N | Protection threshold, default is `0` | +| `selector` | `JSON format String` | N | Selector, default is empty | + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -d 'serviceName=nacos.test.1' \ + -d 'metadata={"k1":"v2"}' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/service' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +Query service
+ +### Description + +Query detailed information about a specific service + +> Error when service does not exist + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/ns/service` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|----------|----------|------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is empty | +| `serviceName` | `String` | **Y** | Service name | + +### Return Data + +| Parameter | Type | Description | +|-------------------------|-----------|------------------------------------| +| `data` | | Service information | +| `data.namespace` | `String` | Namespace | +| `data.groupName` | `String` | Group name | +| `data.serviceName` | `String` | Service name | +| `data.clusterMap` | `map` | Cluster information | +| `data.metadata` | `map` | Service metadata | +| `data.protectThreshold` | `float` | Protection threshold | +| `data.selector` | `Object` | Selector | +| `data.ephemeral` | `Boolean` | Whether it is a temporary instance | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/service?serviceName=nacos.test.1' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": { + "namespace": "public", + "serviceName": "nacos.test.1", + "groupName": "DEFAULT_GROUP", + "clusterMap": {}, + "metadata": {}, + "protectThreshold": 0, + "selector": { + "type": "none", + "contextType": "NONE" + }, + "ephemeral": false + } + } + ``` + +Query service list
+ +### Description + +Check the list of eligible services + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/ns/service/list` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|----------------------|----------|----------------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is empty | +| `selector` | `JSON format String` | **Y** | Selector | +| `pageNo` | `int` | N | Current page, default is `1` | +| `pageSize` | `int` | N | Number of page, default is `20`, Up to `500` | + +### Return Data + +| Parameter | Type | Description | +|-----------------|------------|---------------------------| +| `data` | | Service list | +| `data.count` | `String` | Number of services | +| `data.services` | `String[]` | Service list after paging | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/service/list' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": { + "count": 2, + "services": [ + "nacos.test.1", + "nacos.test.2" + ] + } + } + ``` + +Query system switches
+ +### Description + +Query system switches + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/ns/operator/switches` + +### Return Data + +| Parameter | Type | Description | +|-----------|----------|---------------------------| +| `data` | `Object` | System switch information | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/operator/switches' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": { + "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": false, + "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": [], + "name": "00-00---000-NACOS_SWITCH_DOMAIN-000---00-00", + "checksum": null + } + } + ``` + +Update system switch
+ +### Description + +Update system switch + +### Request Method + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/ns/operator/switches` + +### Request Body + +| Parameter | Type | Required | Description | +|-----------|-----------|----------|--------------------------------------------------------------------------------------------------------------------------------------| +| `entry` | `String` | **Y** | Entry | +| `value` | `String` | **Y** | Value | +| `debug` | `boolean` | N | Whether it takes effect on local machine only,`true` means it takes effect on local machine,`false` means it takes effect on cluster | + +### Return Data + +| Parameter | Type | Description | +|-----------|----------|-------------------------------------| +| `data` | `String` | "ok" indicates successful execution | + +### Example + +* Request Example + + ```shell + curl -d 'entry=pushEnabled' \ + -d 'value=false' \ + -d 'debug=true' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/operator/switches' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": "ok" + } + ``` + +Query system metrics
+ +### Description + +Query system metrics + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/ns/operator/metrics` + +### Request Parameters + +| Parameter | Type | Required | Description | +|--------------|-----------|----------|-------------------------------------| +| `onlyStatus` | `boolean` | N | Show status only, default is `true` | + +> When `onlyStatus` is set to `true`, only the string indicating the system status is returned + +### Return Data + +| Parameter | Type | Description | +|------------------------------------|----------|----------------------------------| +| `data` | `Object` | System metrics | +| `data.status` | `String` | System status | +| `data.serviceCount` | `int` | Number of services | +| `data.instanceCount` | `int` | Number of instances | +| `data.subscribeCount` | `int` | Number of subscriptions | +| `data.raftNotifyTaskCount` | `int` | Number of `Raft` notify task | +| `data.responsibleServiceCount` | `int` | | +| `data.responsibleInstanceCount` | `int` | | +| `data.clientCount` | `int` | Number of client | +| `data.connectionBasedClientCount` | `int` | Number of connectionBasedClient | +| `data.ephemeralIpPortClientCount` | `int` | Number of ephemeralIpPortClient | +| `data.persistentIpPortClientCount` | `int` | Number of persistentIpPortClient | +| `data.responsibleClientCount` | `int` | | +| `data.cpu` | `float` | `cpu` utilization | +| `data.load` | `float` | load | +| `data.mem` | `float` | Memory usage | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/operator/metrics' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": { + "status": "UP", + "serviceCount": 2, + "instanceCount": 2, + "subscribeCount": 2, + "raftNotifyTaskCount": 0, + "responsibleServiceCount": 0, + "responsibleInstanceCount": 0, + "clientCount": 2, + "connectionBasedClientCount": 2, + "ephemeralIpPortClientCount": 0, + "persistentIpPortClientCount": 0, + "responsibleClientCount": 2, + "cpu": 0, + "load": -1, + "mem": 1 + } + } + ``` + +Update instance health status
+ +### Description + +Update the health status of the instance + +### Request Method + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/ns/health/instance` + +### Request Body + +| Parameter | Type | Required | Description | +|---------------|-----------|----------|----------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is `DEFAULT_GROUP` | +| `serviceName` | `String` | **Y** | Service name | +| `clusterName` | `String` | N | Cluster name, default is `DEFAULT` | +| `ip` | `String` | **Y** | `IP` address | +| `port` | `int` | **Y** | Port number | +| `healthy` | `boolean` | **Y** | healthy | + +### Return Data + +| Parameter | Type | Description | +|-----------|----------|---------------------------------------| +| `data` | `String` | "`ok`" indicates successful execution | + +### Example + +* Request Example + + ```shell + curl -d 'serviceName=nacos.test.1' \ + -d 'ip=127.0.0.1' \ + -d 'port=8080' \ + -d 'healthy=false' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/health/instance' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": "ok" + } + ``` + +Query client list (new)
+ +### Description + +Query the current list of all clients + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/ns/client/list` + +### Return Data + +| Parameter | Type | Description | +|-----------|------------|------------------| +| `data` | `String[]` | Client `id` list | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/list' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": [ + "10.128.164.35:9956#true", + "1664358687402_127.0.0.1_2300", + "1664358642902_127.0.0.1_2229", + "192.168.139.1:49825#true", + "10.128.164.35:9954#true", + "192.168.139.1:53556#true" + ] + } + ``` + +> For different versions of the nacos client, there are different ways to create clients. +> +> For `nacos client` in `1.x` version, each Instance will create two clients based on `ip+port`, corresponding to Instance registration and service subscription, respectively, with `clientId` in the format `ip:port#ephemeral` +> +> For `nacos client` in `2.x` version, each Instance establishes a `RPC` connection, which corresponds to an `RPC` connection-based client with both registration and subscription functions, with `clientId` in the format `time_ip_port` + + +Query client (new)
+ +### Description + +Query the details of the specified client + +> Error when client does not exist + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/ns/client` + +### Request Parameters + +| Parameter | Type| Required | Description | +|------------|----------|----------|------------| +| `clientId` | `String` | **Y** | Client `id` | + +### Return Data + +| Parameter | Type | Description | +|------------------------|-----------|------------------------------------| +| `data` | `Object` | Client Information | +| `data.clientId` | `String` | Client `id` | +| `data.ephemeral` | `boolean` | Whether it is a temporary instance | +| `data.lastUpdatedTime` | `int` | Last update time | +| `data.clientType` | `String` | Client type | +| `data.clientIp` | `String` | Client `IP` | +| `data.clientPort` | `String` | Client `port` | +| `data.connectType` | `String` | Connection type | +| `data.appName` | `String` | Application name | +| `data.Version` | `String` | Client version | + +> Only when `clientType` is `connection`, the `connectType`, `appName` and `appName` fields will be displayed + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client?clientId=1664527081276_127.0.0.1_4400' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": { + "clientId": "1664527081276_127.0.0.1_4400", + "ephemeral": true, + "lastUpdatedTime": 1664527081642, + "clientType": "connection", + "connectType": "GRPC", + "appName": "-", + "version": "Nacos-Java-Client:v2.1.0", + "clientIp": "10.128.164.35", + "clientPort": "4400" + } + } + ``` + +Query the registration information of the client (new)
+ +### Description + +Query the registration information of the specified client + +> Error when client does not exist + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/ns/client/publish/list` + +### Request Parameters + +| Parameter | Type | Required | Description | +|------------|----------|----------|-------------| +| `clientId` | `String` | **Y** | Client `id` | + +### Return Data + +| Parameter | Type | Description | +|-----------------------------------|------------|-------------------------------------------| +| `data` | `Object[]` | List of services registered by the client | +| `data.namespace` | `String` | Namespace | +| `data.group` | `String` | Group name | +| `data.serviceName` | `String` | Service name | +| `data.registeredInstance` | `Object` | Instances registered under this service | +| `data.registeredInstance.ip` | `String` | `IP` address | +| `data.registeredInstance.port` | `int` | Port number | +| `data.registeredInstance.cluster` | `String` | Cluster name | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/publish/list?clientId=1664527081276_127.0.0.1_4400' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "namespace": "public", + "group": "DEFAULT_GROUP", + "serviceName": "nacos.test.1", + "registeredInstance": { + "ip": "10.128.164.35", + "port": 9950, + "cluster": "DEFAULT" + } + } + ] + } + ``` + +Query the subscription information of the client (new)
+ +### Description + +Query the subscription information of the specified client + +> Error when client does not exist + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/ns/client/subscribe/list` + +### Request Parameters + +| Parameter | Type | Required | Description | +|------------|----------|----------|-------------| +| `clientId` | `String` | **Y** | Client `id` | + +### Return Data + +| Parameter | Type | Description | +|-----------------------------|------------|----------------------------------------------------| +| `data` | `Object[]` | List of services to which the client is subscribed | +| `data.namespace` | `String` | Namespace | +| `data.group` | `String` | Group name | +| `data.serviceName` | `String` | Service name | +| `data.subscriberInfo` | `Object` | Subscription Information | +| `data.subscriberInfo.app` | `String` | Application | +| `data.subscriberInfo.agent` | `String` | Client Information | +| `data.subscriberInfo.addr` | `String` | Address | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/subscribe/list?clientId=1664527081276_127.0.0.1_4400' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "namespace": "public", + "group": "DEFAULT_GROUP", + "serviceName": "nacos.test.1", + "subscriberInfo": { + "app": "unknown", + "agent": "Nacos-Java-Client:v2.1.0", + "addr": "10.128.164.35" + } + } + ] + } + ``` + +Query the client that registered the specified service (new)
+ +### Description + +Query the client information of the registered specified service + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/ns/client/service/publisher/list` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|-----------|----------|---------------------------------------------------------------------| +| `namespaceId` | `String` | N | Namespace`Id`, default is `public` | +| `groupName` | `String` | N | Group name, default is `DEFAULT_GROUP` | +| `serviceName` | `String` | **Y** | Service name | +| `ephemeral` | `boolean` | N | Whether it is a temporary instance | +| `ip` | `String` | N | `IP` address, default is empty, indicates unrestricted `IP` address | +| `port` | `int` | N | Port number, default is empty, Indicates unrestricted `Port` number | + +### Return Data + +| Parameter | Type | Description | +|-----------------|----------|---------------| +| `data` | | Client list | +| `data.clientId` | `String` | Client `id` | +| `data.ip` | `String` | Client `IP` | +| `data.port` | `int` | Client `port` | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/service/publisher/list?serviceName=nacos.test.1&ip=&port=' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "clientId": "1664527081276_127.0.0.1_4400", + "ip": "10.128.164.35", + "port": 9950 + }, + { + "clientId": "10.128.164.35:9954#true", + "ip": "10.128.164.35", + "port": 9954 + } + ] + } + ``` + +Query the information of clients subscribed to the specified service (new)
+ +### Description + +Query the clients subscribed to the specified service + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/ns/client/service/subscriber/list` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|---------|----------|---------------------------------------------------------------------| +| `namespaceId` | String | N | Namespace`Id`, default is `public` | +| `groupName` | String | N | Group name, default is `DEFAULT_GROUP` | +| `serviceName` | String | **Y** | Service name | +| `ephemeral` | boolean | N | Whether it is a temporary instance | +| `ip` | String | N | `IP` address, default is empty, indicates unrestricted `IP` address | +| `port` | int | N | Port number, default is empty, Indicates unrestricted `Port` number | + +### Return Data + +| Parameter | Type | Description | +|-----------------|----------|---------------| +| `data` | | Client list | +| `data.clientId` | `String` | Client `id` | +| `data.ip` | `String` | Client `IP` | +| `data.port` | `int` | Client `port` | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/service/subscriber/list?serviceName=nacos.test.1&ip=&port=' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "clientId": "1664527125645_127.0.0.1_4443", + "ip": "10.128.164.35", + "port": 0 + }, + { + "clientId": "172.24.144.1:54126#true", + "ip": "172.24.144.1", + "port": 54126 + } + ] + } + ``` + +## Namespace + +Query namespaces
+ +### Description + +Query all namespaces + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/console/namespace/list` + +### Return Data + +| Parameter | Type | Description | +|--------------------------|------------|-----------------------------------| +| `data` | `Object[]` | Namespaces | +| `data.namespace` | `String` | Namespace`ID` | +| `data.namespaceShowName` | `String` | Namespace name | +| `data.namespaceDesc` | `String` | Namespace description | +| `data.quota` | `int` | the capacity of Namespace | +| `data.configCount` | `int` | Number of configs under namespace | +| `data.type` | `int` | Namespace type | + +> There are 3 types of Namespace, `0 ` - Global Namespace `1 ` - Default Private Namespace `2 ` - Custom Namespace + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/console/namespace/list' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "namespace": "", + "namespaceShowName": "public", + "namespaceDesc": null, + "quota": 200, + "configCount": 1, + "type": 0 + } + ] + } + ``` + +Query namespace
+ +### Description + +Query information about a specific Namespace + +> Error when namespace does not exist + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/console/namespace` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|----------|----------|---------------| +| `namespaceId` | `String` | **Y** | Namespace`Id` | + +### Return Data + +| Parameter | Type | Description | +|--------------------------|----------|-----------------------------------| +| `data` | `Object` | Namespace | +| `data.namespace` | `String` | Namespace `ID` | +| `data.namespaceShowName` | `String` | Namespace name | +| `data.namespaceDesc` | `String` | Namespace description | +| `data.quota` | `int` | the capacity of Namespace | +| `data.configCount` | `int` | Number of configs under namespace | +| `data.type` | `int` | Namespace type | + +> There are 3 types of Namespace, `0 ` - Global Namespace `1 ` - Default Private Namespace `2 ` - Custom Namespace + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/console/namespace?namespaceId=test_namespace' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": { + "namespace": "test_namespace", + "namespaceShowName": "test", + "namespaceDesc": null, + "quota": 200, + "configCount": 0, + "type": 2 + } + } + ``` + +Create namespace
+ +### Description + +Create a namespace + +> Error when namespace already exists + +### Request Method + +`POST` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/console/namespace` + +### Request Body + +| Parameter | Type | Required | Description | +|-----------------|----------|----------|-----------------------| +| `namespaceId` | `String` | **Y** | Namespace`Id` | +| `namespaceName` | `String` | **Y** | Namespace name | +| `namespaceDesc` | `String` | N | Namespace Description | + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -d 'namespaceId=test_namespace' \ + -d 'namespaceName=test' \ + -X POST 'http://127.0.0.1:8848/nacos/v2/console/namespace' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +Update namespace
+ +### Description + +Edit namespace + +### Request Method + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/console/namespace` + +### Request Body + +| Parameter | Type | Required | Description | +|-----------------|----------|----------|-----------------------| +| `namespaceId` | `String` | **Y** | Namespace`Id` | +| `namespaceName` | `String` | **Y** | Namespace name | +| `namespaceDesc` | `String` | N | Namespace Description | + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -d 'namespaceId=test_namespace' \ + -d 'namespaceName=test.nacos' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/console/namespace' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +Delete namespace
+ +### Description + +Delete the specified namespace + +### Request Method + +`DELETE` + +### Request URL + +`/nacos/v2/console/namespace` + +### Request Parameters + +| Parameter | Type | Required | Description | +|---------------|----------|----------|---------------| +| `namespaceId` | `String` | **Y** | Namespace`Id` | + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -d 'namespaceId=test_namespace' \ + -X DELETE 'http://127.0.0.1:8848/nacos/v2/console/namespace' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +## Cluster + +Query the current node
+ +### Description + +Query the current `nacos` node + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/core/cluster/node/self` + +Return Data
+ +| Parameter | Type | Description | +|----------------------|----------|--------------------------| +| `data` | `Object` | Current node | +| `data.ip` | `String` | Node `IP` address | +| `data.port` | `int` | Node port | +| `data.state` | `String` | Node status | +| `data.extendInfo` | `Object` | Node extend information | +| `data.address` | `String` | Node address （`IP:port`） | +| `data.failAccessCnt` | `int` | Number of failed access | +| `data.abilities` | `Object` | | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/cluster/node/self' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": { + "ip": "10.128.164.35", + "port": 8848, + "state": "UP", + "extendInfo": { + "lastRefreshTime": 1664521263623, + "raftMetaData": { + "metaDataMap": { + "naming_instance_metadata": { + "leader": "10.128.164.35:7848", + "raftGroupMember": [ + "10.128.164.35:7848" + ], + "term": 12 + }, + "naming_persistent_service_v2": { + "leader": "10.128.164.35:7848", + "raftGroupMember": [ + "10.128.164.35:7848" + ], + "term": 12 + }, + "naming_service_metadata": { + "leader": "10.128.164.35:7848", + "raftGroupMember": [ + "10.128.164.35:7848" + ], + "term": 12 + } + } + }, + "raftPort": "7848", + "readyToUpgrade": true, + "version": "2.1.0" + }, + "address": "10.128.164.35:8848", + "failAccessCnt": 0, + "abilities": { + "remoteAbility": { + "supportRemoteConnection": true + }, + "configAbility": { + "supportRemoteMetrics": false + }, + "namingAbility": { + "supportJraft": true + } + } + } + } + ``` + +Query the list of cluster nodes
+ +### Description + +Query the information of all nodes in the cluster + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/core/cluster/node/list` + +### Request Parameters + +| Parameter | Type | Required | Description | +|-----------|----------|----------|--------------------------------| +| `address` | `String` | N | Node address, default is empty | +| `state` | `String` | N | Node status, default is empty | + +> `address`corresponds to the prefix match condition of the Node address to be queried, and is not restricted when it is empty +> +> `state`corresponds to the filter condition of node status and is not restricted when it is empty + +### Return Data + +| Parameter | Type | Description | +|-----------|------------|------------------------------------------| +| `data` | `Object[]` | Node list, refer to [Node info](#Member) | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/cluster/node/list' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "ip": "10.128.164.35", + "port": 8848, + "state": "UP", + "extendInfo": { + "lastRefreshTime": 1664521263623, + "raftMetaData": { + "metaDataMap": { + "naming_instance_metadata": { + "leader": "10.128.164.35:7848", + "raftGroupMember": [ + "10.128.164.35:7848" + ], + "term": 12 + }, + "naming_persistent_service_v2": { + "leader": "10.128.164.35:7848", + "raftGroupMember": [ + "10.128.164.35:7848" + ], + "term": 12 + }, + "naming_service_metadata": { + "leader": "10.128.164.35:7848", + "raftGroupMember": [ + "10.128.164.35:7848" + ], + "term": 12 + } + } + }, + "raftPort": "7848", + "readyToUpgrade": true, + "version": "2.1.0" + }, + "address": "10.128.164.35:8848", + "failAccessCnt": 0, + "abilities": { + "remoteAbility": { + "supportRemoteConnection": true + }, + "configAbility": { + "supportRemoteMetrics": false + }, + "namingAbility": { + "supportJraft": true + } + } + } + ] + } + ``` + +Query the current node health status
+ +### Description + +Query the current `nacos` node health status + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/core/cluster/node/self/health` + +Return Data
+ +| Parameter | Type | Description | +|-----------|----------|----------------------------| +| `data` | `String` | Current node health status | + +> Node has five states: `STARTING`, `UP`, `SUSPICIOUS`, `DOWN` and `ISOLATION`. + +### Example + +* Request Example + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/cluster/node/self/health' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": "UP" + } + ``` + + +Switch addressing modes
+ +### Description + +Switch addressing modes + +### Request Method + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +### Request URL + +`/nacos/v2/core/cluster/lookup` + +### Request Body + +| Parameter | Type | Required | Description | +|-----------|----------|----------|-----------------| +| `type` | `String` | **Y** | Addressing mode | + +> There are two addressing modes: `file` (file configuration) and `address-server` (address server) + +### Return Data + +| Parameter | Type | Description | +|-----------|-----------|-------------------------------------| +| `data` | `boolean` | Whether the execution is successful | + +### Example + +* Request Example + + ```shell + curl -d 'type=file' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/core/cluster/lookup' + ``` + +* Response Example + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +## Connection Load Management + +###Query the List of Current Node Client Connections
+ +#### Description + +Query the list of client connections on the current `Nacos` node. + +#### Request Method + +`GET` + +#### Request URL + +`/nacos/v2/core/loader/current` + +#### Return Data + +| Parameter | Type | Description | +|----------------|-----------|----------------------| +| `traced` | `Boolean` | Monitoring indicator | +| `abilityTable` | `Map` | Capability table | +| `metaInfo` | `Object` | Metadata | +| `connected` | `Integer` | Connection status | +| `labels` | `Map` | Labels | + +#### Example + +* Request Example + +```shell +curl -X GET 'http://localhost:8848/nacos/v2/core/loader/current' +``` + +* Response Example + +```json +{ + "1697424543845_127.0.0.1_11547": { + "traced": false, + "abilityTable": null, + "metaInfo": { + "connectType": "GRPC", + "clientIp": "192.168.49.1", + "localPort": 9848, + "version": "Nacos-Java-Client:v2.1.0", + "connectionId": "1697424543845_127.0.0.1_11547", + "createTime": "2023-10-16T10:49:03.907+08:00", + "lastActiveTime": 1697424869827, + "appName": "unknown", + "tenant": "", + "labels": { + "source": "sdk", + "taskId": "0", + "module": "config", + "AppName": "unknown" + }, + "tag": null, + "sdkSource": true, + "clusterSource": false + }, + "connected": true, + "labels": { + "source": "sdk", + "taskId": "0", + "module": "config", + "AppName": "unknown" + } + } +} + +``` + +Reload the Number of Current Node Client Connections
+ +### Description + +Reload the number of client connections on the current `Nacos` node. + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/core/loader/current/reloadCurrent` + +### Request Parameters + +| Parameter | Type | Required | Description | +|-------------------|-----------|----------|-------------------| +| `count` | `Integer` | **Y** | ID of connections | +| `redirectAddress` | `String` | N | Redirect address | + +### Return Data + +| Parameter | Type | Description | +|-----------|----------|------------------| +| `data` | `String` | Execution result | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://localhost:8848/nacos/v2/core/loader/reloadCurrent?count=1&redirectAddress=127.0.0.1:8848' + ``` + +* Response Example + + ```text + success + ``` + +Intelligently Balance the Number of Client Connections in the Cluster
+ +### Description + +Intelligently balance the client connections among all nodes in the `Nacos` cluster. + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/core/loader/current/smartReloadCluster` + +### Request Parameters + +| Parameter | Type | Required | Description | +|----------------|----------|----------|-------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `loaderFactor` | `Float` | N | The loading factor, with a default value of 0.1, determines the number of SDKs per node, calculated as (1 - loaderFactor) * avg ~ (1 + loaderFactor) * avg. | +| `force` | `String` | N | Force flag | + +### Return Data + +| Parameter | Type | Description | +|-----------|----------|------------------| +| `data` | `String` | Execution result | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://localhost:8848/nacos/v2/core/loader/smartReloadCluster?loaderFactor=1' + ``` + +* Response Example + + ```text + Ok + ``` + +Reset a Specific Client Connection
+ +### Description + +Send a connection reset request based on the `SDK` connection ID. + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/core/loader/current/reloadClient` + +### Request Body + +| Parameter | Type | Required | Description | +|-------------------|----------|----------|---------------| +| `connectionId` | `String` | **Y** | Connection ID | +| `redirectAddress` | `String` | N | Reset address | + +### Return Data + +| Parameter | Type | Description | +|-----------|----------|------------------| +| `data` | `String` | Execution result | + +### Example + +* Request Example + + ```shell + curl -X GET 'http://localhost:8848/nacos/v2/core/loader/reloadClient?connectionId=1&redirectAddress=127.0.0.1:8848' + ``` + +* Response Example + + ```text + success + ``` + +Get SDK Metrics for the Cluster
+ +### Description + +Get SDK metrics for all nodes in the `Nacos` cluster. + +### Request Method + +`GET` + +### Request URL + +`/nacos/v2/core/loader/current/cluster` + +### Return Data + +| Parameter | Type | Description | +|------------------|-----------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `total` | `Integer` | Current number of cluster nodes | +| `min` | `Integer` | Minimum load value | +| `avg` | `Integer` | Average load value | +| `max` | `Integer` | Maximum load value | +| `memberCount` | `Integer` | Number of members in the current node | +| `metricsCount` | `Integer` | Number of load information | +| `threshold` | `Float` | Load threshold. The threshold is calculated as: Average load value * 1.1 | +| `detail` | `String` | Contains detailed load information for each node | +| `detail.address` | `Map
+
+
+
+
+
+#### Return values
+
+| Type | Description |
+| :--- | :--- |
+| string | configuration value |
+
+
+#### Request example
+
+```java
+try {
+ // Initialize the configuration service, and the console automatically obtains the following parameters through the sample code.
+ String serverAddr = "{serverAddr}";
+ String dataId = "{dataId}";
+ String group = "{group}";
+ Properties properties = new Properties();
+ properties.put("serverAddr", serverAddr);
+ ConfigService configService = NacosFactory.createConfigService(properties);
+ // Actively get the configuration.
+ String content = configService.getConfig(dataId, group, 5000);
+ System.out.println(content);
+} catch (NacosException e) {
+ // TODO Auto-generated catch block
+ e.printStackTrace();
+}
+```
+
+#### Exception specification
+
+A ConfigException is thrown in case of a configuration read time-out or a network error.
+
+### Listen configuration
+#### Description
+
+Use dynamic configuration listening API to enable Nacos to send configuration change notifications.
+
+```java
+public void addListener(String dataId, ConfigChangeListenerAdapter listener)
+```
+
+#### Request parameters
+
+|
+ Name
+ |
+
+ Type
+ |
+
+ Description
+ |
+
|
+ dataId
+ |
+
+ string
+
+ |
+
+ Configuration ID. Use a naming rule similar to package.class (for example, com.taobao.tc.refund.log.level) to ensure global uniqueness. It is recommended to indicate business meaning of the configuration in the "class" section. Use
+ lower case for all characters. Use alphabetical letters and these four special characters (".", ":", "-", "_") only. Up to 256 characters are allowed.
+ |
+
|
+ group
+ |
+
+ string
+ |
+
+ Configuration group. To ensure uniqueness, format such as product name: module name (for example, Nacos:Test) is preferred. Use alphabetical letters and these four special characters (".", ":", "-",
+ "_") only. Up to 128 characters are allowed.
+ |
+
|
+ timeout
+ |
+
+ long
+ |
+
+ Length of configuration read time-out (in ms). Recommended value: 3000.
+ |
+
+
+
+
+
+#### Return values
+
+| Type | Description |
+| :--- | :--- |
+| string | Configuration value. This value is returned through the callback function during initialization or configuration modification. |
+
+#### Request example
+
+```java
+
+// Initialize the configuration service, and the console automatically obtains the following parameters through the sample code.
+String serverAddr = "{serverAddr}";
+String dataId = "{dataId}";
+String group = "{group}";
+Properties properties = new Properties();
+properties.put("serverAddr", serverAddr);
+ConfigService configService = NacosFactory.createConfigService(properties);
+String content = configService.getConfig(dataId, group, 5000);
+System.out.println(content);
+configService.addListener(dataId, group, new Listener() {
+ @Override
+ public void receiveConfigInfo(String configInfo) {
+ System.out.println("receive1:" + configInfo);
+ }
+ @Override
+ public Executor getExecutor() {
+ return null;
+ }
+});
+
+// Keep the main thread alive throughout the test, because the configuration subscription runs in a daemon thread, which exits once the main thread exits. The following code is not required in a real environment.
+while (true) {
+ try {
+ Thread.sleep(1000);
+ } catch (InterruptedException e) {
+ e.printStackTrace();
+ }
+}
+```
+
+### Delete Listening
+#### Description
+
+Cancel listen configuration. No more notification after cancellation.
+
+```java
+public void removeListener(String dataId, String group, Listener listener)
+```
+
+#### Request parameters
+
+|
+ Name
+ |
+
+ Type
+ |
+
+ Description
+ |
+
|
+ dataId
+ |
+
+ string
+ |
+
+ Configuration ID. Use a naming rule similar to package.class (for example, com.taobao.tc.refund.log.level) to ensure global uniqueness. It is recommended to indicate business meaning of the configuration in the "class" section. Use
+ lower case for all characters. Use alphabetical letters and these four special characters (".", ":", "-", "_") only. Up to 256 characters are allowed.
+ |
+
|
+ group
+ |
+
+ string
+ |
+
+ Configuration group. To ensure uniqueness, format such as product name: module name (for example, Nacos:Test) is preferred. Use alphabetical letters and these four special characters (".", ":", "-",
+ "_") only. Up to 128 characters are allowed.
+ |
+
|
+ listener
+ |
+
+ Config Change Listener
+ |
+
+ Listener. Configuration changes go into the callback function of the listener.
+ |
+
+
+
+
+
+#### Request example
+
+```java
+String serverAddr = "{serverAddr}";
+String dataId = "{dataId}";
+String group = "{group}";
+Properties properties = new Properties();
+properties.put("serverAddr", serverAddr);
+ConfigService configService = NacosFactory.createConfigService(properties);
+configService.removeListener(dataId, group, yourListener);
+```
+
+### Publish configuration
+#### Description
+
+Publish Nacos configurations automatically to reduce the operation and maintenance cost.
+
+__Note:__ It uses the same publishing interface to create or modify a configuration. If the specified configuration doesn’t exist, it will create a configuration. If the specified configuration exists, it will update the configuration.
+
+```java
+public boolean publishConfig(String dataId, String group, String content) throws NacosException;
+
+@Since 1.4.1
+public boolean publishConfig(String dataId, String group, String content, String type) throws NacosException;
+
+```
+
+#### Request parameters
+
+| Name | Type | Description |
+| :--- | :--- | :--- |
+| dataId | string | Configuration ID. Naming rule is similar to package.class (com.taobao.tc.refund.log.level) is used to ensure the global uniqueness We recommend that you define class by business meaning. All characters must be in lower case. Use alphabetical letters and these four special characters (".", ":", "-", "\_") only. Up to 256 characters are allowed. |
+| group | string | Configuration group. We recommend that you use product name: module name (for example Nacos:Test) to ensure the uniqueness. Use alphabetical letters and these four special characters (".", ":", "-", "\_") only. Up to 128 characters are allowed. |
+| content | string | Configuration content. No more than 100K bytes. |
+| type | string | @Since 1.4.1. Configuration type. See com.alibaba.nacos.api.config.ConfigType, default as TEXT. |
+
+#### Response parameters
+
+| Type | Description |
+| :--- | :--- |
+| boolean | If the publishing is successful |
+
+
+#### Request example
+
+```java
+try {
+ // Initialize the configuration service. Retrieves the following parameters in console with sample code
+ String serverAddr = "{serverAddr}";
+ String dataId = "{dataId}";
+ String group = "{group}";
+ Properties properties = new Properties();
+ properties.put("serverAddr", serverAddr);
+ ConfigService configService = NacosFactory.createConfigService(properties);
+ boolean isPublishOk = configService.publishConfig(dataId, group, "content");
+ System.out.println(isPublishOk);
+} catch (NacosException e) {
+ // TODO Auto-generated catch block
+ e.printStackTrace();
+}
+```
+
+#### Exceptions
+
+In case of reading configuration timeout or network issues, ConfigException exception is thrown.
+
+
+### Delete configuration
+#### Description
+
+It deletes Nacos configurations automatically with program to reduce operation and maintenance costs with automation.
+
+__Note:__ If the specified configuration exists, then it deletes the configuration. If the specified configuration doesn’t exist, then it returns a successful message.
+
+```java
+public boolean removeConfig(String dataId, String group) throws NacosException
+
+```
+
+#### Request parameters
+
+
+| Parameter name | Parameter type | Description |
+| :--- | :--- | :--- |
+| dataId | String | Configuration ID |
+| group | String | Configuration group |
+
+
+#### Response parameters
+
+
+| Parameter type | Description |
+| :--- | :--- |
+| boolean | If the deletion is successful |
+
+
+#### Request example
+
+```java
+try {
+ // Initialize the configuration service. Retrieves the following parameters in console with sample code
+ String serverAddr = "{serverAddr}";
+ String dataId = "{dataId}";
+ String group = "{group}";
+ Properties properties = new Properties();
+ properties.put("serverAddr", serverAddr);
+
+ ConfigService configService = NacosFactory.createConfigService(properties);
+ boolean isRemoveOk = configService.removeConfig(dataId, group);
+ System.out.println(isRemoveOk);
+} catch (NacosException e) {
+ // TODO Auto-generated catch block
+ e.printStackTrace();
+}
+```
+
+#### Exceptions
+
+In case of reading configuration timeout or network issues, ConfigException exception is thrown.
+
+## Service Discovery SDK
+### Register Instance
+#### Description
+Register an instance to service.
+```java
+void registerInstance(String serviceName, String ip, int port) throws NacosException;
+
+void registerInstance(String serviceName, String ip, int port, String clusterName) throws NacosException;
+
+void registerInstance(String serviceName, Instance instance) throws NacosException;
+```
+
+#### Request Parameters
+
+| Name | Type | Description |
+| :--- | :--- | --- |
+| serviceName | String | service name |
+| ip | String | instance ip |
+| port | int | instance port |
+| clusterName | String | cluster name |
+| instance | Refer to Java docs | instance properties |
+
+#### Response
+void
+#### Request Example
+```java
+NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
+naming.registerInstance("nacos.test.3", "11.11.11.11", 8888, "TEST1");
+
+Instance instance = new Instance();
+instance.setIp("55.55.55.55");
+instance.setPort(9999);
+instance.setHealthy(false);
+instance.setWeight(2.0);
+Map|
+ Name
+ |
+
+ Type
+ |
+
+ Description
+ |
+
|
+ dataId
+ |
+
+ string
+ |
+
+ Configuration ID. Use a naming rule similar to package.class (for example, com.taobao.tc.refund.log.level) to ensure global uniqueness. It is recommended to indicate business meaning of the configuration in the "class" section. Use
+ lower case for all characters. Use alphabetical letters and these four special characters (".", ":", "-", "_") only. Up to 256 characters are allowed.
+ |
+
|
+ group
+ |
+
+ string
+ |
+
+ Configuration group
+ |
+
|
+ listener
+ |
+
+ ConfigChangeListenerAdapter
+ |
+
+ Listener. Configuration changes go into the callback function of the listener.
+ |
+
返回数据
+ +| 参数名 | 参数类型 | 描述说明 | +|-------------------------|----------|------------| +| `data` | `Object` | 历史配置项 | +| `data.id` | `String` | 配置`id` | +| `data.lastId` | `int` | | +| `data.dataId` | `String` | 配置名 | +| `data.group` | `String` | 配置分组 | +| `data.tenant` | `String` | 租户信息（命名空间） | +| `data.appName` | `String` | 应用名 | +| `data.md5` | `String` | 配置内容的md5值 | +| `data.content` | `String` | 配置内容 | +| `data.srcIp` | `String` | 源ip | +| `data.srcUser` | `String` | 源用户 | +| `data.opType` | `String` | 操作类型 | +| `data.createdTime` | `String` | 创建时间 | +| `data.lastModifiedTime` | `String` | 上次修改时间 | +| `data.encryptedDataKey` | `String` | | + +#### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history?dataId=nacos.example&group=com.alibaba.nacos&namespaceId=&nid=203' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "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" + } + } + ``` + +### 2.6. 查询配置上一版本信息 + +#### 接口描述 + +获取指定配置的上一版本 + +#### 请求方式 + +`GET` + +#### 请求URL + +`/nacos/v2/cs/history/previous` + +#### 请求参数 + +| 参数名 | 类型 | 必填 | 参数描述 | +|---------------|----------|--------|------------------------| +| `namespaceId` | `String` | 否 | 命名空间，默认为`public`与 `''`相同 | +| `group` | `String` | **是** | 配置分组名 | +| `dataId` | `String` | **是** | 配置名 | +| `id` | `long` | **是** | 配置id | + +返回数据
+ +| 参数名 | 参数类型 | 描述说明 | +|--------|----------|------------------------------------------------------| +| `data` | `Object` | 历史配置项，参见[历史配置项信息](#ConfigHistoryInfo) | + +#### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history/previous?id=309135486247505920&dataId=nacos.example&group=com.alibaba.nacos&namespaceId=' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "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" + } + } + ``` + +## 3. 服务发现 + +:::note +Nacos v2的openAPI中，已移除关于`发送实例心跳`的相关API，原因是Nacos2.0对于非持久化实例，已经使用长链接作为存活的基准，而不是通过传统`心跳续约`的方式进行。因此对于使用Nacos2.0的客户端用户，以及针对Nacos2.0进行服务开发的用户，其实已经不再需要使用v2的心跳openAPI。 + +Nacos v2的`注册实例`的OpenAPI，更多的是给予持久化服务实例进行注册；非持久化实例的注册，建议采用Nacos2.0客户端进行，获取更高的性能及更灵敏的变化感知能力。 + +对于仍然在使用Nacos1.X客户端的用户，以及基于Nacos v1 `发送实例心跳`的openAPI的用户，依旧可以继续使用。 +::: + +### 3.1. 注册实例 + +#### 接口描述 + +注册一个实例 + +#### 请求方式 + +`POST` + +`Content-Type:application/x-www-form-urlencoded` + +#### 请求URL + +`/nacos/v2/ns/instance` + +#### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|------------------|----------|----------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `ip` | `String` | **是** | `IP`地址 | +| `port` | `int` | **是** | 端口号 | +| `clusterName` | `String` | 否 | 集群名称，默认为`DEFAULT` | +| `healthy` | `boolean` | 否 | 是否只查找健康实例，默认为`true` | +| `weight` | `double` | 否 | 实例权重，默认为`1.0` | +| `enabled` | `boolean` | 否 | 是否可用，默认为`true` | +| `metadata` | `JSON格式String` | 否 | 实例元数据 | +| `ephemeral` | `boolean` | 否 | 是否为临时实例 | + +#### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +#### 示例 + +* 请求示例 + + ```shell + curl -d 'serviceName=test_service' \ + -d 'ip=127.0.0.1' \ + -d 'port=8090' \ + -d 'weight=0.9' \ + -d 'ephemeral=true' \ + -X POST 'http://127.0.0.1:8848/nacos/v2/ns/instance' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +### 3.2. 注销实例 + +#### 接口描述 + +注销指定实例 + +#### 请求方式 + +`DELETE` + +`Content-Type:application/x-www-form-urlencoded` + +#### 请求URL + +`/nacos/v2/ns/instance` + +#### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|------------------|----------|----------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `ip` | `String` | **是** | `IP`地址 | +| `port` | `int` | **是** | 端口号 | +| `clusterName` | `String` | 否 | 集群名称，默认为`DEFAULT` | +| `healthy` | `boolean` | 否 | 是否只查找健康实例，默认为`true` | +| `weight` | `double` | 否 | 实例权重，默认为`1.0` | +| `enabled` | `boolean` | 否 | 是否可用，默认为`true` | +| `metadata` | `JSON格式String` | 否 | 实例元数据 | +| `ephemeral` | `boolean` | 否 | 是否为临时实例 | + +#### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +#### 示例 + +* 请求示例 + + ```shell + curl -d 'serviceName=test_service' \ + -d 'ip=127.0.0.1' \ + -d 'port=8090' \ + -d 'weight=0.9' \ + -d 'ephemeral=true' \ + -X DELETE 'http://127.0.0.1:8848/nacos/v2/ns/instance' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +### 3.3. 更新实例 + +#### 接口描述 + +修改实例信息 + +> 通过该接口更新的元数据拥有更高的优先级，且具有记忆能力；会在对应实例删除后，依旧存在一段时间，如果在此期间实例重新注册，该元数据依旧生效；您可以通过`nacos.naming.clean.expired-metadata.expired-time`及`nacos.naming.clean.expired-metadata.interval`对记忆时间进行修改 + +#### 请求方式 + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +#### 请求URL + +`/nacos/v2/ns/instance` + +#### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|------------------|----------|----------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `ip` | `String` | **是** | `IP`地址 | +| `port` | `int` | **是** | 端口号 | +| `clusterName` | `String` | 否 | 集群名称，默认为`DEFAULT` | +| `healthy` | `boolean` | 否 | 是否只查找健康实例，默认为`true` | +| `weight` | `double` | 否 | 实例权重，默认为`1.0` | +| `enabled` | `boolean` | 否 | 是否可用，默认为`true` | +| `metadata` | `JSON格式String` | 否 | 实例元数据 | +| `ephemeral` | `boolean` | 否 | 是否为临时实例 | + +#### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +#### 示例 + +* 请求示例 + + ```shell + curl -d 'serviceName=test_service' \ + -d 'ip=127.0.0.1' \ + -d 'port=8090' \ + -d 'weight=0.9' \ + -d 'ephemeral=true' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/instance' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +### 3.4. 查询实例详情 + +#### 接口描述 + +查询某个具体实例的详情信息 + +#### 请求方式 + +`GET` + +#### 请求URL + +`/nacos/v2/ns/instance` + +#### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|----------|----------|-------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `clusterName` | `String` | 否 | 集群名称，默认为`DEFAULT` | +| `ip` | `String` | **是** | `IP`地址 | +| `port` | `int` | **是** | 端口号 | + +#### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|--------------------|-----------|--------------| +| `data` | `Object` | 实例详情信息 | +| `data.serviceName` | `String` | 服务名 | +| `data.ip` | `String` | `IP`地址 | +| `data.port` | `int` | 端口号 | +| `data.clusterName` | `String` | 集群名称 | +| `data.weight` | `double` | 实例权重 | +| `data.healthy` | `boolean` | 是否健康 | +| `data.instanceId` | `String` | 实例`id` | +| `data.metadata` | `map` | 实例元数据 | + +#### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/instance?namespaceId=public&groupName=&serviceName=test_service&ip=127.0.0.1&port=8080' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "serviceName": "DEFAULT_GROUP@@test_service", + "ip": "127.0.0.1", + "port": 8080, + "clusterName": "DEFAULT", + "weight": 1.0, + "healthy": true, + "instanceId": null, + "metadata": { + "value": "1" + } + } + } + ``` + +### 3.5. 查询指定服务的实例列表 + +#### 接口描述 + +查询指定服务下的实例详情信息列表 + +#### 请求方式 + +`GET` + +#### 请求URL + +`/nacos/v2/ns/instance/list` + +#### 请求头 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|------------------|----------|----------|----------------------| +| `User-Agent` | `String` | 否 | 用户代理，默认为空 | +| `Client-Version` | `String` | 否 | 客户端版本，默认为空 | + +#### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|-----------|----------|----------------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `clusterName` | `String` | 否 | 集群名称，默认为`DEFAULT` | +| `ip` | `String` | 否 | `IP`地址，默认为空，表示不限制`IP`地址 | +| `port` | `int` | 否 | 端口号，默认为`0`，表示不限制端口号 | +| `healthyOnly` | `boolean` | 否 | 是否只获取健康实例，默认为`false` | +| `app` | `String` | 否 | 应用名，默认为空 | + +#### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|----------------------------------------|------------|-----------| +| `data` | | 指定服务的实例列表 | +| `data.name` | `String` | 分组名@@服务名 | +| `data.groupName` | `String` | 分组名 | +| `data.clusters` | `String` | 集群名 | +| `data.cacheMillis` | `int` | 缓存时间 | +| `data.hosts` | `Object[]` | 实例列表 | +| `data.hosts.ip` | `String` | 实例`IP` | +| `data.hosts.port` | `int` | 实例端口号 | +| `data.hosts.weight` | `double` | 实例权重 | +| `data.hosts.healthy` | `boolean` | 实例是否健康 | +| `data.hosts.enabled` | `boolean` | 实例是否可用 | +| `data.hosts.ephemeral` | `boolean` | 是否为临时实例 | +| `data.hosts.clusterName` | `String` | 实例所在的集群名称 | +| `data.hosts.serviceName` | `String` | 服务名 | +| `data.hosts.metadata` | `map` | 实例元数据 | +| `data.hosts.instanceHeartBeatTimeOut` | `int` | 实例心跳超时时间 | +| `data.hosts.ipDeleteTimeout` | `int` | 实例删除超时时间 | +| `data.hosts.instanceHeartBeatInterval` | `int` | 实例心跳间隔 | +| `data.lastRefTime` | `int` | 上次刷新时间 | +| `data.checksum` | `int` | 校验码 | +| `data.allIPs` | `boolean` | | +| `data.reachProtectionThreshold` | `boolean` | 是否到达保护阈值 | +| `data.valid` | `boolean` | 是否有效 | + +#### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/instance/list?serviceName=test_service&ip=127.0.0.1' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "name": "DEFAULT_GROUP@@test_service", + "groupName": "DEFAULT_GROUP", + "clusters": "", + "cacheMillis": 10000, + "hosts": [ + { + "ip": "127.0.0.1", + "port": 8080, + "weight": 1.0, + "healthy": true, + "enabled": true, + "ephemeral": true, + "clusterName": "DEFAULT", + "serviceName": "DEFAULT_GROUP@@test_service", + "metadata": { + "value": "1" + }, + "instanceHeartBeatTimeOut": 15000, + "ipDeleteTimeout": 30000, + "instanceHeartBeatInterval": 5000 + } + ], + "lastRefTime": 1662554390814, + "checksum": "", + "allIPs": false, + "reachProtectionThreshold": false, + "valid": true + } + } + ``` + +### 3.6. 批量更新实例元数据 + +#### 接口描述 + +批量更新实例的元数据, + +> 对应元数据的键不存在时，则添加对应元数据 + +#### 请求方式 + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +#### 请求URL + +`/nacos/v2/ns/instance/metadata/batch` + +#### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|-------------------|------------------|----------|-------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `consistencyType` | `String` | 否 | 持久化类型，默认为空 | +| `instances` | `JSON格式String` | 否 | 需要更新的实例列表，默认为空 | +| `metadata` | `JSON格式String` | **是** | 实例元数据 | + +#### 参数说明 + +> - `consistencyType`: 实例的持久化类型，当为‘`persist`’，表示对持久化实例的元数据进行更新；否则表示对临时实例的元数据进行更新 +> - `instances`: 待更新的实例列表，`json`数组，通过`ip+port+ephemeral+cluster`定位到某一实例，为空则表示更新指定服务下所有实例的元数据 + +#### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +#### 示例 + +* 请求示例 + + ```shell + curl -d 'serviceName=test_service' \ + -d 'consistencyType=ephemeral' \ + -d '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"}]' \ + -d 'metadata={"age":"20","name":"cocolan"}' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/instance/metadata/batch' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +### 3.7. 批量删除实例元数据 + +#### 接口描述 + +批量删除实例的元数据, + +> 对应元数据的键不存在时，则不做操作 + +#### 请求方式 + +`DELETE` + +`Content-Type:application/x-www-form-urlencoded` + +#### 请求URL + +`/nacos/v2/ns/instance/metadata/batch` + +#### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|-------------------|------------------|----------|-------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `consistencyType` | `String` | 否 | 持久化类型，默认为空 | +| `instances` | `JSON格式String` | 否 | 需要更新的实例列表，默认为空 | +| `metadata` | `JSON格式String` | **是** | 实例元数据 | + +#### 参数说明 + +> - `consistencyType`: 实例的持久化类型，当为‘`persist`’，表示对持久化实例的元数据进行删除；否则表示对临时实例的元数据进行 +> - `instances`: 待更新的实例列表，`json`数组，通过`ip+port+ephemeral+cluster`定位到某一实例，为空则表示更新指定服务下所有实例的元数据 + +#### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +#### 示例 + +* 请求示例 + + ```shell + curl -d 'serviceName=test_service' \ + -d 'consistencyType=ephemeral' \ + -d '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"}]' \ + -d 'metadata={"age":"20","name":"cocolan"}' \ + -X DELETE 'http://127.0.0.1:8848/nacos/v2/ns/instance/metadata/batch' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +### 3.8. 创建服务 + +#### 接口描述 + +创建一个服务 + +> 服务已存在时会创建失败 + +#### 请求方式 + +`POST` + +`Content-Type:application/x-www-form-urlencoded` + +#### 请求URL + +`/nacos/v2/ns/service` + +#### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|--------------------|------------------|----------|-------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `metadata` | `JSON格式String` | 否 | 服务元数据，默认为空 | +| `ephemeral` | `boolean` | 否 | 是否为临时实例，默认为`false` | +| `protectThreshold` | `float` | 否 | 保护阈值，默认为`0` | +| `selector` | `JSON格式String` | 否 | 访问策略，默认为空 | + +#### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +#### 示例 + +* 请求示例 + + ```shell + curl -d 'serviceName=nacos.test.1' \ + -d 'ephemeral=true' \ + -d 'metadata={"k1":"v1"}' \ + -X POST 'http://127.0.0.1:8848/nacos/v2/ns/service' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +### 3.9. 删除服务 + +#### 接口描述 + +删除指定服务 + +> 服务不存在时会报错，且服务还存在实例时会删除失败 + +#### 请求方式 + +`DELETE` + +#### 请求URL + +`/nacos/v2/ns/service` + +#### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|----------|----------|-------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | + +#### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +#### 示例 + +* 请求示例 + + ```shell + curl -X DELETE 'http://127.0.0.1:8848/nacos/v2/ns/service?serviceName=nacos.test.1' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +### 3.10. 修改服务 + +#### 接口描述 + +更新指定服务 + +> 服务不存在时会报错 + +#### 请求方式 + +`POST` + +`Content-Type:application/x-www-form-urlencoded` + +#### 请求URL + +`/nacos/v2/ns/service` + +#### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|--------------------|------------------|----------|-------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `metadata` | `JSON格式String` | 否 | 服务元数据，默认为空 | +| `protectThreshold` | `float` | 否 | 保护阈值，默认为`0` | +| `selector` | `JSON格式String` | 否 | 访问策略，默认为空 | + +#### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +#### 示例 + +* 请求示例 + + ```shell + curl -d 'serviceName=nacos.test.1' \ + -d 'metadata={"k1":"v2"}' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/service' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +### 3.11. 查询服务详情 + +#### 接口描述 + +查询某个具体服务的详情信息 + +> 服务不存在时会报错 + +#### 请求方式 + +`GET` + +#### 请求URL + +`/nacos/v2/ns/service` + +#### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|----------|----------|---------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | + +#### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|-------------------------|-----------|----------------| +| `data` | | 服务信息 | +| `data.namespace` | `String` | 命名空间 | +| `data.groupName` | `String` | 分组名 | +| `data.serviceName` | `String` | 服务名 | +| `data.clusterMap` | `map` | 集群信息 | +| `data.metadata` | `map` | 服务元数据 | +| `data.protectThreshold` | `float` | 保护阈值 | +| `data.selector` | `Object` | 访问策略 | +| `data.ephemeral` | `Boolean` | 是否为临时实例 | + +#### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/service?serviceName=nacos.test.1' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "namespace": "public", + "serviceName": "nacos.test.1", + "groupName": "DEFAULT_GROUP", + "clusterMap": {}, + "metadata": {}, + "protectThreshold": 0, + "selector": { + "type": "none", + "contextType": "NONE" + }, + "ephemeral": false + } + } + ``` + +### 3.12. 查询服务列表 + +#### 接口描述 + +查询符合条件的服务列表 + +#### 请求方式 + +`GET` + +#### 请求URL + +`/nacos/v2/ns/service/list` + +#### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|------------------|----------|-----------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `selector` | `JSON格式String` | **是** | 访问策略 | +| `pageNo` | `int` | 否 | 当前页，默认为`1` | +| `pageSize` | `int` | 否 | 页条目数，默认为`20`，最大为`500` | + +#### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|-----------------|------------|------------------| +| `data` | | 服务列表信息 | +| `data.count` | `String` | 服务数目 | +| `data.services` | `String[]` | 分页后的服务列表 | + +#### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/service/list' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "count": 2, + "services": [ + "nacos.test.1", + "nacos.test.2" + ] + } + } + ``` + +### 3.13. 更新实例健康状态 + +#### 接口描述 + +更新实例的健康状态 + +#### 请求方式 + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +#### 请求URL + +`/nacos/v2/ns/health/instance` + +#### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|-----------|----------|-------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `clusterName` | `String` | 否 | 集群名，默认为`DEFAULT` | +| `ip` | `String` | **是** | `IP`地址 | +| `port` | `int` | **是** | 端口号 | +| `healthy` | `boolean` | **是** | 是否健康 | + +#### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|----------|--------------------| +| `data` | `String` | “`ok`”表示执行成功 | + +#### 示例 + +* 请求示例 + + ```shell + curl -d 'serviceName=nacos.test.1' \ + -d 'ip=127.0.0.1' \ + -d 'port=8080' \ + -d 'healthy=false' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/health/instance' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": "ok" + } + ``` + +### 3.14. 查询客户端列表（新） + +#### 接口描述 + +查询当前所有的客户端列表 + +#### 请求方式 + +`GET` + +#### 请求URL + +`/nacos/v2/ns/client/list` + +#### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|--------|------------|----------------| +| `data` | `String[]` | 客户端`id`列表 | + +#### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/list' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": [ + "10.128.164.35:9956#true", + "1664358687402_127.0.0.1_2300", + "1664358642902_127.0.0.1_2229", + "192.168.139.1:49825#true", + "10.128.164.35:9954#true", + "192.168.139.1:53556#true" + ] + } + ``` + +> 对于不同版本的nacos client，建立客户端的方式不同。 +> +> 对于`1.x`版本，每个实例会建立两个基于`ip+port`的客户端，分别对应实例注册与服务订阅，`clientId`格式为 `ip:port#ephemeral` +> +> 对于`2.x`版本的`nacos client`, 每个实例会建立一个`RPC`连接，对应一个基于`RPC`连接的客户端，兼具注册与订阅功能，`clientId` +> 格式为`time_ip_port` + + + +### 3.15. 查询客户端信息（新） + +#### 接口描述 + +查询指定客户端的详细信息 + +> 客户端不存在时会报错 + +#### 请求方式 + +`GET` + +#### 请求URL + +`/nacos/v2/ns/client` + +#### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|------------|----------|----------|------------| +| `clientId` | `String` | **是** | 客户端`id` | + +#### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|------------------------|-----------|----------------| +| `data` | `Object` | 客户端信息 | +| `data.clientId` | `String` | 客户端`id` | +| `data.ephemeral` | `boolean` | 是否为临时实例 | +| `data.lastUpdatedTime` | `int` | 上次更新时间 | +| `data.clientType` | `String` | 客户端类型 | +| `data.clientIp` | `String` | 客户端`IP` | +| `data.clientPort` | `String` | 客户端端口 | +| `data.connectType` | `String` | 连接类型 | +| `data.appName` | `String` | 应用名 | +| `data.Version` | `String` | 客户端版本 | + +> 只有当`clientType`为`connection`时，会显示`connectType`，`appName`和`appName`字段 + +#### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client?clientId=1664527081276_127.0.0.1_4400' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "clientId": "1664527081276_127.0.0.1_4400", + "ephemeral": true, + "lastUpdatedTime": 1664527081642, + "clientType": "connection", + "connectType": "GRPC", + "appName": "-", + "version": "Nacos-Java-Client:v2.1.0", + "clientIp": "10.128.164.35", + "clientPort": "4400" + } + } + ``` + +### 3.16. 查询客户端的注册信息（新） + +#### 接口描述 + +查询指定客户端的注册信息 + +> 客户端不存在时会报错 + +#### 请求方式 + +`GET` + +#### 请求URL + +`/nacos/v2/ns/client/publish/list` + +#### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|------------|----------|----------|------------| +| `clientId` | `String` | **是** | 客户端`id` | + +#### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|-----------------------------------|------------|----------------------| +| `data` | `Object[]` | 客户端注册的服务列表 | +| `data.namespace` | `String` | 命名空间 | +| `data.group` | `String` | 分组名 | +| `data.serviceName` | `String` | 服务名 | +| `data.registeredInstance` | `Object` | 该服务下注册的实例 | +| `data.registeredInstance.ip` | `String` | `IP`地址 | +| `data.registeredInstance.port` | `int` | 端口号 | +| `data.registeredInstance.cluster` | `String` | 集群名 | + +#### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/publish/list?clientId=1664527081276_127.0.0.1_4400' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "namespace": "public", + "group": "DEFAULT_GROUP", + "serviceName": "nacos.test.1", + "registeredInstance": { + "ip": "10.128.164.35", + "port": 9950, + "cluster": "DEFAULT" + } + } + ] + } + ``` + +### 3.17. 查询客户端的订阅信息（新） + +#### 接口描述 + +查询指定客户端的订阅信息 + +> 客户端不存在时会报错 + +#### 请求方式 + +`GET` + +#### 请求URL + +`/nacos/v2/ns/client/subscribe/list` + +#### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|------------|----------|----------|------------| +| `clientId` | `String` | **是** | 客户端`id` | + +#### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|-----------------------------|------------|----------------------| +| `data` | `Object[]` | 客户端订阅的服务列表 | +| `data.namespace` | `String` | 命名空间 | +| `data.group` | `String` | 分组名 | +| `data.serviceName` | `String` | 服务名 | +| `data.subscriberInfo` | `Object` | 订阅信息 | +| `data.subscriberInfo.app` | `String` | 应用 | +| `data.subscriberInfo.agent` | `String` | 客户端信息 | +| `data.subscriberInfo.addr` | `String` | 地址 | + +#### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/subscribe/list?clientId=1664527081276_127.0.0.1_4400' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "namespace": "public", + "group": "DEFAULT_GROUP", + "serviceName": "nacos.test.1", + "subscriberInfo": { + "app": "unknown", + "agent": "Nacos-Java-Client:v2.1.0", + "addr": "10.128.164.35" + } + } + ] + } + ``` + +### 3.18. 查询注册指定服务的客户端信息（新） + +#### 接口描述 + +查询注册指定服务的客户端信息 + +#### 请求方式 + +`GET` + +#### 请求URL + +`/nacos/v2/ns/client/service/publisher/list` + +#### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|-----------|----------|------------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `ephemeral` | `boolean` | 否 | 是否为临时实例 | +| `ip` | `String` | 否 | `IP`地址，默认为空，不限制`IP`地址 | +| `port` | `int` | 否 | 端口号，默认为空，表示不限制端口号 | + +#### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|-----------------|----------|------------| +| `data` | | 客户端列表 | +| `data.clientId` | `String` | 客户端`id` | +| `data.ip` | `String` | 客户端`IP` | +| `data.port` | `int` | 客户端端口 | + +#### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/service/publisher/list?serviceName=nacos.test.1&ip=&port=' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "clientId": "1664527081276_127.0.0.1_4400", + "ip": "10.128.164.35", + "port": 9950 + }, + { + "clientId": "10.128.164.35:9954#true", + "ip": "10.128.164.35", + "port": 9954 + } + ] + } + ``` + +### 3.19. 查询订阅指定服务的客户端信息（新） + +#### 接口描述 + +查询订阅指定服务的客户端信息 + +#### 请求方式 + +`GET` + +#### 请求URL + +`/nacos/v2/ns/client/service/subscriber/list` + +#### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|----------|----------|------------------------------------| +| `namespaceId` | String | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | String | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | String | **是** | 服务名 | +| `ephemeral` | boolean | 否 | 是否为临时实例 | +| `ip` | String | 否 | `IP`地址，默认为空，不限制`IP`地址 | +| `port` | int | 否 | 端口号，默认为空，表示不限制端口号 | + +#### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|-----------------|----------|------------| +| `data` | | 客户端列表 | +| `data.clientId` | `String` | 客户端`id` | +| `data.ip` | `String` | 客户端`IP` | +| `data.port` | `int` | 客户端端口 | + +#### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/service/subscriber/list?serviceName=nacos.test.1&ip=&port=' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "clientId": "1664527125645_127.0.0.1_4443", + "ip": "10.128.164.35", + "port": 0 + }, + { + "clientId": "172.24.144.1:54126#true", + "ip": "172.24.144.1", + "port": 54126 + } + ] + } + ``` + +## 4. 命名空间 + +### 4.1. 查询命名空间列表 + +#### 接口描述 + +查询当前所有的命名空间 + +#### 请求方式 + +`GET` + +#### 请求URL + +`/nacos/v2/console/namespace/list` + +#### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|--------------------------|------------|----------------------| +| `data` | `Object[]` | 命名空间列表 | +| `data.namespace` | `String` | 命名空间`ID` | +| `data.namespaceShowName` | `String` | 命名空间名称 | +| `data.namespaceDesc` | `String` | 命名空间描述 | +| `data.quota` | `int` | 命名空间的容量 | +| `data.configCount` | `int` | 命名空间下的配置数量 | +| `data.type` | `int` | 命名空间类型 | + +> 命名空间分为3种类型，`0 `- 全局命名空间 `1` - 默认私有命名空间 `2 `- 自定义命名空间 + +#### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/console/namespace/list' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "namespace": "", + "namespaceShowName": "public", + "namespaceDesc": null, + "quota": 200, + "configCount": 1, + "type": 0 + } + ] + } + ``` + +### 4.2. 查询具体命名空间 + +#### 接口描述 + +查询具体命名空间的信息 + +> 命名空间不存在时会报错 + +#### 请求方式 + +`GET` + +#### 请求URL + +`/nacos/v2/console/namespace` + +#### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|----------|----------|--------------| +| `namespaceId` | `String` | **是** | 命名空间`Id` | + +#### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|--------------------------|----------|----------------------| +| `data` | `Object` | 命名空间信息 | +| `data.namespace` | `String` | 命名空间`ID` | +| `data.namespaceShowName` | `String` | 命名空间名称 | +| `data.namespaceDesc` | `String` | 命名空间描述 | +| `data.quota` | `int` | 命名空间的容量 | +| `data.configCount` | `int` | 命名空间下的配置数量 | +| `data.type` | `int` | 命名空间类型 | + +> 命名空间分为3种类型，`0` - 全局命名空间 `1` - 默认私有命名空间 `2` - 自定义命名空间 + +#### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/console/namespace?namespaceId=test_namespace' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "namespace": "test_namespace", + "namespaceShowName": "test", + "namespaceDesc": null, + "quota": 200, + "configCount": 0, + "type": 2 + } + } + ``` + +### 4.3. 创建命名空间 + +#### 接口描述 + +创建一个命名空间 + +> 命名空间已存在时会报错 + +#### 请求方式 + +`POST` + +`Content-Type:application/x-www-form-urlencoded` + +#### 请求URL + +`/nacos/v2/console/namespace` + +#### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|-----------------|----------|----------|--------------| +| `namespaceId` | `String` | **是** | 命名空间`Id` | +| `namespaceName` | `String` | **是** | 命名空间名称 | +| `namespaceDesc` | `String` | 否 | 命名空间描述 | + +#### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +#### 示例 + +* 请求示例 + + ```shell + curl -d 'namespaceId=test_namespace' \ + -d 'namespaceName=test' \ + -X POST 'http://127.0.0.1:8848/nacos/v2/console/namespace' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +### 4.4. 编辑命名空间 + +#### 接口描述 + +编辑命名空间信息 + +#### 请求方式 + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +#### 请求URL + +`/nacos/v2/console/namespace` + +#### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|-----------------|----------|----------|--------------| +| `namespaceId` | `String` | **是** | 命名空间`Id` | +| `namespaceName` | `String` | **是** | 命名空间名称 | +| `namespaceDesc` | `String` | 否 | 命名空间描述 | + +#### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +#### 示例 + +* 请求示例 + + ```shell + curl -d 'namespaceId=test_namespace' \ + -d 'namespaceName=test.nacos' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/console/namespace' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +### 4.5. 删除命名空间 + +#### 接口描述 + +删除指定命名空间 + +#### 请求方式 + +`DELETE` + +#### 请求URL + +`/nacos/v2/console/namespace` + +#### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|----------|----------|--------------| +| `namespaceId` | `String` | **是** | 命名空间`Id` | + +#### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +#### 示例 + +* 请求示例 + + ```shell + curl -d 'namespaceId=test_namespace' \ + -X DELETE 'http://127.0.0.1:8848/nacos/v2/console/namespace' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` diff --git a/src/content/docs/v3.0/en/manual/user/overview/other-language.md b/src/content/docs/v3.0/en/manual/user/overview/other-language.md new file mode 100644 index 00000000000..ad2eb365c5d --- /dev/null +++ b/src/content/docs/v3.0/en/manual/user/overview/other-language.md @@ -0,0 +1,22 @@ +--- +title: Nacos SDK OverView +keywords: [其他语言,SDK] +description: 其他语言的SDK +sidebar: + order: 1 +--- + +# Nacos SDK OverView + +Nacos官方目前提供并维护了Java、Golang、Python三个版本的客户端，同时我们将主要依靠社区的贡献来发展多语言客户端。在未来，我们将向Nacos社区用户推荐那些最被广泛使用的以及支持最好的客户端作为Nacos相应语言的官方版本。 + +| Language | code repo | pkg repo | +| ---- | ---- | ---- | +| Java | [https://github.com/alibaba/nacos](https://github.com/alibaba/nacos)| [https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client](https://mvnrepository.com/artifact/com.alibaba.nacos/nacos-client) +| Golang | [https://github.com/nacos-group/nacos-sdk-go](https://github.com/nacos-group/nacos-sdk-go) | github.com/nacos-group/nacos-sdk-go/v2| +| Python | [https://github.com/nacos-group/nacos-sdk-python](https://github.com/nacos-group/nacos-sdk-python) |[https://pypi.org/project/nacos-sdk-python/](https://pypi.org/project/nacos-sdk-python/)| +| C++ | [https://github.com/nacos-group/nacos-sdk-cpp](https://github.com/nacos-group/nacos-sdk-cpp)|/| +| NodeJS|[https://github.com/nacos-group/nacos-sdk-nodejs](https://github.com/nacos-group/nacos-sdk-nodejs)|[https://www.npmjs.com/package/nacos](https://www.npmjs.com/package/nacos)| +| C#| [https://github.com/nacos-group/nacos-sdk-csharp](https://github.com/nacos-group/nacos-sdk-csharp)|[https://www.nuget.org/packages/nacos-sdk-csharp](https://www.nuget.org/packages/nacos-sdk-csharp)| +|Rust|[https://github.com/nacos-group/nacos-sdk-rust](https://github.com/nacos-group/nacos-sdk-rust)|[https://crates.io/crates/nacos-sdk/versions](https://crates.io/crates/nacos-sdk/versions) + diff --git a/src/content/docs/v3.0/en/manual/user/parameters-check.md b/src/content/docs/v3.0/en/manual/user/parameters-check.md new file mode 100644 index 00000000000..ff8e25675dc --- /dev/null +++ b/src/content/docs/v3.0/en/manual/user/parameters-check.md @@ -0,0 +1,235 @@ +--- +title: 参数校验 +keywords: [参数校验,使用规则] +description: 参数校验 +sidebar: + order: 9 +--- + +# 参数校验 + +2.3.0版本之前的Nacos的参数校验逻辑分散，由各类请求的处理方法单独进行校验，难以更改维护，经常出现参数校验的遗漏，参数校验的规则也没有明确统一；这使得用户使用时经常会因为一些特殊字符导致功能不符合预期或出现漏洞，甚至导致大量推送，导致带宽打满，内存占用过多，导致应用出现故障。 + +在2.3.0之后的版本中，Nacos明确了参数校验规则，在服务端实现了统一的参数校验逻辑并添加了参数校验层，根据校验规则对客户端向服务端发送的请求进行校验。 + +用户可以选择开启参数校验功能，开启后Nacos将会对客户端向服务端发送的请求中的部分参数进行参数校验，确保参数的合法性，避免由于错误使用，导致的不符合预期以及性能问题。 + +## 1. 参数校验开关 + +服务端的参数校验功能**默认开启**，用户可以通过设置`${nacos.home}/conf`目录下的`application.properties`文件中的`nacos.core.param.check.enabled`值选择开启或者关闭服务端参数校验功能。 + +`nacos.core.param.check.enabled=true`时开启Nacos服务端参数校验，`false`关闭服务端参数校验 + +## 2. 参数校验规则 + +开启参数校验后OpenAPI文档 和 SDK文档中的所有接口中的相关参数都会接受格式校验，现对相关参数以及校验规则进行说明： + +|参数描述|最大字符长度|校验规则| +|-----|-----|-----| +|命名空间名称|256|禁止`@#$%^&*`，对应正则表达式：`[^@#$%^&*]+$`| +|命名空间ID|64|只允许字母数字下划线以及"-"字符，对应正则表达式：`^[\w-]+`｜ +|配置名称|256|只允许字母数字以及`_-.:`，对应正则表达式：`^[a-zA-Z0-9-_:\.]*$`| +|服务名称|512|禁止中文和`@@`且禁止以`@`开头，禁止空白字符，对应正则表达式`^(?!@).((?!@@)[^\u4E00-\u9FA5])*$`| +|分组名称|128|只允许字母数字以及`_-.:`，对应正则表达式：`^[a-zA-Z0-9-_:\.]*$`| +|集群名称|64|只允许数字字母和`-_`，对应正则表达式`^[0-9a-zA-Z-_]+$`| +|IP地址|128|禁止中文字符和空白字符，对应正则表达式为`^[^\u4E00-\u9FA5]*$`| +|端口号|-|取值范围为`0～65535`| +|实例元数据|1024|字段名加字段值的总长度小于1024个字符| + +### 2.1. namespaceShowName + +#### 参数描述 + +命名空间名称 + +#### 校验规则 + +字符长度最大为256，禁止`@#$%^&*`,对应正则表达式：`[^@#$%^&*]+$` + +#### OpenAPI示例 + +- [创建命名空间](./open-api.md#43-创建命名空间) + +#### 校验失败报错信息 + +- 超出长度：`Param 'namespaceShowName' is illegal, the param length should not exceed 256.` +- 非法字符：`Param 'namespaceShowName' is illegal, illegal characters should not appear in the param.` + +### 2.2. namespaceId/tenant/namespace + +#### 参数描述 + +命名空间ID（租户空间） + +#### 校验规则 + +字符长度最大为64，只允许字母数字下划线以及"-"字符，对应正则表达式：`^[\w-]+` + +#### OpenAPI示例 + +- [获取配置](./open-api.md#21-获取配置) +- [注册实例](./open-api.md#31-注册实例) + +#### 校验失败报错信息 + +- 超出长度：`Param 'namespaceId/tenant' is illegal, the param length should not exceed 64.` +- 非法字符：`Param 'namespaceId/tenant' is illegal, illegal characters should not appear in the param.` + +### 2.3. dataId + +#### 参数描述 + +配置名称 + +#### 校验规则 + +字符长度最大为256，只允许字母数字以及`_-.:`，对应正则表达式：`^[a-zA-Z0-9-_:\.]*$` + +#### OpenAPI示例 + +[发布配置](./open-api.md#22-发布配置) + +#### Java SDK示例 + +监听配置：`public void addListener(String dataId, String group, Listener listener) ` + +#### 校验失败报错信息 + +- 超出长度：`Param 'dataId' is illegal, the param length should not exceed 512.` +- 非法字符：`Param 'dataId' is illegal, illegal characters should not appear in the param.` + +### 2.4. service/serviceName + +#### 参数描述 + +服务名称 + +#### 校验规则 + +字符长度最大为512，禁止中文和`@@`且禁止以`@`开头，对应正则表达式`^(?!@).((?!@@)[^\u4E00-\u9FA5])*$` + +#### OpenAPI示例 + +[注册实例](./open-api.md#31-注册实例) + +#### Java SDK示例 + +注册实例：`void registerInstance(String serviceName, String ip, int port) throws NacosException; ` + +#### 校验失败报错信息 + +- 超出长度：`Param 'serviceName' is illegal, the param length should not exceed 512.` +- 非法字符：`Param 'serviceName' is illegal, illegal characters should not appear in the param.` + +### 2.5. group/groupName + +#### 参数描述 + +分组名称 + +#### 校验规则 + +字符长度最大为128，只允许字母数字以及`_-.:`，对应正则表达式：`^[a-zA-Z0-9-_:\.]*$` + +#### OpenAPI示例 + +[查询实例列表](./open-api.md#35-查询指定服务的实例列表) + +#### Java SDK示例 + +删除配置：`public boolean removeConfig(String dataId, String group) throws NacosException ` + +#### 校验失败报错信息 + +- 超出长度：`Param 'group' is illegal, the param length should not exceed 512.` +- 非法字符：`Param 'group' is illegal, illegal characters should not appear in the param.` + +### 2.6. cluster/clusterName + +#### 参数描述 + +集群名称 + +#### 校验规则 + +字符长度最大为64，只允许数字字母和`-_`，对应正则表达式`^[0-9a-zA-Z-_]+$` + +#### OpenAPI示例 + +[更新实例](./open-api.md#33-更新实例) + +#### Java SDK示例 + +获取全部实例：`ListRegisterInstanceTraceEvent
+ +> Since 2.2.0. + +type: `REGISTER_INSTANCE_TRACE_EVENT` + +Extra Content: + +|Field Name|Description| +|-----|---| +|clientIp|The source IP of registering service instance request, probably null.| +|rpc|Whether the source request is gRPC, `true` when request is gRPC, `false` is HTTP.| +|instanceIp|The IP or Host of service instance registered| +|instancePort|The Port of service instance registered| + +DeregisterInstanceTraceEvent
+ +> Since 2.2.0. + +type: `DEREGISTER_INSTANCE_TRACE_EVENT` + +Extra Content: + +|Field Name|Description| +|-----|---| +|clientIp|The source IP of de-registering service instance request, probably null.| +|reason|The reason of de-registering, details see [DeregisterInstanceReason](#1.2.1)| +|rpc|Whether the source request is gRPC, `true` when request is gRPC, `false` is HTTP.| +|instanceIp|The IP or Host of service instance de-registered| +|instancePort|The Port of service instance de-registered| + +DeregisterInstanceReason
+ +|Reason|Description| +|-----|---| +|REQUEST|De-registration comes from client requests, in other word, user initiated de-registration.| +|NATIVE_DISCONNECTED|De-registration comes from client disconnected| +|SYNCED_DISCONNECTED|De-registration comes from client disconnected in other server node, and synced from other server node.| +|HEARTBEAT_EXPIRE|De-registration comes from heartbeat timeout for 1.X version client.| + +RegisterServiceTraceEvent
+ +> Since 2.2.0. + +type: `REGISTER_SERVICE_TRACE_EVENT` + +Extra Content: None + +DeregisterServiceTraceEvent
+ +> Since 2.2.0. + +type: `DEREGISTER_SERVICE_TRACE_EVENT` + +Extra Content: None + +SubscribeServiceTraceEvent
+ +> Since 2.2.0. + +type: `SUBSCRIBE_SERVICE_TRACE_EVENT` + +Extra Content: + +|Field Name|Description| +|-----|---| +|clientIp|The IP of subscriber| + +UnsubscribeServiceTraceEvent
+ +> Since 2.2.0. + +type: `UNSUBSCRIBE_SERVICE_TRACE_EVENT` + +Extra Content: + +|Field Name|Description| +|-----|---| +|clientIp|The IP of subscriber| + +PushServiceTraceEvent
+ +> Since 2.2.0. + +type: `PUSH_SERVICE_TRACE_EVENT` + +Extra Content: + +|Field Name|Description| +|-----|---| +|clientIp|The IP of subscriber| +|instanceSize|The size of service instance for this push| +|pushCostTimeForAll|The full cost for this push, means that the cost from start pushing to end pushing, including the wait time in combined queue and the time for executing.| +|pushCostTimeForNetWork|The network cost for this push, means that the cost from executing to end pushing, only including the network cost.| +|serviceLevelAgreementTime|The actual cost for this push, means the cost from services changeing to end pushing. It's a reference value not accuracy.| + +HealthStateChangeTraceEvent
+ +> Since 2.2.0. + +type: `HEALTH_STATE_CHANGE_TRACE_EVENT` + +Extra Content: + +|Field Name|Description| +|-----|---| +|instanceIp|The IP or Host of service instance changed| +|instancePort|The Port of service instance changed| +|isHealthy|The change result is healthy or not| +|healthCheckType|The type of health check| +|healthStateChangeReason|The reason of healthy changed| diff --git a/src/content/docs/v3.0/en/quickstart/quick-start-docker.mdx b/src/content/docs/v3.0/en/quickstart/quick-start-docker.mdx new file mode 100644 index 00000000000..fc30a2fb9e4 --- /dev/null +++ b/src/content/docs/v3.0/en/quickstart/quick-start-docker.mdx @@ -0,0 +1,83 @@ +--- +title: Nacos Docker 快速开始 +keywords: [Nacos,Docker] +description: Nacos Docker 快速开始 +sidebar: + order: 2 +--- + +# Nacos Docker 快速开始 + +这个快速开始手册是帮忙您快速在通过Nacos的Docker镜像，在Docker容器中部署并使用 Nacos。 + +:::note +- 快速开始旨在帮助您快速上手安装、部署及入门使用Nacos，本快速开始所生产出的Nacos服务为**单机模式**及**未开启鉴权**，建议仅在测试中使用，若在实际生产环境中部署，请部署**集群模式**并**开启鉴权**，以避免存在**稳定性和安全性**的风险。 +- Nacos定义为一个IDC内部应用组件，并非面向公网环境的产品，建议在内部隔离网络环境中部署，**强烈不建议**部署在公共网络环境。 +::: + +## 1. 环境准备 + +使用此快速开始方法进行Nacos安装及部署，需要安装[Docker](https://www.docker.com/)和[Docker Compose](https://docs.docker.com/compose/)。 + +## 2. 下载 nacos-docker 项目 + +```powershell +git clone https://github.com/nacos-group/nacos-docker.git +cd nacos-docker +``` + +## 3. 执行 docker-compose 命令启动Nacos + +> 首次执行命令时，会自动下载所需的相关Docker镜像，需要等待的时长取决于网络速度。您也可以提前下载好相关镜像，以缩短执行部署命令的等待时间。 + +```powershell +docker-compose -f example/standalone-derby.yaml up +``` + +## 4. 验证Nacos服务是否启动成功 + +通过`docker logs -f $container_id`命令，查看Nacos服务启动日志，如果看到如下日志，说明服务启动成功。 + +``` +Nacos started successfully in xxxx mode. use xxxx storage +``` + +可以通过下列服务，快速检验Nacos的功能。 + +### 4.1. 服务注册 + + ```powershell + curl -X POST 'http://127.0.0.1:8848/nacos/v1/ns/instance?serviceName=nacos.naming.serviceName&ip=20.18.7.10&port=8080' + ``` + +### 4.2. 服务发现 + + ```powershell + curl -X GET 'http://127.0.0.1:8848/nacos/v1/ns/instance/list?serviceName=nacos.naming.serviceName' + ``` + +### 4.3. 发布配置 + + ```powershell + curl -X POST "http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=nacos.cfg.dataId&group=test&content=helloWorld" + ``` + +### 4.4. 获取配置 + + ```powershell + curl -X GET "http://127.0.0.1:8848/nacos/v1/cs/configs?dataId=nacos.cfg.dataId&group=test" + ``` + +### 4.5. Nacos控制台页面 + + link：http://127.0.0.1:8848/nacos/ + +## Nacos + Grafana + Prometheus +参考：[Nacos监控指南](../guide/admin/monitor-guide.md) + +**Note**: grafana创建一个新数据源时，数据源地址必须是 **http://prometheus:9090** + +## 相关项目 + +* [Nacos](https://github.com/alibaba/nacos) +* [Nacos Docker](https://github.com/nacos-group/nacos-docker) diff --git a/src/content/docs/v3.0/en/quickstart/quick-start-kubernetes.mdx b/src/content/docs/v3.0/en/quickstart/quick-start-kubernetes.mdx new file mode 100644 index 00000000000..a8b0f689af5 --- /dev/null +++ b/src/content/docs/v3.0/en/quickstart/quick-start-kubernetes.mdx @@ -0,0 +1,81 @@ +--- +title: Nacos Kubernetes 快速开始 +keywords: [nacos,kubernetes] +description: 本项目包含一个可构建的Nacos Docker Image，旨在利用 StatefulSets 在 Kubernetes上部署 Nacos。 +sidebar: + order: 3 +--- + +# Nacos Kubernetes 快速开始 + +这个快速开始手册是帮忙您快速在通过Nacos的Docker镜像，在Kubernetes中部署并使用 Nacos。 + +:::note +- 快速开始旨在帮助您快速上手安装、部署及入门使用Nacos，本快速开始所生产出的Nacos服务为**未开启鉴权**，建议仅在测试中使用，若在实际生产环境中部署，请部署**开启鉴权**，以避免存在**安全性**的风险。 +- 快速开始旨在帮助您快速上手安装、部署及入门使用Nacos，本快速开始为方便快速在kubernetes环境中部署Nacos，连接数据库时使用了默认的数据库配置，建议仅在测试中使用，在实际生产环境部署时，请**务必**修改部署的数据库配置信息，以避免存在**安全性**的风险。 +- Nacos定义为一个IDC内部应用组件，并非面向公网环境的产品，建议在内部隔离网络环境中部署，**强烈不建议**部署在公共网络环境。 +::: + +## 1. 环境准备 + +使用此快速开始方法进行Nacos安装及部署，需要安装[Kubernetes](https://kubernetes.io/)。 + +## 2. 下载 nacos-k8s 项目 + +```shell +git clone https://github.com/nacos-group/nacos-k8s.git +cd nacos-k8s +``` + +## 3. 快速启动 + +> 使用此方式快速启动,请注意这是没有使用持久化卷的,可能存在数据丢失风险: + +```shell +cd nacos-k8s +chmod +x quick-startup.sh +./quick-startup.sh +``` + +## 4. 验证Nacos服务是否启动成功 + +通过`kubectl logs -f $pod_name`命令，查看Nacos服务启动日志，如果看到如下日志，说明服务启动成功。 + +``` +Nacos started successfully in xxxx mode. use xxxx storage +``` + +可以通过下列服务，快速检验Nacos的功能。 + +### 4.1. 服务注册 + + ```powershell + curl -X POST 'http://${cluster-ip}:8848/nacos/v1/ns/instance?serviceName=nacos.naming.serviceName&ip=20.18.7.10&port=8080' + ``` + +### 4.2. 服务发现 + + ```powershell + curl -X GET 'http://${cluster-ip}:8848/nacos/v1/ns/instance/list?serviceName=nacos.naming.serviceName' + ``` + +### 4.3. 发布配置 + + ```powershell + curl -X POST "http://${cluster-ip}:8848/nacos/v1/cs/configs?dataId=nacos.cfg.dataId&group=test&content=helloWorld" + ``` + +### 4.4. 获取配置 + + ```powershell + curl -X GET "http://${cluster-ip}:8848/nacos/v1/cs/configs?dataId=nacos.cfg.dataId&group=test" + ``` + +### 4.5. Nacos控制台页面 + +link：`http://${cluster-ip}:8848/nacos/` + +## 相关项目 + +* [Nacos](https://github.com/alibaba/nacos) +* [Nacos Docker](https://github.com/nacos-group/nacos-k8s) \ No newline at end of file diff --git a/src/content/docs/v3.0/en/quickstart/quick-start-native.mdx b/src/content/docs/v3.0/en/quickstart/quick-start-native.mdx new file mode 100644 index 00000000000..f6f759a4573 --- /dev/null +++ b/src/content/docs/v3.0/en/quickstart/quick-start-native.mdx @@ -0,0 +1,69 @@ +--- +title: Nacos Native Quick Start +keywords: [Nacos,Quick Start] +description: This quick start guide is designed to help you quickly download, install, and use Nacos on your computer. +sidebar: + order: 1 +--- + +import { Tabs, TabItem } from '@astrojs/starlight/components'; + +# Nacos Quick Start + +This quick start guide is designed to help you quickly download, install, and use Nacos on your computer. + +:::note +- The quick start guide is intended to assist you in quickly setting up, deploying, and getting started with Nacos. The Nacos service set up via this guide operates in **standalone mode** without **authentication enabled**, and is recommended for testing purposes only. For production environments, it's advised to deploy Nacos in **cluster mode** with **authentication enabled** to mitigate **stability and security risks**. +- Nacos is intended to be used as an internal data center (IDC) application component, not a publicly facing product. It is highly recommended to deploy Nacos within an isolated internal network. **It is strongly discouraged** to deploy Nacos in public network environments. +::: + +## System Requirements +Nacos Native is a version of Nacos built using the GraalVM, and it no longer depends on a separate JDK installation. Nacos Native currently provides executable files for Linux (GNU) and macOS. The current version of Nacos Native corresponds to Java Nacos version 2.4.0. Executable binaries can be downloaded from the corresponding release page. It is recommended to run Nacos Native on a complete 64-bit operating system that includes the `libstdc++` library. + +## Download and Extract the Package +After downloading the program package from the appropriate page, extract it and verify the files: + +1. On Linux operating systems, the extracted files should include the `nacos-server` binary, the `libinstrument.so` symlink, and other related configurations. +2. On macOS, the extracted files should include the `nacos-server` binary and other related configurations. + +If a Nacos Native version for other operating systems is not available, you can manually compile the source code on that operating system to obtain the Nacos Native binary package. + +## Starting the Server +It is recommended to run Nacos Native on a machine with at least 1 CPU core, 2 GB of RAM, and 60 GB of storage. On Linux/Unix/macOS, you can start Nacos Native using the following command: + +```shell +# standalone means running in single-node mode, not cluster mode +sh startup.sh -m standalone +``` + +If you want to start Nacos Native in cluster mode, make sure to have a `cluster.conf` file in the `conf` directory. This process is the same as with Java Nacos. After starting Nacos Native in cluster mode, it will automatically scan and retrieve the cluster IP addresses. + +## Stopping the Server +To stop the Nacos Native server on Linux/Unix/macOS, use the following command: + +```shell +sh shutdown.sh +``` + +## Viewing Logs +For Linux/Unix operating systems, Nacos Native's runtime logs are recorded in the `/root/nacos/logs` directory. The log structure is consistent with that of Java Nacos. + +## Building Native Nacos +Nacos Native provides build configurations for different operating systems. You can quickly build the Nacos Native executable for a specific OS using Maven. Follow the instructions below to build Nacos Native: + +```shell +# Build Native Nacos for Windows x64 +mvn clean install -DskipTests=true -Pnative -Pnative-win64 +# Build Native Nacos for macOS x86_64 +mvn clean install -DskipTests=true -Pnative -Pnative-osx-x86_64 +# Build Native Nacos for Linux x64 +mvn clean install -DskipTests=true -Pnative -Pnative-linux64 +``` + +The `-Pnative` configuration provides the basic native build settings, while `-Pnative-控制台
提供了精简Web操作控制台,支持国际化:
+ +### 同步任务管理页面 + + +### 注册中心管理页面 + +##  + +## 使用场景: +* 多个网络互通的Region之间服务共享,打破Region之间的服务调用限制 + + + +* 双向同步功能,支持Dubbo+Zookeeper服务平滑迁移到Dubbo+Nacos,享受Nacos更加优质的服务 + + + +# 使用流程 + +## 准备工作 +启动服务之前，你需要安装下面的服务： +* 64bit OS: Linux/Unix/Mac/Windows supported, Linux/Unix/Mac recommended. +* 64bit JDK 1.8+: [downloads](http://www.oracle.com/technetwork/java/javase/downloads/jdk8-downloads-2133151.html), [JAVA_HOME settings](https://docs.oracle.com/cd/E19182-01/820-7851/inst_cli_jdk_javahome_t/). +* Maven 3.2.x+: [downloads](https://maven.apache.org/download.cgi), [settings](https://maven.apache.org/settings.html). +* MySql 5.6.+ + +## 获取安装包 +有两种方式可以获得 NacosSync 的安装包： +* 直接下载 NacosSync 的二进制安装包：[nacosSync.${version}.zip](https://github.com/nacos-group/nacos-sync/releases) +* 从 GitHub 上下载 NacosSync 的源码进行构建 + +Package: +```basic +cd nacosSync/ +mvn clean package -U +``` + +目标文件的路径： +```basic +nacos-sync/nacossync-distribution/target/nacosSync.${version}.zip +``` + +解压安装包之后,工程的文件目录结构： +```basic +nacosSync +├── LICENSE +├── NOTICE +├── bin +│ ├── nacosSync.sql +│ ├── shutdown.sh +│ └── startup.sh +├── conf +│ ├── application.properties +│ └── logback-spring.xml +├── logs +└── nacosSync-server.${version}.jar +``` + +## 初始化数据库 + +系统默认配置的数据库是Mysql，也能支持其他的关系型数据库。 +1.建库，缺省的数据库名字为“nacos_Sync”。 +2.数据库表不需要单独创建，默认使用了hibernate的自动建表功能。 +3.如果你的环境不支持自动建表，可以使用系统自带的sql脚本建表，脚本放在bin目录下。 + +## 数据库配置 + +数据库的配置文件放在`conf/application.properties`中： +```basic +spring.datasource.url=jdbc:mysql://127.0.0.1:3306/nacos_sync?characterEncoding=utf8 +spring.datasource.username=root +spring.datasource.password=root +``` + +## 启动服务器 + +```bash +$ nacosSync/bin: +sh startup.sh restart +``` + +## 检查系统状态 + +1.检查系统日志 + +日志的路径在`nacosSync/logs/nacosSync.log`，检查是否有异常信息。 + +2.检查系统端口 + +缺省的系统端口是`8081`，你可以自己定义在`application.properties`中。 + +```bash +$netstat -ano|grep 8081 +tcp 0 0 0.0.0.0:8081 0.0.0.0:* LISTEN off (0.00/0/0) +``` + +## 控制台 + +访问路径： +``` +http://127.0.0.1:8081/#/serviceSync +``` + + +如果检查没有问题，NacosSync 已经正常启动了，NacosSync 的部署结构： + +## 开始迁移 + +### 迁移信息 + +Dubbo服务的部署信息： + +迁移的服务： + +| Service Name | Version | Group Name | +| --- | --- | --- | +| com.alibaba.nacos.api.DemoService | 1.0.0 | zk | + +### 添加注册中心集群信息 + +1.点击左侧导航栏中的“集群配置”按钮，新增加一个集群，先增加一个Zookeeper集群，选择集群类型为ZK。 + + +> 注意：集群名字可以自定义，但是一旦确认，不能被修改，否则基于此集群增加的任务，在 NacosSync 重启后，将不会恢复成功。 + +2.同样的步骤，增加Nacos集群。 + + +3.添加完成后，可以在列表中查询到： + + +### 添加同步任务 + +1.增加一个同步任务，从Zookeeper集群同步到Nacos集群，同步的粒度是服务，Zookeeper集群则称为源集群，Nacos集群称为目标集群。 + + +添加完成之后，可以在服务同步列表中，查看已添加的同步任务： + + +2.同步完成之后，检查下数据是否同步成功到Nacos集群，可以通过Nacos的控制台进行查询。 + + +3.此刻，数据已经成功从Zookeeper集群同步到了Nacos集群，部署结构如下： + + +### Dubbo 客户端连接到 Nacos 注册中心 + +#### Dubbo Consumer客户端迁移 + +Dubbo 已经支持Nacos注册中心，支持的版本为2.5+，需要增加一个Nacos注册中心的Dubbo扩展插件依赖： +```basic +
Nacos是什么
+ +Nacos 致力于帮助您发现、配置和管理微服务。Nacos 提供了一组简单易用的特性集，帮助您快速实现动态服务发现、服务配置、服务元数据及流量管理。详情可以参考[Nacos官网介绍](../../what-is-nacos.md)。 + +Nacos如何支持多环境
+ +在日常使用中常常需要不同的环境，比如日常，预发，线上环境，如果是逻辑隔离可以使用命名空间，Nacos支持命名空间来支持多环境隔离，可以在Nacos控制台创建多个命名空间。如果需要物理隔离，就要部署多套Nacos环境。 + +Nacos是否生产可用
+ +Nacos在2019.1发布了Pre-GA版本，支持了安全隔离、监控和服务迁移等上生产的最后一公里，以更稳定的支撑用户的生产环境。详情可以参考[Nacos 发布 v0.8.0 Pre-GA 版本，安全稳定上生产](https://www.oschina.net/news/104019/nacos-0-8-0-pre-ga)。 + +Nacos有什么依赖
+ +在单机模式下，Nacos没有任何依赖，在集群模式下，Nacos依赖Mysql做存储，详情可以参考[Nacos部署](../admin/deployment.md)。 + +Nacos使用什么开源协议
+ +Nacos使用[Apache 2.0](https://github.com/alibaba/nacos/blob/master/LICENSE)。 + +## Nacos运维问题 +Nacos如何单机部署
+ +可以参考Nacos官网部署手册[quick start](../../quickstart/quick-start.mdx)。 + +Nacos单机部署如何使用mysql
+ +Nacos单机模式默认使用内嵌的数据库作为存储引擎，如果想换成自己安装的mysql，可以按照[官网文档](../admin/deployment.md)。 + +生产环境如何部署Nacos
+ +生产环境使用Nacos为了达到高可用不能使用单机模式，需要搭建nacos集群，具体详情可以参考[集群部署手册](../admin/cluster-mode-quick-start.md)。 + +Nacos如何Docker部署
+ +除了使用压缩包部署Nacos，Nacos也提供了相应的Docker镜像，当Nacos发布新的版本的时候，Nacos会发布对应的镜像版本支持Docker部署。具体详情可以参考[Nacos Docker](../../quickstart/quick-start-docker.mdx)。 + +如何在k8s中部署Nacos
+ +在生产环境部署Nacos集群，如果要对Nacos进行扩容操作，需要手动更改集群ip文件，启动新的Nacos服务。为了能进行自动化运维，Nacos和k8s结合利用StatefulSets提供了自动运维方案，能对Nacos进行动态扩缩容，具体详情参考[Kubernetes Nacos](https://github.com/nacos-group/nacos-k8s/blob/master/README-CN.md)。 + +如何监控Nacos
+ +Nacos0.8版本提供了Metrics数据暴露能力，能通过Metrics数据的内容对Nacos的运行状态进行监控，详情参考[Nacos监控](../admin/monitor-guide.md)。 + +Nacos在Docker环境下集群部署，无法正常启动，日志一直打印 Nacos is starting...
+ +原因可能是由于Docker环境下，内存不足导致另外的服务无法正常启动，最后导致服务报错，一直重启，可以通过增大Docker限制内存尝试解决。 + +## Nacos使用问题 +Zookeeper上的服务可以迁移到Nacos上吗
+ +可以通过Nacos-Sync把Zookeeper服务迁移到Nacos，也可以从Nacos迁移到Zookeeper，具体可以参考[Nacos Sync 使用](https://github.com/paderlol/nacos-sync-example)。 + +Nacos支持多配置文件
+ +Nacos通过Spring Cloud Alibaba Nacos Config支持了多配置文件，可以将配置存储在多个独立的配置文件中。关联的[issue](https://github.com/alibaba/nacos/issues/320)，详情参考文档[Spring Cloud Alibaba Nacos Config](https://github.com/spring-cloud-incubator/spring-cloud-alibaba/wiki/Nacos-config)。 + +Nacos支持Dubbo
+ +Nacos 0.6版本和Dubbo集成，支持使用Nacos作为注册中心，关联[issue](https://github.com/alibaba/nacos/issues/390),具体文档参考 [Dubbo 融合 Nacos 成为注册中心](../../ecology/use-nacos-with-dubbo.md) 。 + +Nacos支持Spring体系
+ +Nacos完善支持了Sping技术栈，具体可以参考[Nacos Spring](../../ecology/use-nacos-with-spring.md)、[Nacos Spring Boot](../../ecology/use-nacos-with-spring-boot.md)、[Spring Cloud](../../ecology/use-nacos-with-spring-cloud.md)。 + +不使用Nacos SDK如何访问Nacos
+ +Nacos的网络交互都是基于Http协议实现的，提供了[Open-API](./open-api.md)可以很容易实现Nacos的访问。 + +Nacos对多语言的支持
+ +Nacos目前只支持Java，对于其他语言的支持还正在开发中，需要大家大力支持一起共建。 + +Nacos0.8版本登陆失败
+ +Nacos 0.8版本当使用openjdk并且没有`JAVA_HOME`的环境变量时，nacos可以启动成功，是因为`yum install`安装的openjdk 会把java命令注册一份到`/bin`目录下面,所以会引发`SignatureException`异常。这个问题已经修复，0.9版本会发版，具体详情可以参考[issue](https://github.com/alibaba/nacos/issues/711)。 + +服务端报错 java.lang.IllegalStateException: unable to find local peer: 127.0.0.1:8848
+ +这个问题是因为Nacos获取本机IP时,没有获取到正确的外部IP.需要保证`InetAddress.getLocalHost().getHostAddress()`或者`hostname -i`的结果是与cluster.conf里配置的IP是一致的。 + +Nacos如何对配置进行加密
+ +Nacos计划在1.X版本提供加密的能力，目前还不支持加密，只能靠sdk做好了加密再存到nacos中。 + +Nacos报401错误
+ +Nacos服务端报错了，可以检查服务端日志，参考[issue](https://github.com/alibaba/nacos/issues/816)。 + +Nacos权重不生效
+ +Nacos控制台上编辑权重, 目前从SpringCloud客户端和Dubbo客户端都没有打通, 所以不能生效. 对于SpringCloud客户端, 应用可以实现Ribbon的负载均衡器来进行权重过滤。 + +Nacos如何扩缩容
+ +目前支持修改cluster.conf文件的方式进行扩缩容, 改完后无需重启, Server会自动刷新到文件新内容。 + +Nacos客户端修改日志级别
+ +配置-D参数com.alibaba.nacos.naming.log.level设置naming客户端的日志级别，例如设置为error： +`-Dcom.alibaba.nacos.naming.log.level=error` +同样的，-D参数com.alibaba.nacos.config.log.level用来设置config客户端的日志级别。 + +Nacos与Zipkin 整合出现 Service not found 问题
+ +配置`spring-cloud-seluth`参数：`spring.zipkin.discovery-client-enabled=false`。 + +如果仍然存在`Service not found`错误，则建议先使用open-api将Zipkin-server注册为永久实例服务： + +`curl -X POST 'http://127.0.0.1:8848/nacos/v1/ns/instance?port=9411&healthy=true&ip=127.0.0.1&weight=1.0&serviceName=zipkin-server&ephemeral=false&namespaceId=public'` + +然后，前往nacos控制台，找到服务名为`zipkin-server`的服务，找到集群配置，设置健康检查模式为`TCP`，端口号为`9411`(即zipkin-server的端口)。 + + +如何依赖最新的Nacos客户端？
+很多用户都是通过Spring Cloud Alibaba或者Dubbo依赖的Nacos客户端，那么Spring Cloud Alibaba和Dubbo中依赖的Nacos客户端版本，往往会落后于Nacos最新发布的版本。在一些情况下，用户需要强制将Nacos客户端升级到最新，此时却往往不知道该升级哪个依赖，这里将Spring Cloud Alibaba和Dubbo的依赖升级说明如下： + + +##### Spring Cloud Alibaba + +用户通常是配置以下Maven依赖来使用的Nacos： + +```xml + +客户端CPU高，或者内存耗尽的问题
+问题的现象是依赖Nacos客户端的应用，在运行一段时间后出现CPU占用率高，内存占用高甚至内存溢出的现象，可以参考issue：[https://github.com/alibaba/nacos/issues/1605](https://github.com/alibaba/nacos/issues/1605)。这种情况首先要做的是分析CPU高或者内存占用高的原因，常用的命令有top、jstack、jmap、jhat等。其中一种情况是Nacos客户端实例在Spring Cloud Alibaba服务框架中被反复构造了多次，可以参考issue：[https://github.com/alibaba/spring-cloud-alibaba/issues/859](https://github.com/alibaba/spring-cloud-alibaba/issues/859)。这个问题已经得到了修复，预期会在下个Spring Cloud Alibaba版本中发布。 + + +日志打印频繁的问题
+在老的Nacos版本中，往往会有大量的无效日志打印，这些日志的打印会迅速占用完用户的磁盘空间，同时也让有效日志难以查找。目前社区反馈的日志频繁打印主要有以下几种情况： + +1. access日志大量打印，相关issue有：[https://github.com/alibaba/nacos/issues/1510](https://github.com/alibaba/nacos/issues/1510)。主要表现是{nacos.home}/logs/access_log.2019-xx-xx.log类似格式文件名的日志大量打印，而且还不能自动清理和滚动。这个日志是Spring Boot提供的tomcat访问日志打印，Spring Boot在关于该日志的选项中，没有最大保留天数或者日志大小控制的选项。因此这个日志的清理必须由应用新建crontab任务来完成，或者通过以下命令关闭日志的输出（在生产环境我们还是建议开启该日志，以便能够有第一现场的访问记录）： + +``` +server.tomcat.accesslog.enabled=false +``` + +2. 服务端业务日志大量打印且无法动态调整日志级别。这个问题在1.1.3已经得到优化，可以通过API的方式来进行日志级别的调整，调整日志级别的方式如下： + +``` +# 调整naming模块的naming-raft.log的级别为error: +curl -X PUT '$nacos_server:8848/nacos/v1/ns/operator/log?logName=naming-raft&logLevel=error' +# 调整config模块的config-dump.log的级别为warn: +curl -X PUT '$nacos_server:8848/nacos/v1/cs/ops/log?logName=config-dump&logLevel=warn' +``` + +3. 客户端日志大量打印，主要有心跳日志、轮询日志等。这个问题已经在1.1.3解决，请升级到1.1.3版本。 + + +集群管理页面，raft term显示不一致问题
+在Nacos 1.0.1版本中，Nacos控制台支持了显示当前的集群各个机器的状态信息。这个功能受到比较多用户的关注，其中一个被反馈的问题是列表中每个节点的集群任期不一样。如下图所示（图片信息来自issue：https://github.com/alibaba/nacos/issues/1786）： + + + +对于这个任期不一致的问题，原因主要是因为获取这个信息的逻辑有一些问题，没有从对应的节点上获取集群任期。这个问题会在下一个Nacos版本中修复。目前一个手动检查集群任期的办法是在每个节点上执行以下命令： + +``` +curl '127.0.0.1:8848/nacos/v1/ns/raft/state' +``` + +然后在返回信息中查找本节点的集群任期。因为每个节点返回的集群任期中，只有当前节点的信息是准确的，返回的其他节点的信息都是不准确的。 + +找不到符号`com.alibaba.nacos.consistency.entity`
+ +这个包目录是由`protobuf`在编译时自动生成，您可以通过`mvn compile`来自动生成他们。如果您使用的是IDEA，也可以使用IDEA的protobuf插件。 + +启动报错java.lang.IllegalArgumentException: the length of secret key must great than or equal 32 bytes...
+启动报错java.lang.IllegalArgumentException: The specified key byte array is x bits which is not secure enough for any JWT HMAC-SHA algorithm.
+ +默认鉴权插件需要密钥来生成访问token，密钥格式需要长度大于32。若`secret.key`进行BASE64解密后的长度小于32，则会在启动过程中此错误。 +您可以在`application.properties`中设置正确的`secret.key`，详情见[用户指南-权限认证](./auth.md). + +启动报错Empty identity, Please set `nacos.core.auth.server.identity.key` and `nacos.core.auth.server.identity.value`
+ +2.2.1后的版本，移除了配置中间中`nacos.core.auth.server.identity.key` 和 `nacos.core.auth.server.identity.value`的默认值，并添加了启动校验。 +如果在开启鉴权但未设置`nacos.core.auth.server.identity.key` 和 `nacos.core.auth.server.identity.value`的情况下，nacos server会提示以上报错信息，并阻止启动。 +可查看[用户指南-权限认证](./auth.md)文档中相关内容，进行设置后启动。 + +## Nacos原理问题 diff --git a/src/content/docs/v3.0/zh-cn/guide/user/open-api.md b/src/content/docs/v3.0/zh-cn/guide/user/open-api.md new file mode 100644 index 00000000000..2757333a7b2 --- /dev/null +++ b/src/content/docs/v3.0/zh-cn/guide/user/open-api.md @@ -0,0 +1,2531 @@ +--- +title: Open API 指南 +keywords: [Open API,指南] +description: Open API 指南 +sidebar: + order: 3 +--- + +> 该文档即将废弃，请参考[用户手册-OpenAPI指南](../../manual/user/open-api.md)，部分接口被定义为运维API，请参考[运维手册-运维API](../../manual/admin/admin-api.md)。 + +# Open API 指南 + +Nacos 2.X 版本兼容 Nacos1.X 版本的OpenAPI, 请参考文档[Nacos1.X OpenAPI](https://nacos.io/docs/v1/open-api)使用。 + +> 注意：未特殊注明支持版本的OpenAPI均从2.2.0版本开始支持。 + +- 文档约定 + - [API 统一返回体格式](#0.1) + - [API 错误码汇总](#0.2) + +- 配置管理 + - [获取配置](#1.1) + - [发布配置](#1.2) + - [删除配置](#1.3) + - [查询配置历史版本列表](#1.4) + - [查询具体版本的历史配置](#1.5) + - [查询配置上一版本信息](#1.6) + - [查询指定命名空间下的配置列表](#1.7) +- 服务发现 + - [注册实例](#2.1) + - [注销实例](#2.2) + - [更新实例](#2.3) + - [查询实例详情](#2.4) + - [查询指定服务下的实例列表](#2.5) + - [批量更新实例元数据(Beta)](#2.6) + - [批量删除实例元数据(Beta)](#2.7) + - [创建服务](#2.8) + - [删除服务](#2.9) + - [修改服务](#2.10) + - [查询服务详情](#2.11) + - [查询服务列表](#2.12) + - [查询系统开关](#2.13) + - [修改系统开关](#2.14) + - [查看系统当前数据指标](#2.15) + - [更新实例的健康状态](#2.16) + - [查询客户端列表（新）](#2.17) + - [查询客户端信息（新）](#2.18) + - [查询客户端的注册信息（新）](#2.19) + - [查询客户端的订阅信息（新）](#2.20) + - [查询注册指定服务的客户端信息（新）](#2.21) + - [查询订阅指定服务的客户端信息（新）](#2.22) +- 命名空间 + - [查询命名空间列表](#3.1) + - [查询具体命名空间](#3.2) + - [新增命名空间](#3.3) + - [编辑命名空间](#3.4) + - [删除命名空间](#3.5) +- 集群管理 + - [查询当前节点信息](#4.1) + - [查询集群节点列表](#4.2) + - [查询当前节点健康状态](#4.3) + - [切换寻址模式](#4.4) + +## 文档规定 + +API 统一返回体格式
+ +2.0版本Open API，所有接口请求的响应均为`json`类型的返回体，返回体具有相同的格式 + +```json +{ + "code": 0, + "message": "success", + "data": {} +} +``` + +返回体中各字段的含义如下表所示 + +| 名称 | 类型 | 描述 | +|:---------:|:--------:|--------------------------------------------------------| +| `code ` | `int` | 错误码，`0`代表执行成功，非`0`代表执行失败的某一种情况 | +| `message` | `String` | 错误码提示信息，执行成功为"`success`" | +| `data` | 任意类型 | 返回数据，执行失败时为详细出错信息 | + +> 由于执行成功的情况下code字段与message字段相同，后续在介绍接口的返回结果时，只介绍返回数据的data字段 + +API 错误码汇总
+ +API接口返回体中的错误码及对应提示信息汇总见下表 + +| 错误码 | 提示信息 | 含义 | +|---------|------------------------------|----------------------------| +| `0` | `success` | 成功执行 | +| `10000` | `parameter missing` | 参数缺失 | +| `10001` | `access denied` | 访问拒绝 | +| `10002` | `data access error` | 数据访问错误 | +| `20001` | `'tenant' parameter error` | `tenant`参数错误 | +| `20002` | `parameter validate error` | 参数验证错误 | +| `20003` | `MediaType Error` | 请求的`MediaType`错误 | +| `20004` | `resource not found` | 资源未找到 | +| `20005` | `resource conflict` | 资源访问冲突 | +| `20006` | `config listener is null` | 监听配置为空 | +| `20007` | `config listener error` | 监听配置错误 | +| `20008` | `invalid dataId` | 无效的`dataId`（鉴权失败） | +| `20009` | `parameter mismatch` | 请求参数不匹配 | +| `21000` | `service name error` | `serviceName`服务名错误 | +| `21001` | `weight error` | `weight`权重参数错误 | +| `21002` | `instance metadata error` | 实例`metadata`元数据错误 | +| `21003` | `instance not found` | `instance`实例不存在 | +| `21004` | `instance error` | `instance`实例信息错误 | +| `21005` | `service metadata error` | 服务`metadata`元数据错误 | +| `21006` | `selector error` | 访问策略`selector`错误 | +| `21007` | `service already exist` | 服务已存在 | +| `21008` | `service not exist` | 服务不存在 | +| `21009` | `service delete failure` | 存在服务实例，服务删除失败 | +| `21010` | `healthy param miss` | `healthy`参数缺失 | +| `21011` | `health check still running` | 健康检查仍在运行 | +| `22000` | `illegal namespace` | 命名空间`namespace`不合法 | +| `22001` | `namespace not exist` | 命名空间不存在 | +| `22002` | `namespace already exist` | 命名空间已存在 | +| `23000` | `illegal state` | 状态`state`不合法 | +| `23001` | `node info error` | 节点信息错误 | +| `23002` | `node down failure` | 节点离线操作出错 | +| ... | ... | ... | +| 30000 | `server error` | 其他内部错误 | + +## 配置管理 + +获取配置
+ +### 接口描述 + +获取指定配置 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/cs/config` + +### 请求参数 + +| 参数名 | 类型 | 必填 | 参数描述 | +|---------------|----------|--------|--------------------------| +| `namespaceId` | `String` | 否 | 命名空间，默认为`public`与 `''`相同 | +| `group` | `String` | **是** | 配置分组名 | +| `dataId` | `String` | **是** | 配置名 | +| `tag` | `String` | 否 | 标签 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|----------|----------| +| `data` | `String` | 配置内容 | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/config?dataId=nacos.example&group=DEFAULT_GROUP&namespaceId=public' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": "contentTest" + } + ``` + +发布配置
+ +### 接口描述 + +发布指定配置 + +> 当配置已存在时，则对配置进行更新 + +### 请求方式 + +`POST` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/cs/config` + +### 请求Body + +| 参数名 | 类型 | 必填 | 参数描述 | +|---------------|----------|--------|--------------------------------| +| `namespaceId` | `String` | 否 | 命名空间，默认为`public`与 `''`相同 | +| `group` | `String` | **是** | 配置组名 | +| `dataId` | `String` | **是** | 配置名 | +| `content` | `String` | **是** | 配置内容 | +| `tag` | `String` | 否 | 标签 | +| `appName` | `String` | 否 | 应用名 | +| `srcUser` | `String` | 否 | 源用户 | +| `configTags` | `String` | 否 | 配置标签列表，可多个，逗号分隔 | +| `desc` | `String` | 否 | 配置描述 | +| `use` | `String` | 否 | - | +| `effect` | `String` | 否 | - | +| `type` | `String` | 否 | 配置类型 | +| `schema` | `String` | 否 | - | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'dataId=nacos.example' \ + -d 'group=DEFAULT_GROUP' \ + -d 'namespaceId=public' \ + -d 'content=contentTest' \ + -X POST 'http://127.0.0.1:8848/nacos/v2/cs/config' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +删除配置
+ +### 接口描述 + +删除指定配置 + +### 请求方式 + +`DELETE` + +### 请求URL + +`/nacos/v2/cs/config` + +### 请求参数 + +| 参数名 | 类型 | 必填 | 参数描述 | +|---------------|----------|--------|--------------------------| +| `namespaceId` | `String` | 否 | 命名空间，默认为`public`与 `''`相同 | +| `group` | `String` | **是** | 配置分组名 | +| `dataId` | `String` | **是** | 配置名 | +| `tag` | `String` | 否 | 标签 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -X DELETE 'http://127.0.0.1:8848/nacos/v2/cs/config?dataId=nacos.example&group=DEFAULT_GROUP&namespaceId=public' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +查询配置历史列表
+ +### 接口描述 + +获取指定配置的历史版本列表 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/cs/history/list` + +### 请求参数 + +| 参数名 | 类型 | 必填 | 参数描述 | +|---------------|----------|--------|------------------------------------| +| `namespaceId` | `String` | 否 | 命名空间，默认为`public`与 `''`相同 | +| `group` | `String` | **是** | 配置分组名 | +| `dataId` | `String` | **是** | 配置名 | +| `pageNo` | `int` | 否 | 当前页，默认为`1` | +| `pageSize` | `int` | 否 | 页条目数，默认为`100`，最大为`500` | + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|-----------------------|------------|----------------------------------------------------------| +| `data` | `Object` | 分页查询结果 | +| `data.totalCount` | `int` | 总数 | +| `data.pageNumber` | `int` | 当前页 | +| `data.pagesAvailable` | `int` | 总页数 | +| `data.pageItems` | `Object[]` | 历史配置项列表，参见[历史配置项信息](#ConfigHistoryInfo) | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history/list?dataId=nacos.example&group=com.alibaba.nacos&namespaceId=' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "totalCount": 1, + "pageNumber": 1, + "pagesAvailable": 1, + "pageItems": [ + { + "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" + } + ] + } + } + ``` + +查询具体版本的历史配置
+ +### 接口描述 + +获取指定版本的历史配置 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/cs/history` + +### 请求参数 + +| 参数名 | 类型 | 必填 | 参数描述 | +|---------------|----------|--------|------------------------| +| `namespaceId` | `String` | 否 | 命名空间，默认为`public`与 `''`相同 | +| `group` | `String` | **是** | 配置分组名 | +| `dataId` | `String` | **是** | 配置名 | +| `nid` | `long` | **是** | 历史配置id | + +返回数据
+ +| 参数名 | 参数类型 | 描述说明 | +|-------------------------|----------|------------| +| `data` | `Object` | 历史配置项 | +| `data.id` | `String` | 配置`id` | +| `data.lastId` | `int` | | +| `data.dataId` | `String` | 配置名 | +| `data.group` | `String` | 配置分组 | +| `data.tenant` | `String` | 租户信息（命名空间） | +| `data.appName` | `String` | 应用名 | +| `data.md5` | `String` | 配置内容的md5值 | +| `data.content` | `String` | 配置内容 | +| `data.srcIp` | `String` | 源ip | +| `data.srcUser` | `String` | 源用户 | +| `data.opType` | `String` | 操作类型 | +| `data.createdTime` | `String` | 创建时间 | +| `data.lastModifiedTime` | `String` | 上次修改时间 | +| `data.encryptedDataKey` | `String` | | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history?dataId=nacos.example&group=com.alibaba.nacos&namespaceId=&nid=203' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "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" + } + } + ``` + +查询配置上一版本信息
+ +### 接口描述 + +获取指定配置的上一版本 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/cs/history/previous` + +### 请求参数 + +| 参数名 | 类型 | 必填 | 参数描述 | +|---------------|----------|--------|------------------------| +| `namespaceId` | `String` | 否 | 命名空间，默认为`public`与 `''`相同 | +| `group` | `String` | **是** | 配置分组名 | +| `dataId` | `String` | **是** | 配置名 | +| `id` | `long` | **是** | 配置id | + +返回数据
+ +| 参数名 | 参数类型 | 描述说明 | +|--------|----------|------------------------------------------------------| +| `data` | `Object` | 历史配置项，参见[历史配置项信息](#ConfigHistoryInfo) | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history/previous?id=309135486247505920&dataId=nacos.example&group=com.alibaba.nacos&namespaceId=' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "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" + } + } + ``` + +查询指定命名空间下的配置列表
+ +### 接口描述 + +获取指定命名空间下的配置信息列表 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/cs/history/configs` + +### 请求参数 + +| 参数名 | 类型 | 必填 | 参数描述 | +|---------------|----------|--------|----------| +| `namespaceId` | `String` | **是** | 命名空间 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|-------------------------|------------|----------------------| +| `data` | `Object[]` | 配置信息列表 | +| `data.id` | `String` | 配置`id` | +| `data.dataId` | `String` | 配置名 | +| `data.group` | `String` | 配置分组 | +| `data.content` | `String` | 配置内容 | +| `data.md5` | `String` | 配置内容的md5值 | +| `data.encryptedDataKey` | `String` | | +| `data.tenant` | `String` | 租户信息（命名空间） | +| `data.appName` | `String` | 应用名 | +| `data.type` | `String` | 配置文件类型 | +| `data.lastModified` | `long` | 上次修改时间 | + +> 返回数据中的配置信息只有`dataId`, `group`, `tenant`, `appName`, `type`字段有效，其他字段为默认值 + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/cs/history/configs?namespaceId=' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "id": "0", + "dataId": "nacos.example", + "group": "com.alibaba.nacos", + "content": null, + "md5": null, + "encryptedDataKey": null, + "tenant": "", + "appName": "", + "type": "yaml", + "lastModified": 0 + } + ] + } + ``` + +## 服务发现 + +注册实例
+ +### 接口描述 + +注册一个实例 + +### 请求方式 + +`POST` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/ns/instance` + +### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|------------------|----------|----------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `ip` | `String` | **是** | `IP`地址 | +| `port` | `int` | **是** | 端口号 | +| `clusterName` | `String` | 否 | 集群名称，默认为`DEFAULT` | +| `healthy` | `boolean` | 否 | 是否只查找健康实例，默认为`true` | +| `weight` | `double` | 否 | 实例权重，默认为`1.0` | +| `enabled` | `boolean` | 否 | 是否可用，默认为`true` | +| `metadata` | `JSON格式String` | 否 | 实例元数据 | +| `ephemeral` | `boolean` | 否 | 是否为临时实例 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'serviceName=test_service' \ + -d 'ip=127.0.0.1' \ + -d 'port=8090' \ + -d 'weight=0.9' \ + -d 'ephemeral=true' \ + -X POST 'http://127.0.0.1:8848/nacos/v2/ns/instance' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +注销实例
+ +### 接口描述 + +注销指定实例 + +### 请求方式 + +`DELETE` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/ns/instance` + +### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|------------------|----------|----------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `ip` | `String` | **是** | `IP`地址 | +| `port` | `int` | **是** | 端口号 | +| `clusterName` | `String` | 否 | 集群名称，默认为`DEFAULT` | +| `healthy` | `boolean` | 否 | 是否只查找健康实例，默认为`true` | +| `weight` | `double` | 否 | 实例权重，默认为`1.0` | +| `enabled` | `boolean` | 否 | 是否可用，默认为`true` | +| `metadata` | `JSON格式String` | 否 | 实例元数据 | +| `ephemeral` | `boolean` | 否 | 是否为临时实例 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'serviceName=test_service' \ + -d 'ip=127.0.0.1' \ + -d 'port=8090' \ + -d 'weight=0.9' \ + -d 'ephemeral=true' \ + -X DELETE 'http://127.0.0.1:8848/nacos/v2/ns/instance' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +更新实例
+ +### 接口描述 + +修改实例信息 + +> 通过该接口更新的元数据拥有更高的优先级，且具有记忆能力；会在对应实例删除后，依旧存在一段时间，如果在此期间实例重新注册，该元数据依旧生效；您可以通过`nacos.naming.clean.expired-metadata.expired-time`及`nacos.naming.clean.expired-metadata.interval`对记忆时间进行修改 + +### 请求方式 + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/ns/instance` + +### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|------------------|----------|----------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `ip` | `String` | **是** | `IP`地址 | +| `port` | `int` | **是** | 端口号 | +| `clusterName` | `String` | 否 | 集群名称，默认为`DEFAULT` | +| `healthy` | `boolean` | 否 | 是否只查找健康实例，默认为`true` | +| `weight` | `double` | 否 | 实例权重，默认为`1.0` | +| `enabled` | `boolean` | 否 | 是否可用，默认为`true` | +| `metadata` | `JSON格式String` | 否 | 实例元数据 | +| `ephemeral` | `boolean` | 否 | 是否为临时实例 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'serviceName=test_service' \ + -d 'ip=127.0.0.1' \ + -d 'port=8090' \ + -d 'weight=0.9' \ + -d 'ephemeral=true' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/instance' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +查询实例详情
+ +### 接口描述 + +查询某个具体实例的详情信息 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/ns/instance` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|----------|----------|-------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `clusterName` | `String` | 否 | 集群名称，默认为`DEFAULT` | +| `ip` | `String` | **是** | `IP`地址 | +| `port` | `int` | **是** | 端口号 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|--------------------|-----------|--------------| +| `data` | `Object` | 实例详情信息 | +| `data.serviceName` | `String` | 服务名 | +| `data.ip` | `String` | `IP`地址 | +| `data.port` | `int` | 端口号 | +| `data.clusterName` | `String` | 集群名称 | +| `data.weight` | `double` | 实例权重 | +| `data.healthy` | `boolean` | 是否健康 | +| `data.instanceId` | `String` | 实例`id` | +| `data.metadata` | `map` | 实例元数据 | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/instance?namespaceId=public&groupName=&serviceName=test_service&ip=127.0.0.1&port=8080' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "serviceName": "DEFAULT_GROUP@@test_service", + "ip": "127.0.0.1", + "port": 8080, + "clusterName": "DEFAULT", + "weight": 1.0, + "healthy": true, + "instanceId": null, + "metadata": { + "value": "1" + } + } + } + ``` + +查询指定服务的实例列表
+ +### 接口描述 + +查询指定服务下的实例详情信息列表 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/ns/instance/list` + +### 请求头 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|------------------|----------|----------|----------------------| +| `User-Agent` | `String` | 否 | 用户代理，默认为空 | +| `Client-Version` | `String` | 否 | 客户端版本，默认为空 | + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|-----------|----------|----------------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `clusterName` | `String` | 否 | 集群名称，默认为`DEFAULT` | +| `ip` | `String` | 否 | `IP`地址，默认为空，表示不限制`IP`地址 | +| `port` | `int` | 否 | 端口号，默认为`0`，表示不限制端口号 | +| `healthyOnly` | `boolean` | 否 | 是否只获取健康实例，默认为`false` | +| `app` | `String` | 否 | 应用名，默认为空 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|----------------------------------------|------------|-----------| +| `data` | | 指定服务的实例列表 | +| `data.name` | `String` | 分组名@@服务名 | +| `data.groupName` | `String` | 分组名 | +| `data.clusters` | `String` | 集群名 | +| `data.cacheMillis` | `int` | 缓存时间 | +| `data.hosts` | `Object[]` | 实例列表 | +| `data.hosts.ip` | `String` | 实例`IP` | +| `data.hosts.port` | `int` | 实例端口号 | +| `data.hosts.weight` | `double` | 实例权重 | +| `data.hosts.healthy` | `boolean` | 实例是否健康 | +| `data.hosts.enabled` | `boolean` | 实例是否可用 | +| `data.hosts.ephemeral` | `boolean` | 是否为临时实例 | +| `data.hosts.clusterName` | `String` | 实例所在的集群名称 | +| `data.hosts.serviceName` | `String` | 服务名 | +| `data.hosts.metadata` | `map` | 实例元数据 | +| `data.hosts.instanceHeartBeatTimeOut` | `int` | 实例心跳超时时间 | +| `data.hosts.ipDeleteTimeout` | `int` | 实例删除超时时间 | +| `data.hosts.instanceHeartBeatInterval` | `int` | 实例心跳间隔 | +| `data.lastRefTime` | `int` | 上次刷新时间 | +| `data.checksum` | `int` | 校验码 | +| `data.allIPs` | `boolean` | | +| `data.reachProtectionThreshold` | `boolean` | 是否到达保护阈值 | +| `data.valid` | `boolean` | 是否有效 | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/instance/list?serviceName=test_service&ip=127.0.0.1' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "name": "DEFAULT_GROUP@@test_service", + "groupName": "DEFAULT_GROUP", + "clusters": "", + "cacheMillis": 10000, + "hosts": [ + { + "ip": "127.0.0.1", + "port": 8080, + "weight": 1.0, + "healthy": true, + "enabled": true, + "ephemeral": true, + "clusterName": "DEFAULT", + "serviceName": "DEFAULT_GROUP@@test_service", + "metadata": { + "value": "1" + }, + "instanceHeartBeatTimeOut": 15000, + "ipDeleteTimeout": 30000, + "instanceHeartBeatInterval": 5000 + } + ], + "lastRefTime": 1662554390814, + "checksum": "", + "allIPs": false, + "reachProtectionThreshold": false, + "valid": true + } + } + ``` + +批量更新实例元数据
+ +### 接口描述 + +批量更新实例的元数据, + +> 对应元数据的键不存在时，则添加对应元数据 + +### 请求方式 + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/ns/instance/metadata/batch` + +### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|-------------------|------------------|----------|-------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `consistencyType` | `String` | 否 | 持久化类型，默认为空 | +| `instances` | `JSON格式String` | 否 | 需要更新的实例列表，默认为空 | +| `metadata` | `JSON格式String` | **是** | 实例元数据 | + +### 参数说明 + +> - `consistencyType`: 实例的持久化类型，当为‘`persist`’，表示对持久化实例的元数据进行更新；否则表示对临时实例的元数据进行更新 +> - `instances`: 待更新的实例列表，`json`数组，通过`ip+port+ephemeral+cluster`定位到某一实例，为空则表示更新指定服务下所有实例的元数据 + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'serviceName=test_service' \ + -d 'consistencyType=ephemeral' \ + -d '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"}]' \ + -d 'metadata={"age":"20","name":"cocolan"}' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/instance/metadata/batch' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +批量删除实例元数据
+ +### 接口描述 + +批量删除实例的元数据, + +> 对应元数据的键不存在时，则不做操作 + +### 请求方式 + +`DELETE` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/ns/instance/metadata/batch` + +### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|-------------------|------------------|----------|-------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `consistencyType` | `String` | 否 | 持久化类型，默认为空 | +| `instances` | `JSON格式String` | 否 | 需要更新的实例列表，默认为空 | +| `metadata` | `JSON格式String` | **是** | 实例元数据 | + +### 参数说明 + +> - `consistencyType`: 实例的持久化类型，当为‘`persist`’，表示对持久化实例的元数据进行删除；否则表示对临时实例的元数据进行 +> - `instances`: 待更新的实例列表，`json`数组，通过`ip+port+ephemeral+cluster`定位到某一实例，为空则表示更新指定服务下所有实例的元数据 + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'serviceName=test_service' \ + -d 'consistencyType=ephemeral' \ + -d '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"}]' \ + -d 'metadata={"age":"20","name":"cocolan"}' \ + -X DELETE 'http://127.0.0.1:8848/nacos/v2/ns/instance/metadata/batch' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +创建服务
+ +### 接口描述 + +创建一个服务 + +> 服务已存在时会创建失败 + +### 请求方式 + +`POST` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/ns/service` + +### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|--------------------|------------------|----------|-------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `metadata` | `JSON格式String` | 否 | 服务元数据，默认为空 | +| `ephemeral` | `boolean` | 否 | 是否为临时实例，默认为`false` | +| `protectThreshold` | `float` | 否 | 保护阈值，默认为`0` | +| `selector` | `JSON格式String` | 否 | 访问策略，默认为空 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'serviceName=nacos.test.1' \ + -d 'ephemeral=true' \ + -d 'metadata={"k1":"v1"}' \ + -X POST 'http://127.0.0.1:8848/nacos/v2/ns/service' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +删除服务
+ +### 接口描述 + +删除指定服务 + +> 服务不存在时会报错，且服务还存在实例时会删除失败 + +### 请求方式 + +`DELETE` + +### 请求URL + +`/nacos/v2/ns/service` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|----------|----------|-------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -X DELETE 'http://127.0.0.1:8848/nacos/v2/ns/service?serviceName=nacos.test.1' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +修改服务
+ +### 接口描述 + +更新指定服务 + +> 服务不存在时会报错 + +### 请求方式 + +`POST` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/ns/service` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|--------------------|------------------|----------|-------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `metadata` | `JSON格式String` | 否 | 服务元数据，默认为空 | +| `protectThreshold` | `float` | 否 | 保护阈值，默认为`0` | +| `selector` | `JSON格式String` | 否 | 访问策略，默认为空 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'serviceName=nacos.test.1' \ + -d 'metadata={"k1":"v2"}' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/service' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +查询服务详情
+ +### 接口描述 + +查询某个具体服务的详情信息 + +> 服务不存在时会报错 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/ns/service` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|----------|----------|---------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|-------------------------|-----------|----------------| +| `data` | | 服务信息 | +| `data.namespace` | `String` | 命名空间 | +| `data.groupName` | `String` | 分组名 | +| `data.serviceName` | `String` | 服务名 | +| `data.clusterMap` | `map` | 集群信息 | +| `data.metadata` | `map` | 服务元数据 | +| `data.protectThreshold` | `float` | 保护阈值 | +| `data.selector` | `Object` | 访问策略 | +| `data.ephemeral` | `Boolean` | 是否为临时实例 | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/service?serviceName=nacos.test.1' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "namespace": "public", + "serviceName": "nacos.test.1", + "groupName": "DEFAULT_GROUP", + "clusterMap": {}, + "metadata": {}, + "protectThreshold": 0, + "selector": { + "type": "none", + "contextType": "NONE" + }, + "ephemeral": false + } + } + ``` + +查询服务列表
+ +### 接口描述 + +查询符合条件的服务列表 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/ns/service/list` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|------------------|----------|-----------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `selector` | `JSON格式String` | **是** | 访问策略 | +| `pageNo` | `int` | 否 | 当前页，默认为`1` | +| `pageSize` | `int` | 否 | 页条目数，默认为`20`，最大为`500` | + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|-----------------|------------|------------------| +| `data` | | 服务列表信息 | +| `data.count` | `String` | 服务数目 | +| `data.services` | `String[]` | 分页后的服务列表 | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/service/list' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "count": 2, + "services": [ + "nacos.test.1", + "nacos.test.2" + ] + } + } + ``` + +查询系统开关
+ +### 接口描述 + +查询系统开关 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/ns/operator/switches` + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|--------|----------|--------------| +| `data` | `Object` | 系统开关信息 | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/operator/switches' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "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": false, + "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": [], + "name": "00-00---000-NACOS_SWITCH_DOMAIN-000---00-00", + "checksum": null + } + } + ``` + +修改系统开关
+ +### 接口描述 + +修改系统开关 + +### 请求方式 + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/ns/operator/switches` + +### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------|-----------|-------|---------------------------------------------------------| +| `entry` | `String` | **是** | 开关名 | +| `value` | `String` | **是** | 开关值 | +| `debug` | `boolean` | 否 | 是否只在本机生效,`true`表示本机生效,`false`表示集群生效 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|----------|------------------| +| `data` | `String` | “`ok`”表示执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'entry=pushEnabled' \ + -d 'value=false' \ + -d 'debug=true' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/operator/switches' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": "ok" + } + ``` + +查询系统当前数据指标
+ +### 接口描述 + +查询系统当前数据指标 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/ns/operator/metrics` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|--------------|-----------|----------|--------------------------| +| `onlyStatus` | `boolean` | 否 | 只显示状态，默认为`true` | + +> 当`onlyStatus`设置为`true`时，只返回表示系统状态的字符串 + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|------------------------------------|----------|--------------------| +| `data` | `Object` | 系统当前数据指标 | +| `data.status` | `String` | 系统状态 | +| `data.serviceCount` | `int` | 服务数量 | +| `data.instanceCount` | `int` | 实例数量 | +| `data.subscribeCount` | `int` | 订阅数量 | +| `data.raftNotifyTaskCount` | `int` | `Raft`通知任务数量 | +| `data.responsibleServiceCount` | `int` | | +| `data.responsibleInstanceCount` | `int` | | +| `data.clientCount` | `int` | 客户端数量 | +| `data.connectionBasedClientCount` | `int` | 连接数量 | +| `data.ephemeralIpPortClientCount` | `int` | 临时客户端数量 | +| `data.persistentIpPortClientCount` | `int` | 持久客户端数量 | +| `data.responsibleClientCount` | `int` | | +| `data.cpu` | `float` | `cpu`使用率 | +| `data.load` | `float` | 负载 | +| `data.mem` | `float` | 内存使用率 | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/operator/metrics' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "status": "UP", + "serviceCount": 2, + "instanceCount": 2, + "subscribeCount": 2, + "raftNotifyTaskCount": 0, + "responsibleServiceCount": 0, + "responsibleInstanceCount": 0, + "clientCount": 2, + "connectionBasedClientCount": 2, + "ephemeralIpPortClientCount": 0, + "persistentIpPortClientCount": 0, + "responsibleClientCount": 2, + "cpu": 0, + "load": -1, + "mem": 1 + } + } + ``` + +更新实例健康状态
+ +### 接口描述 + +更新实例的健康状态 + +### 请求方式 + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/ns/health/instance` + +### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|-----------|----------|-------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `clusterName` | `String` | 否 | 集群名，默认为`DEFAULT` | +| `ip` | `String` | **是** | `IP`地址 | +| `port` | `int` | **是** | 端口号 | +| `healthy` | `boolean` | **是** | 是否健康 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|----------|--------------------| +| `data` | `String` | “`ok`”表示执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'serviceName=nacos.test.1' \ + -d 'ip=127.0.0.1' \ + -d 'port=8080' \ + -d 'healthy=false' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/ns/health/instance' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": "ok" + } + ``` + +查询客户端列表（新）
+ +### 接口描述 + +查询当前所有的客户端列表 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/ns/client/list` + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|--------|------------|----------------| +| `data` | `String[]` | 客户端`id`列表 | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/list' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": [ + "10.128.164.35:9956#true", + "1664358687402_127.0.0.1_2300", + "1664358642902_127.0.0.1_2229", + "192.168.139.1:49825#true", + "10.128.164.35:9954#true", + "192.168.139.1:53556#true" + ] + } + ``` + +> 对于不同版本的nacos client，建立客户端的方式不同。 +> +> 对于`1.x`版本，每个实例会建立两个基于`ip+port`的客户端，分别对应实例注册与服务订阅，`clientId`格式为 `ip:port#ephemeral` +> +> 对于`2.x`版本的`nacos client`, 每个实例会建立一个`RPC`连接，对应一个基于`RPC`连接的客户端，兼具注册与订阅功能，`clientId` +> 格式为`time_ip_port` + + + +查询客户端信息（新）
+ +### 接口描述 + +查询指定客户端的详细信息 + +> 客户端不存在时会报错 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/ns/client` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|------------|----------|----------|------------| +| `clientId` | `String` | **是** | 客户端`id` | + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|------------------------|-----------|----------------| +| `data` | `Object` | 客户端信息 | +| `data.clientId` | `String` | 客户端`id` | +| `data.ephemeral` | `boolean` | 是否为临时实例 | +| `data.lastUpdatedTime` | `int` | 上次更新时间 | +| `data.clientType` | `String` | 客户端类型 | +| `data.clientIp` | `String` | 客户端`IP` | +| `data.clientPort` | `String` | 客户端端口 | +| `data.connectType` | `String` | 连接类型 | +| `data.appName` | `String` | 应用名 | +| `data.Version` | `String` | 客户端版本 | + +> 只有当`clientType`为`connection`时，会显示`connectType`，`appName`和`appName`字段 + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client?clientId=1664527081276_127.0.0.1_4400' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "clientId": "1664527081276_127.0.0.1_4400", + "ephemeral": true, + "lastUpdatedTime": 1664527081642, + "clientType": "connection", + "connectType": "GRPC", + "appName": "-", + "version": "Nacos-Java-Client:v2.1.0", + "clientIp": "10.128.164.35", + "clientPort": "4400" + } + } + ``` + +查询客户端的注册信息（新）
+ +### 接口描述 + +查询指定客户端的注册信息 + +> 客户端不存在时会报错 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/ns/client/publish/list` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|------------|----------|----------|------------| +| `clientId` | `String` | **是** | 客户端`id` | + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|-----------------------------------|------------|----------------------| +| `data` | `Object[]` | 客户端注册的服务列表 | +| `data.namespace` | `String` | 命名空间 | +| `data.group` | `String` | 分组名 | +| `data.serviceName` | `String` | 服务名 | +| `data.registeredInstance` | `Object` | 该服务下注册的实例 | +| `data.registeredInstance.ip` | `String` | `IP`地址 | +| `data.registeredInstance.port` | `int` | 端口号 | +| `data.registeredInstance.cluster` | `String` | 集群名 | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/publish/list?clientId=1664527081276_127.0.0.1_4400' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "namespace": "public", + "group": "DEFAULT_GROUP", + "serviceName": "nacos.test.1", + "registeredInstance": { + "ip": "10.128.164.35", + "port": 9950, + "cluster": "DEFAULT" + } + } + ] + } + ``` + +查询客户端的订阅信息（新）
+ +### 接口描述 + +查询指定客户端的订阅信息 + +> 客户端不存在时会报错 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/ns/client/subscribe/list` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|------------|----------|----------|------------| +| `clientId` | `String` | **是** | 客户端`id` | + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|-----------------------------|------------|----------------------| +| `data` | `Object[]` | 客户端订阅的服务列表 | +| `data.namespace` | `String` | 命名空间 | +| `data.group` | `String` | 分组名 | +| `data.serviceName` | `String` | 服务名 | +| `data.subscriberInfo` | `Object` | 订阅信息 | +| `data.subscriberInfo.app` | `String` | 应用 | +| `data.subscriberInfo.agent` | `String` | 客户端信息 | +| `data.subscriberInfo.addr` | `String` | 地址 | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/subscribe/list?clientId=1664527081276_127.0.0.1_4400' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "namespace": "public", + "group": "DEFAULT_GROUP", + "serviceName": "nacos.test.1", + "subscriberInfo": { + "app": "unknown", + "agent": "Nacos-Java-Client:v2.1.0", + "addr": "10.128.164.35" + } + } + ] + } + ``` + +查询注册指定服务的客户端信息（新）
+ +### 接口描述 + +查询注册指定服务的客户端信息 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/ns/client/service/publisher/list` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|-----------|----------|------------------------------------| +| `namespaceId` | `String` | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | `String` | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | `String` | **是** | 服务名 | +| `ephemeral` | `boolean` | 否 | 是否为临时实例 | +| `ip` | `String` | 否 | `IP`地址，默认为空，不限制`IP`地址 | +| `port` | `int` | 否 | 端口号，默认为空，表示不限制端口号 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|-----------------|----------|------------| +| `data` | | 客户端列表 | +| `data.clientId` | `String` | 客户端`id` | +| `data.ip` | `String` | 客户端`IP` | +| `data.port` | `int` | 客户端端口 | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/service/publisher/list?serviceName=nacos.test.1&ip=&port=' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "clientId": "1664527081276_127.0.0.1_4400", + "ip": "10.128.164.35", + "port": 9950 + }, + { + "clientId": "10.128.164.35:9954#true", + "ip": "10.128.164.35", + "port": 9954 + } + ] + } + ``` + +查询订阅指定服务的客户端信息（新）
+ +### 接口描述 + +查询订阅指定服务的客户端信息 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/ns/client/service/subscriber/list` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|----------|----------|------------------------------------| +| `namespaceId` | String | 否 | 命名空间`Id`，默认为`public` | +| `groupName` | String | 否 | 分组名，默认为`DEFAULT_GROUP` | +| `serviceName` | String | **是** | 服务名 | +| `ephemeral` | boolean | 否 | 是否为临时实例 | +| `ip` | String | 否 | `IP`地址，默认为空，不限制`IP`地址 | +| `port` | int | 否 | 端口号，默认为空，表示不限制端口号 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|-----------------|----------|------------| +| `data` | | 客户端列表 | +| `data.clientId` | `String` | 客户端`id` | +| `data.ip` | `String` | 客户端`IP` | +| `data.port` | `int` | 客户端端口 | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/ns/client/service/subscriber/list?serviceName=nacos.test.1&ip=&port=' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "clientId": "1664527125645_127.0.0.1_4443", + "ip": "10.128.164.35", + "port": 0 + }, + { + "clientId": "172.24.144.1:54126#true", + "ip": "172.24.144.1", + "port": 54126 + } + ] + } + ``` + +## 命名空间 + +查询命名空间列表
+ +### 接口描述 + +查询当前所有的命名空间 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/console/namespace/list` + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|--------------------------|------------|----------------------| +| `data` | `Object[]` | 命名空间列表 | +| `data.namespace` | `String` | 命名空间`ID` | +| `data.namespaceShowName` | `String` | 命名空间名称 | +| `data.namespaceDesc` | `String` | 命名空间描述 | +| `data.quota` | `int` | 命名空间的容量 | +| `data.configCount` | `int` | 命名空间下的配置数量 | +| `data.type` | `int` | 命名空间类型 | + +> 命名空间分为3种类型，`0 `- 全局命名空间 `1` - 默认私有命名空间 `2 `- 自定义命名空间 + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/console/namespace/list' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "namespace": "", + "namespaceShowName": "public", + "namespaceDesc": null, + "quota": 200, + "configCount": 1, + "type": 0 + } + ] + } + ``` + +查询具体命名空间
+ +### 接口描述 + +查询具体命名空间的信息 + +> 命名空间不存在时会报错 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/console/namespace` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|----------|----------|--------------| +| `namespaceId` | `String` | **是** | 命名空间`Id` | + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|--------------------------|----------|----------------------| +| `data` | `Object` | 命名空间信息 | +| `data.namespace` | `String` | 命名空间`ID` | +| `data.namespaceShowName` | `String` | 命名空间名称 | +| `data.namespaceDesc` | `String` | 命名空间描述 | +| `data.quota` | `int` | 命名空间的容量 | +| `data.configCount` | `int` | 命名空间下的配置数量 | +| `data.type` | `int` | 命名空间类型 | + +> 命名空间分为3种类型，`0` - 全局命名空间 `1` - 默认私有命名空间 `2` - 自定义命名空间 + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/console/namespace?namespaceId=test_namespace' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "namespace": "test_namespace", + "namespaceShowName": "test", + "namespaceDesc": null, + "quota": 200, + "configCount": 0, + "type": 2 + } + } + ``` + +创建命名空间
+ +### 接口描述 + +创建一个命名空间 + +> 命名空间已存在时会报错 + +### 请求方式 + +`POST` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/console/namespace` + +### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|-----------------|----------|----------|--------------| +| `namespaceId` | `String` | **是** | 命名空间`Id` | +| `namespaceName` | `String` | **是** | 命名空间名称 | +| `namespaceDesc` | `String` | 否 | 命名空间描述 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'namespaceId=test_namespace' \ + -d 'namespaceName=test' \ + -X POST 'http://127.0.0.1:8848/nacos/v2/console/namespace' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +编辑命名空间
+ +### 接口描述 + +编辑命名空间信息 + +### 请求方式 + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/console/namespace` + +### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|-----------------|----------|----------|--------------| +| `namespaceId` | `String` | **是** | 命名空间`Id` | +| `namespaceName` | `String` | **是** | 命名空间名称 | +| `namespaceDesc` | `String` | 否 | 命名空间描述 | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'namespaceId=test_namespace' \ + -d 'namespaceName=test.nacos' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/console/namespace' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +删除命名空间
+ +### 接口描述 + +删除指定命名空间 + +### 请求方式 + +`DELETE` + +### 请求URL + +`/nacos/v2/console/namespace` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|---------------|----------|----------|--------------| +| `namespaceId` | `String` | **是** | 命名空间`Id` | + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'namespaceId=test_namespace' \ + -X DELETE 'http://127.0.0.1:8848/nacos/v2/console/namespace' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + +## 集群管理 + +查询当前节点信息
+ +### 接口描述 + +查询当前`nacos`节点信息 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/core/cluster/node/self` + +返回数据
+ +| 参数名 | 参数类型 | 描述说明 | +|----------------------|----------|-----------------------| +| `data` | `Object` | 当前节点信息 | +| `data.ip` | `String` | 节点`IP`地址 | +| `data.port` | `int` | 节点端口 | +| `data.state` | `String` | 节点状态 | +| `data.extendInfo` | `Object` | 节点扩展信息 | +| `data.address` | `String` | 节点地址（`IP:port`） | +| `data.failAccessCnt` | `int` | 失败访问次数 | +| `data.abilities` | `Object` | | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/cluster/node/self' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": { + "ip": "10.128.164.35", + "port": 8848, + "state": "UP", + "extendInfo": { + "lastRefreshTime": 1664521263623, + "raftMetaData": { + "metaDataMap": { + "naming_instance_metadata": { + "leader": "10.128.164.35:7848", + "raftGroupMember": [ + "10.128.164.35:7848" + ], + "term": 12 + }, + "naming_persistent_service_v2": { + "leader": "10.128.164.35:7848", + "raftGroupMember": [ + "10.128.164.35:7848" + ], + "term": 12 + }, + "naming_service_metadata": { + "leader": "10.128.164.35:7848", + "raftGroupMember": [ + "10.128.164.35:7848" + ], + "term": 12 + } + } + }, + "raftPort": "7848", + "readyToUpgrade": true, + "version": "2.1.0" + }, + "address": "10.128.164.35:8848", + "failAccessCnt": 0, + "abilities": { + "remoteAbility": { + "supportRemoteConnection": true + }, + "configAbility": { + "supportRemoteMetrics": false + }, + "namingAbility": { + "supportJraft": true + } + } + } + } + ``` + +查询集群节点列表
+ +### 接口描述 + +查询集群节点列表 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/core/cluster/node/list` + +### 请求参数 + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|-----------|----------|----------|--------------------| +| `address` | `String` | 否 | 节点地址，默认为空 | +| `state` | `String` | 否 | 节点状态，默认为空 | + +> `address `对应于需要查询的节点地址的前缀匹配条件，为空时不做限制 +> +> `state`对应节点状态的筛选条件，为空时不做限制 + +### 返回数据 + +| 参数名 | 参数类型 | 描述说明 | +|--------|------------|---------------------------------------| +| `data` | `Object[]` | 节点列表，详情参见[节点详情](#Member) | + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/cluster/node/list' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": [ + { + "ip": "10.128.164.35", + "port": 8848, + "state": "UP", + "extendInfo": { + "lastRefreshTime": 1664521263623, + "raftMetaData": { + "metaDataMap": { + "naming_instance_metadata": { + "leader": "10.128.164.35:7848", + "raftGroupMember": [ + "10.128.164.35:7848" + ], + "term": 12 + }, + "naming_persistent_service_v2": { + "leader": "10.128.164.35:7848", + "raftGroupMember": [ + "10.128.164.35:7848" + ], + "term": 12 + }, + "naming_service_metadata": { + "leader": "10.128.164.35:7848", + "raftGroupMember": [ + "10.128.164.35:7848" + ], + "term": 12 + } + } + }, + "raftPort": "7848", + "readyToUpgrade": true, + "version": "2.1.0" + }, + "address": "10.128.164.35:8848", + "failAccessCnt": 0, + "abilities": { + "remoteAbility": { + "supportRemoteConnection": true + }, + "configAbility": { + "supportRemoteMetrics": false + }, + "namingAbility": { + "supportJraft": true + } + } + } + ] + } + ``` + +查询当前节点健康状态
+ +### 接口描述 + +查询当前`nacos`节点健康状态 + +### 请求方式 + +`GET` + +### 请求URL + +`/nacos/v2/core/cluster/node/self/health` + +返回数据
+ +| 参数名 | 参数类型 | 描述说明 | +|--------|----------|------------------| +| `data` | `String` | 当前节点健康状态 | + +> 节点共有 `STARTING`， `UP`，`SUSPICIOUS`，`DOWN`，`ISOLATION`五种状态 + +### 示例 + +* 请求示例 + + ```shell + curl -X GET 'http://127.0.0.1:8848/nacos/v2/core/cluster/node/self/health' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": "UP" + } + ``` + + +切换集群寻址模式
+ +### 接口描述 + +切换集群寻址模式 + +### 请求方式 + +`PUT` + +`Content-Type:application/x-www-form-urlencoded` + +### 请求URL + +`/nacos/v2/core/cluster/lookup` + +### 请求Body + +| 参数名 | 参数类型 | 是否必填 | 描述说明 | +|--------|----------|----------|----------| +| `type` | `String` | **是** | 寻址模式 | + +> 寻址模式有两种：`file`（文件配置）和 `address-server`（地址服务器） + +### 返回数据 + +| 参数名 | 参数类型 | 描述 | +|--------|-----------|--------------| +| `data` | `boolean` | 是否执行成功 | + +### 示例 + +* 请求示例 + + ```shell + curl -d 'type=file' \ + -X PUT 'http://127.0.0.1:8848/nacos/v2/core/cluster/lookup' + ``` + +* 返回示例 + + ```json + { + "code": 0, + "message": "success", + "data": true + } + ``` + + diff --git a/src/content/docs/v3.0/zh-cn/guide/user/other-language.md b/src/content/docs/v3.0/zh-cn/guide/user/other-language.md new file mode 100644 index 00000000000..6f161bb0eb5 --- /dev/null +++ b/src/content/docs/v3.0/zh-cn/guide/user/other-language.md @@ -0,0 +1,23 @@ +--- +title: 其他语言的SDK +keywords: [其他语言,SDK] +description: 其他语言的SDK +sidebar: + order: 2 +--- + +# 其他语言的SDK + +Nacos社区当前仅提供了Java版本的客户端，我们将主要依靠社区的贡献来发展多语言客户端。在未来，我们将向Nacos社区用户推荐那些最被广泛使用的以及支持最好的客户端作为Nacos相应语言的官方版本。 + +* [go](https://github.com/nacos-group/nacos-sdk-go) +* [cpp](https://github.com/nacos-group/nacos-sdk-cpp) +* [python](https://github.com/nacos-group/nacos-sdk-python) +* [nodejs](https://github.com/nacos-group/nacos-sdk-nodejs) +* [c#](https://github.com/nacos-group/nacos-sdk-csharp) +* more ... + +## 其他多语言用法 +> 以下多语言用法由其他社区提供和维护： + +* [PHP](https://github.com/workbunny/webman-nacos) \ No newline at end of file diff --git a/src/content/docs/v3.0/zh-cn/guide/user/parameters-check.md b/src/content/docs/v3.0/zh-cn/guide/user/parameters-check.md new file mode 100644 index 00000000000..62bfbf17ce4 --- /dev/null +++ b/src/content/docs/v3.0/zh-cn/guide/user/parameters-check.md @@ -0,0 +1,244 @@ +--- +title: 参数校验 +keywords: [参数校验,使用规则] +description: 参数校验 +date: 2023-10-24 +sidebar: + order: 4 +--- + +> 该文档即将废弃，推荐查看[用户手册-参数校验](../../manual/user/parameters-check.md)。 + +# 参数校验 + +2.3.0版本之前的Nacos的参数校验逻辑分散，由各类请求的处理方法单独进行校验，难以更改维护，经常出现参数校验的遗漏，参数校验的规则也没有明确统一；这使得用户使用时经常会因为一些特殊字符导致功能不符合预期或出现漏洞，甚至导致大量推送，导致带宽打满，内存占用过多，导致应用出现故障。 + +在2.3.0版本中，Nacos明确了参数校验规则，在服务端实现了统一的参数校验逻辑并添加了参数校验层，根据校验规则对客户端向服务端发送的请求进行校验。 + +用户可以选择开启参数校验功能，开启后Nacos将会对客户端向服务端发送的请求中的部分参数进行参数校验，确保参数的合法性，避免由于错误使用，导致的不符合预期以及性能问题。 + +## 参数校验开关 + +### 服务端 + +服务端的参数校验功能**默认开启**，用户可以通过设置`${nacos.home}/conf`目录下的`application.properties`文件中的`nacos.core.param.check.enabled`值选择开启或者关闭服务端参数校验功能。 + +`nacos.core.param.check.enabled=true`时开启Nacos服务端参数校验，`false`关闭服务端参数校验 + +### 客户端 + +待实现 + +## 参数校验规则 + +开启参数校验后OpenAPI文档 和 SDK文档中的所有接口中的相关参数都会接受格式校验，现对相关参数以及校验规则进行说明： + +|参数描述|最大字符长度|校验规则| +|-----|-----|-----| +|命名空间名称|256|禁止`@#$%^&*`，对应正则表达式：`[^@#$%^&*]+$`| +|命名空间ID|64|只允许字母数字下划线以及"-"字符，对应正则表达式：`^[\w-]+`｜ +|配置名称|256|只允许字母数字以及`_-.:`，对应正则表达式：`^[a-zA-Z0-9-_:\.]*$`| +|服务名称|512|禁止中文和`@@`且禁止以`@`开头，禁止空白字符，对应正则表达式`^(?!@).((?!@@)[^\u4E00-\u9FA5])*$`| +|分组名称|128|只允许字母数字以及`_-.:`，对应正则表达式：`^[a-zA-Z0-9-_:\.]*$`| +|集群名称|64|只允许数字字母和`-_`，对应正则表达式`^[0-9a-zA-Z-_]+$`| +|IP地址|128|禁止中文字符和空白字符，对应正则表达式为`^[^\u4E00-\u9FA5]*$`| +|端口号|-|取值范围为`0～65535`| +|实例元数据|1024|字段名加字段值的总长度小于1024个字符| + +### 1. namespaceShowName + +#### 参数描述 + +命名空间名称 + +#### 校验规则 + +字符长度最大为256，禁止`@#$%^&*`,对应正则表达式：`[^@#$%^&*]+$` + +#### OpenAPI示例 + +- [命名空间](./open-api.md) + +#### 校验失败报错信息 + +- 超出长度：`Param 'namespaceShowName' is illegal, the param length should not exceed 256.` +- 非法字符：`Param 'namespaceShowName' is illegal, illegal characters should not appear in the param.` + +### 2. namespaceId/tenant/namespace + +#### 参数描述 + +命名空间ID（租户空间） + +#### 校验规则 + +字符长度最大为64，只允许字母数字下划线以及"-"字符，对应正则表达式：`^[\w-]+` + +#### OpenAPI示例 + +- [获取配置](./open-api.md) +- [注册实例](./open-api.md) + +#### 校验失败报错信息 + +- 超出长度：`Param 'namespaceId/tenant' is illegal, the param length should not exceed 64.` +- 非法字符：`Param 'namespaceId/tenant' is illegal, illegal characters should not appear in the param.` + +### 3. dataId + +#### 参数描述 + +配置名称 + +#### 校验规则 + +字符长度最大为256，只允许字母数字以及`_-.:`，对应正则表达式：`^[a-zA-Z0-9-_:\.]*$` + +#### OpenAPI示例 + +[发布配置](./open-api.md) + +#### Java SDK示例 + +监听配置：`public void addListener(String dataId, String group, Listener listener) ` + +#### 校验失败报错信息 + +- 超出长度：`Param 'dataId' is illegal, the param length should not exceed 512.` +- 非法字符：`Param 'dataId' is illegal, illegal characters should not appear in the param.` + +### 4. service/serviceName + +#### 参数描述 + +服务名称 + +#### 校验规则 + +字符长度最大为512，禁止中文和`@@`且禁止以`@`开头，对应正则表达式`^(?!@).((?!@@)[^\u4E00-\u9FA5])*$` + +#### OpenAPI示例 + +[注册实例](./open-api.md) + +#### Java SDK示例 + +注册实例：`void registerInstance(String serviceName, String ip, int port) throws NacosException; ` + +#### 校验失败报错信息 + +- 超出长度：`Param 'serviceName' is illegal, the param length should not exceed 512.` +- 非法字符：`Param 'serviceName' is illegal, illegal characters should not appear in the param.` + +### 5. group/groupName + +#### 参数描述 + +分组名称 + +#### 校验规则 + +字符长度最大为128，只允许字母数字以及`_-.:`，对应正则表达式：`^[a-zA-Z0-9-_:\.]*$` + +#### OpenAPI示例 + +[查询实例列表](./open-api.md) + +#### Java SDK示例 + +删除配置：`public boolean removeConfig(String dataId, String group) throws NacosException ` + +#### 校验失败报错信息 + +- 超出长度：`Param 'group' is illegal, the param length should not exceed 512.` +- 非法字符：`Param 'group' is illegal, illegal characters should not appear in the param.` + +### 6. cluster/clusterName + +#### 参数描述 + +集群名称 + +#### 校验规则 + +字符长度最大为64，只允许数字字母和`-_`，对应正则表达式`^[0-9a-zA-Z-_]+$` + +#### OpenAPI示例 + +[更新实例](./open-api.md) + +#### Java SDK示例 + +获取全部实例：`List
+
+
+
+
+
+#### 返回值
+
+| 参数类型 | 描述 |
+| :--- | :--- |
+| string | 配置值，初始化或者配置变更的时候通过回调函数返回该值。 |
+
+
+#### 请求示例
+
+```java
+String serverAddr = "{serverAddr}";
+String dataId = "{dataId}";
+String group = "{group}";
+Properties properties = new Properties();
+properties.put("serverAddr", serverAddr);
+ConfigService configService = NacosFactory.createConfigService(properties);
+String content = configService.getConfig(dataId, group, 5000);
+System.out.println(content);
+configService.addListener(dataId, group, new Listener() {
+ @Override
+ public void receiveConfigInfo(String configInfo) {
+ System.out.println("recieve1:" + configInfo);
+ }
+ @Override
+ public Executor getExecutor() {
+ return null;
+ }
+});
+
+// 测试让主线程不退出，因为订阅配置是守护线程，主线程退出守护线程就会退出。 正式代码中无需下面代码
+while (true) {
+ try {
+ Thread.sleep(1000);
+ } catch (InterruptedException e) {
+ e.printStackTrace();
+ }
+}
+```
+
+### 删除监听
+#### 描述
+
+取消监听配置，取消监听后配置不会再推送。
+
+```java
+public void removeListener(String dataId, String group, Listener listener)
+```
+
+#### 请求参数
+
+| 参数名 | 参数类型 | 描述 |
+| :--- | :--- | :--- |
+| dataId | string | 配置 ID，采用类似 package.class（如com.taobao.tc.refund.log.level）的命名规则保证全局唯一性，class 部分建议是配置的业务含义。全部字符小写。只允许英文字符和 4 种特殊字符（"."、":"、"-"、"\_"），不超过 256 字节。 |
+| group | string | 配置分组 |
+| listener | ConfigChangeListenerAdapter | 监听器，配置变更进入监听器的回调函数。 |
+
+
+#### 使用示例
+
+```java
+String serverAddr = "{serverAddr}";
+String dataId = "{dataId}";
+String group = "{group}";
+Properties properties = new Properties();
+properties.put("serverAddr", serverAddr);
+ConfigService configService = NacosFactory.createConfigService(properties);
+configService.removeListener(dataId, group, yourListener);
+```
+
+### 发布配置
+#### 描述
+
+用于通过程序自动发布 Nacos 配置，以便通过自动化手段降低运维成本。
+
+注意：创建和修改配置时使用的同一个发布接口，当配置不存在时会创建配置，当配置已存在时会更新配置。
+
+```java
+public boolean publishConfig(String dataId, String group, String content) throws NacosException;
+
+@Since 1.4.1
+public boolean publishConfig(String dataId, String group, String content, String type) throws NacosException;
+
+```
+
+#### 请求参数
+
+| 参数名 | 参数类型 | 描述 |
+| :--- | :--- | :--- |
+| dataId | string | 配置 ID，采用类似 `package.class`（如 `com.taobao.tc.refund.log.level`）的命名规则保证全局唯一性。建议根据配置的业务含义来定义 class 部分。全部字符均为小写。只允许英文字符和 4 种特殊字符（“.”、“:”、“-”、“\_”），不超过 256 字节。 |
+| group | string | 配置分组，建议填写`产品名:模块名`（如 Nacos`:Test`）来保证唯一性。只允许英文字符和 4 种特殊字符（“.”、“:”、“-”、“\_”），不超过 128 字节。 |
+| content | string | 配置内容，不超过 100K 字节。 |
+| type | string | @Since 1.4.1. 配置类型，见 `com.alibaba.nacos.api.config.ConfigType`，默认为TEXT |
+
+
+#### 返回参数
+
+| 参数类型 | 描述 |
+| :--- | :--- |
+| boolean | 是否发布成功 |
+
+
+#### 请求示例
+
+```java
+try {
+ // 初始化配置服务，控制台通过示例代码自动获取下面参数
+ String serverAddr = "{serverAddr}";
+ String dataId = "{dataId}";
+ String group = "{group}";
+ Properties properties = new Properties();
+ properties.put("serverAddr", serverAddr);
+ ConfigService configService = NacosFactory.createConfigService(properties);
+ boolean isPublishOk = configService.publishConfig(dataId, group, "content");
+ System.out.println(isPublishOk);
+} catch (NacosException e) {
+ // TODO Auto-generated catch block
+ e.printStackTrace();
+}
+```
+
+#### 异常说明
+
+读取配置超时或网络异常，抛出 NacosException 异常。
+
+### 删除配置
+#### 描述
+
+用于通过程序自动删除 Nacos 配置，以便通过自动化手段降低运维成本。
+
+__注意：__ 当配置已存在时会删除该配置，当配置不存在时会直接返回成功消息。
+
+
+```java
+public boolean removeConfig(String dataId, String group) throws NacosException
+
+```
+
+#### 请求参数
+
+| 参数名 | 参数类型 | 描述 |
+| :--- | :--- | :--- |
+| dataId | string | 配置 ID |
+| group | string | 配置分组 |
+
+
+#### 返回参数
+
+| 参数类型 | 描述 |
+| :--- | :--- |
+| boolean | 是否删除成功 |
+
+
+#### 请求示例
+
+```java
+try {
+ // 初始化配置服务，控制台通过示例代码自动获取下面参数
+ String serverAddr = "{serverAddr}";
+ String dataId = "{dataId}";
+ String group = "{group}";
+ Properties properties = new Properties();
+ properties.put("serverAddr", serverAddr);
+
+ ConfigService configService = NacosFactory.createConfigService(properties);
+ boolean isRemoveOk = configService.removeConfig(dataId, group);
+ System.out.println(isRemoveOk);
+} catch (NacosException e) {
+ // TODO Auto-generated catch block
+ e.printStackTrace();
+}
+```
+
+#### 异常说明
+
+读取配置超时或网络异常，抛出 NacosException 异常。
+
+
+
+## 服务发现SDK
+### 注册实例
+#### 描述注册一个实例到服务。
+```java
+void registerInstance(String serviceName, String ip, int port) throws NacosException;
+
+void registerInstance(String serviceName, String ip, int port, String clusterName) throws NacosException;
+
+void registerInstance(String serviceName, Instance instance) throws NacosException;
+```
+
+#### 请求参数
+
+| 名称 | 类型 | 描述 |
+| :--- | :--- | --- |
+| serviceName | 字符串 | 服务名 |
+| ip | 字符串 | 服务实例IP |
+| port | int | 服务实例port |
+| clusterName | 字符串 | 集群名 |
+| instance | 参见代码注释 | 实例属性 |
+
+#### 返回参数
+无
+#### 请求示例
+```java
+NamingService naming = NamingFactory.createNamingService(System.getProperty("serveAddr"));
+naming.registerInstance("nacos.test.3", "11.11.11.11", 8888, "TEST1");
+
+Instance instance = new Instance();
+instance.setIp("55.55.55.55");
+instance.setPort(9999);
+instance.setHealthy(false);
+instance.setWeight(2.0);
+Map|
+ 参数名
+ |
+
+ 参数类型
+ |
+
+ 描述
+ |
+
|
+ dataId
+ |
+
+ string
+ |
+
+ 配置 ID，采用类似 package.class（如com.taobao.tc.refund.log.level）的命名规则保证全局唯一性，class 部分建议是配置的业务含义。 全部字符小写。只允许英文字符和 4 种特殊字符（"."、":"、"-"、"_"）。不超过 256 字节。
+ |
+
|
+ group
+ |
+
+ string
+ |
+
+ 配置分组，建议填写产品名：模块名（如 Nacos:Test）保证唯一性。 只允许英文字符和4种特殊字符（"."、":"、"-"、"_"），不超过128字节。
+
+ |
+
|
+ listener
+ |
+
+ Listener
+ |
+
+ 监听器，配置变更进入监听器的回调函数。
+ |
+