Skip to content

Commit

Permalink
Refining the configs interface documentation (#4804)
Browse files Browse the repository at this point in the history 
* add tech-support-qq-4.png

* Update README.md

* Enhance the user experience in the scenario of submitting duplicate keys

* Modify the key-value conflict exception prompt, adjust the code style

* chore(apollo-doc): Refining the configs interface documentation

* Update docs/en/usage/other-language-client-user-guide.md

---------

Co-authored-by: Jason Song <[email protected]>
  • Loading branch information
@klboke @nobodyiam
klboke and nobodyiam authored Mar 19, 2023
1 parent 1815912 commit b7af5cc
Show file tree
Hide file tree
Showing 2 changed files with 23 additions and 19 deletions.
20 changes: 11 additions & 9 deletions docs/en/usage/other-language-client-user-guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -55,20 +55,22 @@ This interface will get the configuration directly from the database and can be

### 1.3.1 Http interface description

**URL**: `{config_server_url}/configs/{appId}/{clusterName}/{namespaceName}?releaseKey={releaseKey}&ip={clientIp}`
**URL**: `{config_server_url}/configs/{appId}/{clusterName}/{namespaceName}?releaseKey={releaseKey}&messages={messages}&label={label}&ip={clientIp}`

**Method**: GET

**Parameter Description**.

| Parameter Name | Required | Parameter Value | Remarks |
| ----------------- | ---------------------------- | ------------------------------------------------------------ | ------------------------------------------------------------ |
| config_server_url | Yes | The address of the Apollo configuration service | |
| appId | Yes | The appId of the application | |
| clusterName | Yes | clusterName | Normally, just pass in default. If you want to configure by cluster, you can refer to [cluster-independent configuration instructions](en/usage/apollo-user-guide?id=iii-cluster-independent-configuration-instructions) to do the relevant configuration, and then fill in the corresponding cluster name here. |
| namespaceName | is the name of the namespace | If no new namespace has been created, just pass in application. If you have created a Namespace and need to use the configuration of that Namespace, pass the corresponding Namespace name. **If the namespace is created and needs to use the configuration of the namespace, pass the namespace name. | |
| releaseKey | No | The releaseKey of the last release object can be passed to the server to compare the version, if there is no change in the version, the server will return 304 to save traffic and computing. | |
| ip | no | The ip of the machine where the application is deployed | This parameter is optional and is used to implement grayscale releases. |
| Parameter Name | Required | Parameter Value | Remarks |
| ----------------- |----------|---------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| config_server_url | Yes | The address of the Apollo configuration service | |
| appId | Yes | The appId of the application | |
| clusterName | Yes | clusterName | Normally, just pass in default. If you want to configure by cluster, you can refer to [cluster-independent configuration instructions](en/usage/apollo-user-guide?id=iii-cluster-independent-configuration-instructions) to do the relevant configuration, and then fill in the corresponding cluster name here. |
| namespaceName | Yes | is the name of the namespace | If no new namespace has been created, just pass in application. If you have created a Namespace and need to use the configuration of that Namespace, pass the corresponding Namespace name. **If the namespace is created and needs to use the configuration of the namespace, pass the namespace name. |
| releaseKey | No | Previous releaseKey | The releaseKey of the last release object can be passed to the server to compare the version, if there is no change in the version, the server will return 304 to save traffic and computing. |
| messages | No | Latest notificationId | To update the memory cache on the server in real-time, if the `releaseKey` parameter is passed without the `messages` parameter, there is a chance that the latest configuration will not be obtained in a multi-instance server environment with memory caching enabled. The `messages` parameter is a JSON string structure {"details":{"key":notificationId}}. The `appId`, `clusterName`, and `namespaceName` need to be concatenated using the + sign to form the key. Assuming `appId=app`, `clusterName=default`, `namespaceName=test`, and `notificationId=11`, the `messages` parameter would be {"details":{"app+default+test":11}}. When using the messages parameter, URL encoding is required.|
| label | No | Labels for grayscale configuration | This parameter is optional and is used for label rule matching in grayscale publishing. |
| ip | No | The ip of the machine where the application is deployed | This parameter is optional and is used for ip rule matching in grayscale publishing. |

### 1.3.2 Http interface return format

Expand Down
22 changes: 12 additions & 10 deletions docs/zh/usage/other-language-client-user-guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -49,21 +49,23 @@
该接口会直接从数据库中获取配置，可以配合配置推送通知实现实时更新配置。

### 1.3.1 Http接口说明
**URL**: {config_server_url}/configs/{appId}/{clusterName}/{namespaceName}?releaseKey={releaseKey}&ip={clientIp}
**URL**: {config_server_url}/configs/{appId}/{clusterName}/{namespaceName}?releaseKey={releaseKey}&messages={messages}&label={label}&ip={clientIp}

**Method**: GET

**参数说明**：

| 参数名 | 是否必须 | 参数值 | 备注 |
|-------------------|----------|----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| config_server_url | 是 | Apollo配置服务的地址 | |
| appId | 是 | 应用的appId | |
| clusterName | 是 | 集群名 | 一般情况下传入 default 即可。 如果希望配置按集群划分，可以参考[集群独立配置说明](zh/usage/apollo-user-guide?id=三、集群独立配置说明)做相关配置，然后在这里填入对应的集群名。 |
| namespaceName | 是 | Namespace的名字 | 如果没有新建过Namespace的话，传入application即可。 如果创建了Namespace，并且需要使用该Namespace的配置，则传入对应的Namespace名字。**需要注意的是对于properties类型的namespace，只需要传入namespace的名字即可，如application。对于其它类型的namespace，需要传入namespace的名字加上后缀名，如datasources.json** |
| releaseKey | 否 | 上一次的releaseKey | 将上一次返回对象中的releaseKey传入即可，用来给服务端比较版本，如果版本比下来没有变化，则服务端直接返回304以节省流量和运算 |
| ip | 否 | 应用部署的机器ip | 这个参数是可选的，用来实现灰度发布。 |

| 参数名 | 是否必须 | 参数值 | 备注 |
|-------------------|---------|---------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| config_server_url | 是 | Apollo配置服务的地址 | |
| appId | 是 | 应用的appId | |
| clusterName | 是 | 集群名 | 一般情况下传入 default 即可。 如果希望配置按集群划分，可以参考[集群独立配置说明](zh/usage/apollo-user-guide?id=三、集群独立配置说明)做相关配置，然后在这里填入对应的集群名。 |
| namespaceName | 是 | Namespace的名字 | 如果没有新建过Namespace的话，传入application即可。 如果创建了Namespace，并且需要使用该Namespace的配置，则传入对应的Namespace名字。**需要注意的是对于properties类型的namespace，只需要传入namespace的名字即可，如application。对于其它类型的namespace，需要传入namespace的名字加上后缀名，如datasources.json** |
| releaseKey | 否 | 上一次的releaseKey | 将上一次返回对象中的releaseKey传入即可，用来给服务端比较版本，如果版本比下来没有变化，则服务端直接返回304以节省流量和运算 |
| messages | 否 | 最新的 notificationId | 用于给服务端即时更新内存缓存，如果传递了 releaseKey，而不传递 messages参数，在服务端多实例、且开启内存缓存时、有概率会获取不到最新的配置。这个参数是json结构的字符串 {"details":{"key":notificationId}}，需要将 `appId`、`clusterName`、`namespaceName`使用 `+` 号拼接为 key,假设现在 `appId=app`、`clusterName=default`、`namespaceName=test`、`notificationId=11`，则 messages 参数为 {"details":{"app+default+test":11}}，使用 messages 参数时，需要进行 URL编码。 |
| label | 否 | 灰度配置的标签 | 这个参数是可选的，用于灰度发布的标签规则匹配。 |
| ip | 否 | 应用部署的机器ip | 这个参数是可选的，用于灰度发布的 ip 规则匹配。 |

### 1.3.2 Http接口返回格式
该Http接口返回的是JSON格式、UTF-8编码。

Expand Down

0 comments on commit b7af5cc

Please sign in to comment.