Merge pull request #307 from taosdata/main-dingbo2

更新云服务SDK文档

Author: wingwing2005

docs/07-develop/01-sdk.md

@@ -12,9 +12,14 @@ TDengine IDMP SDK 使您可以以编程的方式无障碍访问整个数据资
 
 ## Java SDK 使用说明
 
-### 引入 SDK
+### 前提条件
 
-如果您的开发环境已经有 maven，建议先将 idmp-sdk 安装到本地 maven 仓库，以便在项目中引用。
+1. 安装最新 Java 稳定版。（至少 Java 11）
+2. 安装 Maven 命令行工具。
+
+### 安装 SDK
+
+先将 idmp-sdk 安装到本地 maven 仓库，以便在项目中引用。
 
 ```bash
 cd idmp-java-sdk
@@ -85,6 +90,10 @@ public class ElementApiTest {
 
 ## Python SDK 使用说明
 
+### 前提条件
+
+安装 Python 开发环境。（python >= 3.10）
+
 ### 安装 SDK
 
 您可以使用 pip 安装 Python SDK。首先，进入 `idmp-python-sdk` 目录，然后运行以下命令：
@@ -167,6 +176,50 @@ with idmp_sdk.ApiClient(configuration) as api_client:
     print("Exception when calling UomResourceApi->api_v1_uomclasses_get: %s\n" % e)
 ```
 
+对于其它语言，将 -g 参数替换为对应语言的名称即可，将 --library 参数替换为对应语言的库名称。另外不同语言有不同的附加参数，可通过--additional-properties 指定，具体请参考-properties 指定 ，具体请参考 [OpenAPI Generator 文档](https://openapi-generator.tech/docs/generators) 点击对应语言名称查看详情。
+
+## 云服务使用 SDK
+
+如果您使用的是 [IDMP 的云服务版](https://idmp.taosdata.com/), 则不能使用上述登录方式。因为云服务的登录认证流程和企业版有所不同，云服务的前端代码封装了比较复杂的登录逻辑。建议您先通过浏览器登录云服务， 然后从浏览器的开发者工具的网络标签页找到任意一个对后端 API 的请求，例如：/api/v1/permissions/menus 这个请求（如果过滤不出这个请求可以刷新页面再过滤），复制以下三项数据：
+
+1. 请求 URL 的 host 部分，对于不同的 IDMP 实例这个 URL 的 host 部分是不同的。它的格式是 `https://<实例ID>.idmp.taosdata.com`
+2. 请求标头 "Access-token" 的值， 这个是云服务认证用的 token。
+3. 请求标头 “Authorization” 的值，这个的 idmp 认证用的 token。注意需要去掉前缀 "Bearer "。
+
+然后将这 3 个值分别设置到环境变量中。假如：
+
+```sh
+export CLOUD_HOST=https://<实例ID>.idmp.taosdata.com
+export CLOUD_TOKEN=<Access-token 的值>
+export BEARER_TOKEN=<Authorization Token 的值>
+```
+
+最后，如果您使用的是 Python 客户端则可以按照下面的示例创建 API Client：
+
+```python
+import idmp_sdk
+from idmp_sdk.rest import ApiException
+from pprint import pprint
+import os
+
+
+configuration = idmp_sdk.Configuration(
+  host=os.environ['CLOUD_HOST'],
+  access_token= os.environ['BEARER_TOKEN']
+)
+
+with idmp_sdk.ApiClient(configuration) as api_client:
+  api_client.set_default_header("Access-token", os.environ['CLOUD_TOKEN'])
+  api_instance = idmp_sdk.CategoryResourceApi(api_client)
+  try:
+    api_response = api_instance.api_v1_categories_get(idmp_sdk.CategoryType.ANALYSIS, system_only=False)
+    pprint(api_response)
+  except ApiException as e:
+    print("Exception when calling CategoryResourceApi->api_v1_categories_get: %s\n" % e)
+```
+
+其它语言客户端使用方法类似。
+
 ## 生成 SDK 的方法
 
 下载 OpenAPI Generator CLI 工具：
@@ -186,9 +239,3 @@ java -jar openapi-generator-cli.jar generate -i idmp-v1.x.x.x.json -g java -o id
 ```bash
 java -jar openapi-generator-cli.jar generate -i idmp-v1.x.x.x.json -g python -o idmp-python-sdk --library urllib3 --additional-properties=packageName=idmp_sdk --skip-validate-spec
 ```
-
-对于其它语言，将 -g 参数替换为对应语言的名称即可，将 --library 参数替换为对应语言的库名称。另外不同语言有不同的附加参数，可通过--additional-properties 指定，具体请参考-properties 指定 ，具体请参考 [OpenAPI Generator 文档](https://openapi-generator.tech/docs/generators) 点击对应语言名称查看详情。
-
-## 云服务使用 SDK
-
-如果您使用的是 [IDMP 的云服务版](https://idmp.taosdata.com/), 则不能使用上述登录方式。因为云服务的登录认证流程和企业版有所不同，云服务的前端代码封装了比较复杂的登录逻辑。建议您先通过浏览器登录云服务， 然后从浏览器的开发者工具从请求标头 “Authorization” 获取认证 token， 最后将 token 设置到环境变量中即可。

i18n/en/docusaurus-plugin-content-docs/current/07-develop/01-sdk.md

@@ -12,9 +12,14 @@ TDengine IDMP SDK allows you to programmatically access the entire data assets w
 
 ## Java SDK Usage Guide
 
-### Introducing the SDK
+### Prerequisites
 
-If your development environment already has Maven, it is recommended to install idmp-sdk into the local Maven repository first for reference in the project.
+1. Install the latest stable version of Java. (At least Java 11)
+2. Install the Maven command-line tool.
+
+### Install the SDK
+
+Install idmp-sdk into the local Maven repository first for reference in the project.
 
 ```bash
 cd idmp-java-sdk
@@ -85,6 +90,10 @@ public class ElementApiTest {
 
 ## Python SDK Usage Guide
 
+### Prerequisites
+
+Install the Python development environment. (python>=3.10 is required)
+
 ### Installing the SDK
 
 You can install the Python SDK using pip. First, enter the `idmp-python-sdk` directory, then run the following command:
@@ -167,6 +176,48 @@ with idmp_sdk.ApiClient(configuration) as api_client:
     print("Exception when calling UomResourceApi->api_v1_uomclasses_get: %s\n" % e)
 ```
 
+## Cloud Service SDK Usage
+
+If you are using the [IDMP Cloud Service Edition](https://idmp.tdengine.com/), you cannot use the login method described above. Because the login authentication process for the cloud service differs from the enterprise edition, the cloud service frontend code encapsulates more complex login logic. It is recommended that you first log in to the cloud service through a browser, then find any request to the backend API from the Network tab of the browser's developer tools, for example: /api/v1/permissions/menus this request (if you can't filter out this request, you can refresh the page and filter again), copy the following three pieces of data:
+
+1. The host part of the request URL, which differs for different IDMP instances. Its format is `https://<instance ID>.idmp.tdengine.com`.
+2. The value of the request header "Access-token", which is the token used for cloud service authentication.
+3. The value of the request header "Authorization", which is the token used for IDMP authentication. Note that you need to remove the prefix "Bearer ".
+
+Then set these 3 values into environment variables respectively. For example:
+
+```sh
+export CLOUD_HOST=https://your-instance-id.idmp.tdengine.com
+export CLOUD_TOKEN='your-access-token-value'
+export BEARER_TOKEN='your-authorization-token-value'
+```
+
+Finally, if you are using the Python client, you can create an API Client according to the following example:
+
+```python
+import idmp_sdk
+from idmp_sdk.rest import ApiException
+from pprint import pprint
+import os
+
+
+configuration = idmp_sdk.Configuration(
+  host=os.environ['CLOUD_HOST'],
+  access_token= os.environ['BEARER_TOKEN']
+)
+
+with idmp_sdk.ApiClient(configuration) as api_client:
+  api_client.set_default_header("Access-token", os.environ['CLOUD_TOKEN'])
+  api_instance = idmp_sdk.CategoryResourceApi(api_client)
+  try:
+    api_response = api_instance.api_v1_categories_get(idmp_sdk.CategoryType.ANALYSIS, system_only=False)
+    pprint(api_response)
+  except ApiException as e:
+    print("Exception when calling CategoryResourceApi->api_v1_categories_get: %s\n" % e)
+```
+
+The usage for clients in other languages is similar.
+
 ## How to Generate SDK
 
 Download the OpenAPI Generator CLI tool:
@@ -188,7 +239,3 @@ java -jar openapi-generator-cli.jar generate -i idmp-v1.x.x.x.json -g python -o
 ```
 
 For other languages, simply replace the `-g` parameter with the corresponding language name, and the --library parameter with the corresponding library name. Additionally, different languages have different additional parameters, which can be specified via --additional-properties. For details, please refer to the [OpenAPI Generator Documentation](https://openapi-generator.tech/docs/generators) and click on the corresponding language name for more information.
-
-## Using SDK with Cloud Service
-
-If you are using the [cloud version of IDMP](https://cloud.tdengine.com/), the login method described above cannot be used. Since the login authentication process for the cloud service differs from the enterprise version, the front-end code of the cloud service encapsulates more complex login logic. It is recommended to first log in to the cloud service through a browser, then obtain the authentication token from the "Authorization" request header in the browser's developer tools, and finally set the token in environment variables.