### Start OpenCode

Source: https://idmpdocs.taosdata.com/administration/easyuse

Start OpenCode in the terminal. This launches the interactive interface for the first time.

```bash
opencode  
```

--------------------------------

### Start TDengine IDMP with Docker Compose

Source: https://idmpdocs.taosdata.com/get-started/get-started-docker

Manual startup commands for TDengine IDMP after All-in-One installation. On Linux/macOS, navigate to ~/.apex/docker and run ./tdengine.sh start; on Windows, navigate to C:\ProgramData\TDengine\Apex\docker and run .\tdengine.ps1 start. The command prompts you to choose between standard deployment (TDengine TSDB Enterprise + IDMP) and full deployment (adds TDgpt for time-series prediction and anomaly detection).

```bash
cd ~/.apex/docker  
./tdengine.sh start  

```

```powershell
cd C:\ProgramData\TDengine\Apex\docker  
.\tdengine.ps1 start  

```

--------------------------------

### Install IDMP CLI via npm

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/idmp-cli

Installs the CLI globally using npm.

```bash
npm install -g @tdengine/idmp-cli

```

--------------------------------

### Backup and restart IDMP certificates (installation package)

Source: https://idmpdocs.taosdata.com/excel-add-in/certificate-configuration

For installation package deployment, back up the existing IDMP certificates and restart the IDMP service to apply new certificates.

```bash
cd /usr/local/taos/idmp/config  
mkdir -p bak  
mv privkey.pem certbundle.pem bak/  

```

```bash
systemctl restart idmp  

```

--------------------------------

### Verify IDMP CLI installation

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/idmp-cli

Run these commands to confirm the CLI is installed and check its version.

```bash
idmp-cli --help
idmp-cli --version

```

--------------------------------

### Start and configure sshd service

Source: https://idmpdocs.taosdata.com/administration/all-in-one-deploy/installation-on-windows

Starts the SSH service and sets it to start automatically. Run in PowerShell after installing OpenSSH Server on each target node for multi-node deployment.

```powershell
Start-Service sshd  
Set-Service -Name sshd -StartupType 'Automatic'  

```

--------------------------------

### Inspect command schema and help with idmp-cli schema

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/idmp-cli

Use `schema search` to find candidate paths by keyword, `schema <service.resource.method>` to inspect parameters, risk level, pagination support, and example commands, and `element elements list --help` to view help for an unfamiliar command. Recommended before executing real calls.

```bash
idmp-cli schema search elements  
idmp-cli schema element.elements.list  
idmp-cli element elements list --help  

```

--------------------------------

### Query all elements with pagination (Java)

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/client-sdk/examples/query-elements

Java example that authenticates with IDMP using environment variables IDMP_HOST, IDMP_USERNAME, and IDMP_PASSWORD, then paginates through all elements with ElementResourceApi.apiV1ElementsGet, printing each element's ID and name. Stops when a page returns fewer rows than the page size (100).

```java
import org.openapitools.client.ApiClient;  
import org.openapitools.client.api.ElementResourceApi;  
import org.openapitools.client.api.ElementResourceApi.ApiV1ElementsGetQueryParams;  
import org.openapitools.client.api.UserResourceApi;  
import org.openapitools.client.model.*;  
  
public class QueryElementsExample {  
  
    public static void main(String[] args) {  
        // 1. Authenticate  
        ApiClient apiClient = new ApiClient("Authorization");  
        apiClient.setBasePath(System.getenv("IDMP_HOST"));  
  
        UserResourceApi userApi = apiClient.buildClient(UserResourceApi.class);  
        LoginReqDTO req = new LoginReqDTO();  
        req.setLoginName(System.getenv("IDMP_USERNAME"));  
        req.setPassword(System.getenv("IDMP_PASSWORD"));  
        LoginRspDTO rsp = userApi.apiV1UsersLoginPost(req);  
        apiClient.setBearerToken(rsp.getToken());  
  
        // 2. Paginate through all elements  
        ElementResourceApi elementApi = apiClient.buildClient(ElementResourceApi.class);  
        int current = 1;  
        int pageSize = 100;  
  
        while (true) {  
            ApiV1ElementsGetQueryParams params = new ApiV1ElementsGetQueryParams()  
                .current(current)  
                .size(pageSize);  
            PageOfBasicElementDTO result = elementApi.apiV1ElementsGet(params);  
  
            for (BasicElementDTO elem : result.getRows()) {  
                System.out.printf("ID: %-30s  Name: %s%n", elem.getId(), elem.getName());  
            }  
  
            if (result.getRows().size() < pageSize) break;  // last page  
            current++;  
        }  
    }  
}  
```

```python
import os  
import idmp_sdk  
from idmp_sdk.rest import ApiException  
  
def get_api_client():  
    """Log in and return an authenticated ApiClient."""  
    configuration = idmp_sdk.Configuration(host=os.environ["IDMP_HOST"])  
    with idmp_sdk.ApiClient(configuration) as api_client:  
        user_api = idmp_sdk.UserResourceApi(api_client)  
        rsp = user_api.api_v1_users_login_post(  
            idmp_sdk.LoginReqDTO(  
                login_name=os.environ["IDMP_USERNAME"],  
                password=os.environ["IDMP_PASSWORD"]  
            )  
        )  
    # Re-initialize with the token  
    auth_config = idmp_sdk.Configuration(  
        host=os.environ["IDMP_HOST"],  
        access_token=rsp.token  
    )  
    return idmp_sdk.ApiClient(auth_config)  
  
def list_all_elements(api_client, page_size=100):  
    """Paginate through all elements and print their IDs and names."""  
    element_api = idmp_sdk.ElementResourceApi(api_client)  
    current = 1  
  
    while True:  
        result = element_api.api_v1_elements_get(  
            current=current,  
            size=page_size  
        )  
        rows = result.rows or []  
        for elem in rows:  
            print(f"ID: {elem.id:<30}  Name: {elem.name}")  
  
        if len(rows) < page_size:  
            break  # last page  
        current += 1  
  
if __name__ == "__main__":  
    with get_api_client() as api_client:  
        list_all_elements(api_client)  
```

--------------------------------

### Start and stop TDengine IDMP on Linux/macOS

Source: https://idmpdocs.taosdata.com/administration/installation/docker-guide

Commands to start and stop the TDengine IDMP services on Linux or macOS after All-in-One deployment. Run from the ~/.apex/docker directory.

```bash
cd ~/.apex/docker  
./tdengine.sh start  

```

```bash
cd ~/.apex/docker  
./tdengine.sh stop  

```

--------------------------------

### Query all elements with pagination (Python)

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/client-sdk/examples/query-elements

Python example that logs in using idmp_sdk and environment variables IDMP_HOST, IDMP_USERNAME, and IDMP_PASSWORD, then paginates through all elements with ElementResourceApi.api_v1_elements_get, printing each element's ID and name. Stops when a page returns fewer rows than the page size (100).

```python
import os  
import idmp_sdk  
from idmp_sdk.rest import ApiException  
  
def get_api_client():  
    """Log in and return an authenticated ApiClient."""  
    configuration = idmp_sdk.Configuration(host=os.environ["IDMP_HOST"])  
    with idmp_sdk.ApiClient(configuration) as api_client:  
        user_api = idmp_sdk.UserResourceApi(api_client)  
        rsp = user_api.api_v1_users_login_post(  
            idmp_sdk.LoginReqDTO(  
                login_name=os.environ["IDMP_USERNAME"],  
                password=os.environ["IDMP_PASSWORD"]  
            )  
        )  
    # Re-initialize with the token  
    auth_config = idmp_sdk.Configuration(  
        host=os.environ["IDMP_HOST"],  
        access_token=rsp.token  
    )  
    return idmp_sdk.ApiClient(auth_config)  
  
def list_all_elements(api_client, page_size=100):  
    """Paginate through all elements and print their IDs and names."""  
    element_api = idmp_sdk.ElementResourceApi(api_client)  
    current = 1  
  
    while True:  
        result = element_api.api_v1_elements_get(  
            current=current,  
            size=page_size  
        )  
        rows = result.rows or []  
        for elem in rows:  
            print(f"ID: {elem.id:<30}  Name: {elem.name}")  
  
        if len(rows) < page_size:  
            break  # last page  
        current += 1  
  
if __name__ == "__main__":  
    with get_api_client() as api_client:  
        list_all_elements(api_client)  
```

--------------------------------

### GET /api/v1/observability/metrics - 查询实时可观测性指标

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/client-sdk/api-reference/metrics

返回 IDMP 服务的实时可观测性指标。可选参数 metricCodes 用于按指标代码过滤，省略时查询全部可用指标。返回 MetricsDTO 对象。

```APIDOC
## GET /api/v1/observability/metrics

### Description
返回 IDMP 服务的实时可观测性指标。

### Method
GET

### Endpoint
/api/v1/observability/metrics

### Parameters
#### Query Parameters
- **metricCodes** (string) - 可选 - 按指标代码过滤；省略时查询全部可用指标

### Response
#### Success Response (200)
返回 `MetricsDTO` 对象。

#### Response Example
（示例代码中未提供响应示例）

### Examples
#### Java
```java
MetricsResourceApi metricsApi = apiClient.buildClient(MetricsResourceApi.class);  
MetricsDTO result = metricsApi.apiV1ObservabilityMetricsGet(null);  
System.out.println(result);  
```

#### Python
```python
metrics_api = idmp_sdk.MetricsResourceApi(api_client)  
result = metrics_api.api_v1_observability_metrics_get()  
print(result)  
```

```

--------------------------------

### Install IDMP CLI offline (Linux/macOS)

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/idmp-cli

Run this script from the root of the unpacked offline package to install the CLI on Linux/macOS.

```bash
bash installers/install-cli-offline.sh

```

--------------------------------

### Python pagination call

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/client-sdk/core-concepts

Python example showing how to call the list endpoint with pagination parameters `current` and `size`.

```python
# Python 示例  
result = element_api.api_v1_elements_get(current=1, size=50)  

```

--------------------------------

### Select DeepSeek V4 Flash model

Source: https://idmpdocs.taosdata.com/administration/easyuse

Example model name to select from the /models list in OpenCode. EasyUse is not bound to any specific model; any model supporting tool use works.

```text
DeepSeek V4 Flash  
```

--------------------------------

### Install IDMP CLI offline (Windows)

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/idmp-cli

Run this command from the root of the unpacked offline package to install the CLI on Windows.

```powershell
installers\install-cli-offline.cmd

```

--------------------------------

### Install OpenCode on Linux/macOS

Source: https://idmpdocs.taosdata.com/administration/easyuse

Install OpenCode on Linux or macOS. The second command reloads the shell configuration file (bashrc or zshrc) depending on the shell used.

```bash
curl -fsSL https://opencode.ai/install | bash  
source ~/.bashrc         # 或 ~/.zshrc，取决于所用 Shell  
```

--------------------------------

### ADFS OAuth configuration example

Source: https://idmpdocs.taosdata.com/administration/user-management

Recommended configuration values for an ADFS OAuth provider. The scope must include openid; the implementation derives the OpenID configuration from the Authorize or Token URL.

```text
Authorize URL: https://adfs.example.com/adfs/oauth2/authorize
Token URL:     https://adfs.example.com/adfs/oauth2/token
Redirect URL:  https://<idmp-host>/login/back
Scope:         openid profile email
```

--------------------------------

### Start and stop TDengine IDMP on Windows PowerShell

Source: https://idmpdocs.taosdata.com/administration/installation/docker-guide

Commands to start and stop the TDengine IDMP services on Windows using PowerShell (admin). Run from the $env:USERPROFILE\.apex\docker directory.

```powershell
cd $env:USERPROFILE\.apex\docker  
.\tdengine.ps1 start  

```

```powershell
cd $env:USERPROFILE\.apex\docker  
.\tdengine.ps1 stop  

```

--------------------------------

### GET /api/v1/elements - 分页查询元素列表

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/client-sdk/api-reference/elements

返回当前用户可访问的元素分页列表，支持按名称或父元素可选过滤。对应 Java 方法 apiV1ElementsGet，Python 方法 api_v1_elements_get。

```APIDOC
## GET /api/v1/elements

### Description
返回当前用户可访问的元素分页列表，支持按名称或父元素可选过滤。

### Method
GET

### Endpoint
/api/v1/elements

### Parameters
#### Query Parameters
- **current** (integer) - Optional - 页码，从 1 开始，默认值 1
- **size** (integer) - Optional - 每页记录数，默认值 20
- **parentId** (integer) - Optional - 按父元素 ID 过滤
- **keyword** (string) - Optional - 按关键字过滤

### Request Example
（无请求体）

### Response
#### Success Response (200)
- **PageOfBasicElementDTO** - 分页元素列表

#### Response Example
（参照 SDK 示例，返回对象未在源码中指定具体结构）

### SDK Examples

#### Java
```java
ElementResourceApi elementApi = apiClient.buildClient(ElementResourceApi.class);
ApiV1ElementsGetQueryParams params = new ApiV1ElementsGetQueryParams()
    .current(1)
    .size(50);
PageOfBasicElementDTO result = elementApi.apiV1ElementsGet(params);
System.out.println("Total elements: " + result.getTotal());
```

#### Python
```python
element_api = idmp_sdk.ElementResourceApi(api_client)
result = element_api.api_v1_elements_get(current=1, size=50)
print(f"Total elements: {result.total}")
for elem in result.rows or []:
    print(f"  {elem.id}: {elem.name}")
```
```

--------------------------------

### Use idmp-cli automatic pagination with --page-all

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/idmp-cli

Enable automatic pagination with `--page-all` for GET commands supporting `current / size` pagination. `--page-limit` caps merged rows (0 means unlimited); `--page-delay` adds intervals between requests to avoid server pressure. If the server does not signal completion, the CLI stops after 500 pages; always pair with `--page-limit` in scripts, CI, and Agent scenarios.

```bash
idmp-cli element +list --size 100 --page-all --page-limit 500 --page-delay 200ms --format table  
idmp-cli api GET /api/v1/elements --params '{"current":1,"size":100}' --page-all --page-limit 500  

```

--------------------------------

### macOS: 下载安装文件

Source: https://idmpdocs.taosdata.com/excel-add-in/installation

在能访问互联网的机器上下载 install.sh 和 manifest.xml，并赋予执行权限。若目录不存在，请先创建。

```bash
mkdir -p ~/Downloads ~/manifest  
curl -fsSL https://taosinstallers.blob.core.windows.net/tdengine-excel-add-in/install.sh -o ~/Downloads/install.sh  
curl -fsSL https://taosinstallers.blob.core.windows.net/tdengine-excel-add-in/manifest.xml -o ~/manifest/manifest.xml  
chmod +x ~/Downloads/install.sh  

```

--------------------------------

### 使用 apex 命令执行自定义部署

Source: https://idmpdocs.taosdata.com/administration/all-in-one-deploy

在 Apex 下载完成后退出流程，参考 `~/.apex/manifests/deployment-xxx.yaml` 创建自定义部署文件，然后执行此命令进行自定义部署。

```bash
apex deploy -f <custom-yaml>  
```

--------------------------------

### Windows: 下载安装文件

Source: https://idmpdocs.taosdata.com/excel-add-in/installation

在能访问互联网的机器上下载 install.ps1 和 manifest.xml。若目录不存在，请先创建。

```powershell
New-Item -ItemType Directory -Force -Path C:\Scripts, C:\manifest  
Invoke-WebRequest -Uri https://taosinstallers.blob.core.windows.net/tdengine-excel-add-in/install.ps1 -OutFile C:\Scripts\install.ps1  
Invoke-WebRequest -Uri https://taosinstallers.blob.core.windows.net/tdengine-excel-add-in/manifest.xml -OutFile C:\manifest\manifest.xml  

```

--------------------------------

### 检查 Docker 服务

Source: https://idmpdocs.taosdata.com/administration/all-in-one-deploy/docker-deployment

确认 Docker 服务正常运作，用于准备 Docker 步骤。

```bash
docker info

```

--------------------------------

### 启动 Docker 并设置开机自启 (Linux)

Source: https://idmpdocs.taosdata.com/administration/all-in-one-deploy/docker-deployment

在有需要时启动 Docker 服务并设置开机自启，适用于权限不足场景。

```bash
systemctl start docker
systemctl enable docker

```

--------------------------------

### 设置 CA 证书目录扫描

Source: https://idmpdocs.taosdata.com/ai-powered-insights/connecting-to-llm

指定目录路径，自动发现目录下所有 .pem 和 .crt 文件。

```bash
export IDMP_TLS_CA_BUNDLE=/etc/idmp/certs/  
```

--------------------------------

### macOS: 使用 launchctl 管理 TDengine IDMP 服务

Source: https://idmpdocs.taosdata.com/administration/installation/install-guide

使用 launchctl 命令启动、查看状态和停止 TDengine IDMP 服务。需要管理员权限。

```bash
sudo launchctl start com.taosdata.tdengine-idmp-h2  
sudo launchctl start com.taosdata.tdengine-idmp-backend  
sudo launchctl start com.taosdata.tdengine-idmp-ui  
sudo launchctl start com.taosdata.tdengine-idmp-chat  

sudo launchctl list | grep tdengine-idmp  
sudo launchctl print system/com.taosdata.tdengine-idmp-backend  

```

--------------------------------

### Linux: 使用 svc-tdengine-idmp 启动服务

Source: https://idmpdocs.taosdata.com/administration/installation/install-guide

使用 svc-tdengine-idmp 命令启动 TDengine IDMP 服务。需要 root 权限，非 root 用户需加 sudo。

```bash
sudo svc-tdengine-idmp start  

```

--------------------------------

### Linux: 查看和停止 svc-tdengine-idmp 服务

Source: https://idmpdocs.taosdata.com/administration/installation/install-guide

使用 svc-tdengine-idmp 命令查看服务状态和停止服务。需要 root 权限。

```bash
sudo svc-tdengine-idmp status  
sudo svc-tdengine-idmp stop  

```

--------------------------------

### GET /api/v1/events

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/client-sdk/api-reference/events

分页查询事件列表，支持按时间范围、状态、严重级别和元素可选过滤。

```APIDOC
## GET /api/v1/events

### Description
分页查询事件列表，支持按时间范围、状态、严重级别和元素可选过滤。

### Method
GET

### Endpoint
/api/v1/events

### Parameters
#### Query Parameters
- **fromTime** (long) - Optional - 开始时间，Unix 毫秒时间戳
- **toTime** (long) - Optional - 结束时间，Unix 毫秒时间戳
- **status** (EventStatus) - Optional - 按事件状态过滤
- **elementId** (integer) - Optional - 按元素 ID 过滤
- **current** (integer) - Optional - 页码，从 1 开始
- **size** (integer) - Optional - 每页记录数

### Request Example
```
EventResourceApi eventApi = apiClient.buildClient(EventResourceApi.class);
ApiV1EventsGetQueryParams params = new ApiV1EventsGetQueryParams()
    .current(1)
    .size(50)
    .fromTime(System.currentTimeMillis() - 86400_000L);
PageOfEventDetailDTO events = eventApi.apiV1EventsGet(params);
System.out.println("Events: " + events.getTotal());
```

### Response
#### Success Response (200)
- **total** (integer) - 总记录数
- **records** (array of EventDetailDTO) - 事件详情列表

#### Response Example
```
{
  "total": 100,
  "records": []
}
```
```

--------------------------------

### 测试镜像拉取

Source: https://idmpdocs.taosdata.com/administration/all-in-one-deploy/docker-deployment

直接测试 Docker 镜像拉取是否正常，用于排查拉取失败问题。

```bash
docker pull <image-name>

```

--------------------------------

### GET /api/v1/events/{eventId}

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/client-sdk/api-reference/events

根据 ID 获取单个事件。

```APIDOC
## GET /api/v1/events/{eventId}

### Description
根据 ID 获取单个事件。

### Method
GET

### Endpoint
/api/v1/events/{eventId}

### Parameters
#### Path Parameters
- **eventId** (string) - Required - 事件 ID

### Response
#### Success Response (200)
- **event** (EventDetailDTO) - 事件详情

#### Response Example
```
{
  "event": {}
}
```
```

--------------------------------

### Copy EasyUse skills to OpenCode

Source: https://idmpdocs.taosdata.com/administration/easyuse

Creates the .opencode directory and copies the three EasyUse skills (idmp-easyuse, idmp-sample-data-generator, idmp-structure-exporter) from the cloned agent-skills repository into the OpenCode skills directory. Run from the working directory where OpenCode is executed.

```bash
mkdir .opencode  
  
cp -r agent-skills的路径/skills/idmp-easyuse                  .opencode/skills/idmp-easyuse  
cp -r agent-skills的路径/skills/idmp-sample-data-generator    .opencode/skills/idmp-sample-data-generator  
cp -r agent-skills的路径/skills/idmp-structure-exporter       .opencode/skills/idmp-structure-exporter  

```

--------------------------------

### 检查主机存储和 Docker 磁盘使用

Source: https://idmpdocs.taosdata.com/administration/all-in-one-deploy/docker-deployment

使用 df -h 和 docker system df 检查磁盘空间，用于排查磁盘空间不足。

```bash
df -h
docker system df

```

--------------------------------

### Uninstall TDengine IDMP on Linux/macOS (rmidmp, rpm, dpkg)

Source: https://idmpdocs.taosdata.com/administration/installation/install-guide

Uninstall TDengine IDMP on Linux/macOS. Use 'rmidmp -e yes' to remove data, logs, and configuration, or 'rmidmp -e no' to preserve them. For rpm-based installations use 'rpm -e tdengine-idmp'; for deb-based installations use 'dpkg -r tdengine-idmp'.

```bash
rmidmp -e yes  
```

```bash
rmidmp -e no  
```

```bash
rpm -e tdengine-idmp  
```

```bash
dpkg -r tdengine-idmp  
```

--------------------------------

### GET /api/v1/elements/{elementId} - 根据 ID 获取单个元素

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/client-sdk/api-reference/elements

根据元素 ID 获取单个元素。对应 Java 方法 apiV1ElementsElementIdGet，Python 方法 api_v1_elements_element_id_get。

```APIDOC
## GET /api/v1/elements/{elementId}

### Description
根据元素 ID 获取单个元素。

### Method
GET

### Endpoint
/api/v1/elements/{elementId}

### Parameters
#### Path Parameters
- **elementId** (integer) - Required - 元素 ID

### Request Example
（无请求体）

### Response
#### Success Response (200)
- **ElementDTO** - 元素信息

#### Response Example
（参照 SDK 示例，返回对象未在源码中指定具体结构）

### Error Responses
- **404** - 元素未找到（ApiException(404)）

### SDK Examples

#### Java
```java
ElementDTO element = elementApi.apiV1ElementsElementIdGet(123L);
System.out.println(element.getName());
```

#### Python
```python
element = element_api.api_v1_elements_element_id_get(123)
print(element.name)
```
```

--------------------------------

### EasyUse 完整示例：创建污水处理 Demo

Source: https://idmpdocs.taosdata.com/administration/easyuse

完整示例，用于创建污水处理 Demo。执行后 EasyUse 会依次解析业务需求、构建资产模型与资产树、生成模拟时序数据、创建实时分析、创建可视化面板，并输出 Demo 生成报告。请勿指定任何已存在的数据库，因为执行过程中有删除指定数据库的风险。

```text
/idmp-easyuse 创建污水处理demo。  
```

--------------------------------

### Pagination response format

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/client-sdk/core-concepts

Response format for all list endpoints. Use the `current` and `size` query parameters to control pagination; `current` starts at 1.

```json
{  
  "current": 1,         // 当前页码（从 1 开始）  
  "size": 20,           // 每页记录数  
  "total": 100,         // 总记录数  
  "rows": [...]         // 当前页的记录  
}  

```

--------------------------------

### 安装 Java SDK 到本地 Maven 仓库

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/client-sdk/installation

在 idmp-java-sdk 目录下执行 Maven 命令，跳过测试，将 SDK 安装到本地 Maven 仓库。

```bash
cd idmp-java-sdk  
mvn install -DskipTests  
```

--------------------------------

### Unix millisecond timestamp calculation

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/client-sdk/core-concepts

Python example for computing Unix millisecond timestamps (UTC) for the last hour, as required by all time parameters and return values.

```python
import time  
  
# 查询最近 1 小时的数据  
now_ms = int(time.time() * 1000)  
one_hour_ago_ms = now_ms - 3600 * 1000  

```

--------------------------------

### SDK 包内容结构

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/client-sdk

SDK 包的结构，包含 OpenAPI 规范文件 idmp-v.json、Java SDK 源码和编译后的 JAR，以及 Python SDK 源码。

```text
idmp-sdk-/  
  ├── idmp-v.json    # OpenAPI 规范——用于为其他语言生成 SDK  
  ├── idmp-java-sdk/              # Java SDK 源码和编译后的 JAR  
  └── idmp-python-sdk/            # Python SDK 源码  

```

--------------------------------

### Linux: 使用 systemctl 管理 TDengine IDMP 服务

Source: https://idmpdocs.taosdata.com/administration/installation/install-guide

使用 systemctl 命令启动、查看状态和停止 TDengine IDMP 服务。需要 root 权限。

```bash
sudo systemctl start tdengine-idmp-h2  
sudo systemctl start tdengine-idmp-backend  
sudo systemctl start tdengine-idmp-ui  
sudo systemctl start tdengine-idmp-chat  

sudo systemctl status tdengine-idmp-backend  
sudo systemctl stop tdengine-idmp-ui  
sudo systemctl stop tdengine-idmp-backend  
sudo systemctl stop tdengine-idmp-chat  
sudo systemctl stop tdengine-idmp-h2  

```

--------------------------------

### Restart IDMP on Windows

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/connect-oss-tsdb

Stop and start the IDMP service on Windows using the provided batch scripts. Alternatively, use the Windows Service Manager to restart the tdengine-idmp, tdengine-idmp-h2, and tdengine-idmp-chat services.

```batch
C:\TDengine\idmp\bin\stop-tdengine-idmp.bat  
C:\TDengine\idmp\bin\start-tdengine-idmp.bat  

```

--------------------------------

### 在 Docker 容器中检索注册激活码

Source: https://idmpdocs.taosdata.com/troubleshooting/troubleshooting

在断网或无私有邮件时，通过 Docker 容器日志检索注册验证码。命令在容器 tdengine-idmp 中执行，搜索关键词 'register verify code for' 并显示最后 10 条匹配。

```bash
docker exec -it tdengine-idmp sh -c \  
  'grep -n "register verify code for" /var/log/taos/tda.log | tail -10'  
```

--------------------------------

### OpenCode /init command

Source: https://idmpdocs.taosdata.com/administration/easyuse

Optional initialization command to run in the OpenCode interactive interface on first use.

```text
/init  
```

--------------------------------

### OAuth TLS configuration example

Source: https://idmpdocs.taosdata.com/administration/user-management

YAML configuration to use a named TLS configuration for OAuth/ADFS HTTPS certificate validation when endpoints use private CA or self-signed certificates. trust-all: true is only recommended for testing; production should use a trusted certificate store.

```yaml
tda:
  oauth:
    tls-configuration-name: oauth-client

quarkus:
  tls:
    oauth-client:
      trust-all: true
```

--------------------------------

### 检查容器资源使用情况

Source: https://idmpdocs.taosdata.com/administration/all-in-one-deploy/docker-deployment

使用 docker stats 查看容器资源占用，用于排查内存不足问题。

```bash
docker stats

```

--------------------------------

### 验证 Python SDK 安装

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/client-sdk/installation

使用 python -c 命令导入 idmp_sdk 并打印成功信息，验证 SDK 是否安装成功。

```bash
python -c "import idmp_sdk; print('SDK installed successfully')"  
```

--------------------------------

### JWT login via UserResourceApi (Java and Python)

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/client-sdk/authentication

Both examples call the login endpoint with credentials from environment variables (IDMP_HOST, IDMP_USERNAME, IDMP_PASSWORD). The Java client sets the returned JWT as a bearer token so subsequent requests include it automatically; the Python client stores the token in the BEARER_TOKEN environment variable for later use.

```java
import org.openapitools.client.ApiClient;  
import org.openapitools.client.api.UserResourceApi;  
import org.openapitools.client.model.LoginReqDTO;  
import org.openapitools.client.model.LoginRspDTO;  
  
ApiClient apiClient = new ApiClient("Authorization");  
apiClient.setBasePath(System.getenv("IDMP_HOST"));  
  
UserResourceApi userApi = apiClient.buildClient(UserResourceApi.class);  
LoginReqDTO req = new LoginReqDTO();  
req.setLoginName(System.getenv("IDMP_USERNAME"));  
req.setPassword(System.getenv("IDMP_PASSWORD"));  
  
LoginRspDTO rsp = userApi.apiV1UsersLoginPost(req);  
apiClient.setBearerToken(rsp.getToken());  // subsequent requests include this token automatically  

```

```python
import os, idmp_sdk  
  
configuration = idmp_sdk.Configuration(host=os.environ["IDMP_HOST"])  
  
with idmp_sdk.ApiClient(configuration) as api_client:  
    user_api = idmp_sdk.UserResourceApi(api_client)  
    rsp = user_api.api_v1_users_login_post(  
        idmp_sdk.LoginReqDTO(  
            login_name=os.environ["IDMP_USERNAME"],  
            password=os.environ["IDMP_PASSWORD"]  
        )  
    )  
    # Store the token in an environment variable for subsequent use  
    os.environ["BEARER_TOKEN"] = rsp.token  

```

--------------------------------

### 下载并启动 Apex 部署工具

Source: https://idmpdocs.taosdata.com/administration/all-in-one-deploy/installation-on-linux

以 root 身份执行此命令，下载 Apex 部署工具并启动部署流程。部署过程中需选择 All-in-One 选项。

```bash
curl -fsSL https://downloads.taosdata.com/apex/latest/install.sh | bash -s -- -m apex  
```

--------------------------------

### 从私有 PyPI 服务器安装 SDK

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/client-sdk/installation

将 SDK 源码上传到私有 PyPI 服务器后，使用 --index-url 指定索引地址进行安装。

```bash
pip install idmp-sdk --index-url https://your-pypi-server/simple/  
```

--------------------------------

### 查看容器状态

Source: https://idmpdocs.taosdata.com/administration/all-in-one-deploy/docker-deployment

查看所有容器的状态，用于排查容器启动后退出或反复重启问题。

```bash
docker ps -a

```

--------------------------------

### 添加 hosts 条目以使用内置测试证书

Source: https://idmpdocs.taosdata.com/excel-add-in/installation

使用内置测试证书时，在客户端机器的 hosts 文件中添加此条目，将 IP 替换为实际服务器地址。hosts 文件位置：Linux/macOS 为 /etc/hosts，Windows 为 C:\Windows\System32\drivers\etc\hosts。

```text
192.168.1.100  idmp.tdengine.net  

```

--------------------------------

### 生成目标语言 SDK（Go 示例）

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/client-sdk

使用 OpenAPI Generator 生成目标语言 SDK 的命令示例，这里以 Go 为例。将 -g go 替换为目标语言名称。

```bash
# 示例：生成 Go SDK  
java -jar openapi-generator-cli.jar generate \  
  -i idmp-v.json \  
  -g go \  
  -o idmp-go-sdk \  
  --skip-validate-spec  

```

--------------------------------

### Python：使用用户 API Key 配置 idmp_sdk

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/client-sdk/authentication

在 Python 中通过环境变量 IDMP_HOST 和 IDMP_API_KEY 创建 idmp_sdk.Configuration，用于用户 API Key 认证。

```python
import os, idmp_sdk  
  
configuration = idmp_sdk.Configuration(  
    host=os.environ["IDMP_HOST"],  
    access_token=os.environ["IDMP_API_KEY"]  
)
```

--------------------------------

### Shell：设置云服务认证环境变量

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/client-sdk/authentication

导出云服务认证所需的三个环境变量：CLOUD_HOST（实例地址）、CLOUD_TOKEN（Access-token）和 BEARER_TOKEN（不含 Bearer 前缀的 Authorization 值）。

```bash
export CLOUD_HOST=https://<instance-id>.idmp.taosdata.com  
export CLOUD_TOKEN=<Access-token 的值>  
export BEARER_TOKEN=<Authorization Token 的值（不含 "Bearer " 前缀）>
```

--------------------------------

### 检查 Docker 版本

Source: https://idmpdocs.taosdata.com/administration/all-in-one-deploy/docker-deployment

确认 Docker 已安装并查看版本信息。

```bash
docker version

```

--------------------------------

### Verify skills with /skills command

Source: https://idmpdocs.taosdata.com/administration/easyuse

Lists the available skills in the OpenCode session. The output should include idmp-easyuse, idmp-sample-data-generator, and idmp-structure-exporter; if any are missing, restart OpenCode.

```bash
/skills  

```

--------------------------------

### Windows: 使用 sc 命令查看服务状态

Source: https://idmpdocs.taosdata.com/administration/installation/install-guide

使用 sc 命令查询 TDengine IDMP 服务状态。

```batch
sc.exe query tdengine-idmp-h2  
sc.exe query tdengine-idmp-chat  
sc.exe query tdengine-idmp-cls  
sc.exe query tdengine-idmp-backend  
sc.exe query tdengine-idmp-ui  

```

--------------------------------

### EasyUse 命令基础格式

Source: https://idmpdocs.taosdata.com/administration/easyuse

基础命令格式，用于在 OpenCode 会话中调用 EasyUse 技能。请勿指定任何已存在的数据库，因为执行过程中有删除指定数据库的风险。

```text
/idmp-easyuse <业务场景描述>。  
```

--------------------------------

### 查看容器日志

Source: https://idmpdocs.taosdata.com/administration/all-in-one-deploy/docker-deployment

用于查看 TDengine All-in-One 容器日志，替换 <container-name> 为实际容器名。

```bash
docker logs <container-name>

```

--------------------------------

### Windows: 使用批处理脚本启动服务

Source: https://idmpdocs.taosdata.com/administration/installation/install-guide

使用批处理脚本启动 TDengine IDMP 服务。需要管理员权限。

```batch
C:\TDengine\idmp\bin\start-tdengine-idmp.bat  

```

--------------------------------

### Linux 部署 TDengine All-in-One

Source: https://idmpdocs.taosdata.com/administration/all-in-one-deploy/docker-deployment

以 root 身份执行该命令，下载并运行安装脚本，以容器方式部署。

```bash
curl -fsSL https://downloads.taosdata.com/apex/latest/install.sh | bash -s -- -m docker

```

--------------------------------

### Linux 重启 Docker 配置

Source: https://idmpdocs.taosdata.com/administration/all-in-one-deploy/docker-deployment

重新加载 daemon.json 配置并重启 Docker 服务。

```bash
systemctl daemon-reload && systemctl restart docker

```

--------------------------------

### 验证 Java SDK 安装

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/client-sdk/installation

在项目中添加 import 语句，如果编译没有报错，说明 SDK 已正确安装。

```java
import org.openapitools.client.ApiClient;  
// If this compiles, the SDK is installed correctly  
```

--------------------------------

### info - sample scenario information

Source: https://idmpdocs.taosdata.com/administration/sample-data

Defines the info section used to display the scenario in the IDMP sample scenario list. The name must be unique, and the file value must match the actual file name.

```json
{  
  "id": "smart_meters",  
  "name": "智能电表",  
  "description": "智能电表示例场景",  
  "file": "init.json",  
  "image": "smart_meters.jpg"  
}  
```

--------------------------------

### Windows: 使用批处理脚本停止服务

Source: https://idmpdocs.taosdata.com/administration/installation/install-guide

使用批处理脚本停止 TDengine IDMP 服务。需要管理员权限。

```batch
C:\TDengine\idmp\bin\stop-tdengine-idmp.bat  

```

--------------------------------

### Windows: 使用 sc 命令启动服务

Source: https://idmpdocs.taosdata.com/administration/installation/install-guide

使用 sc 命令启动 TDengine IDMP 服务。

```batch
sc.exe start tdengine-idmp-h2  
sc.exe start tdengine-idmp-chat  
sc.exe start tdengine-idmp-cls  
sc.exe start tdengine-idmp-backend  
sc.exe start tdengine-idmp-ui  

```

--------------------------------

### Linux 配置 registry-mirrors

Source: https://idmpdocs.taosdata.com/administration/all-in-one-deploy/docker-deployment

编辑 /etc/docker/daemon.json 添加阿里云镜像加速器。

```json
{
  "registry-mirrors": [
    "https://tdengine-registry.cn-beijing.cr.aliyuncs.com"
  ]
}

```

--------------------------------

### 配置私有 Maven 仓库

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/client-sdk/installation

当开发环境无法访问互联网时，在 pom.xml 中配置私有仓库 URL，用于从私有仓库下载 SDK。

```xml
<repositories>  
  <repository>  
    <id>private-repo</id>  
    <url>https://your-maven-repo/repository/maven-releases/</url>  
  </repository>  
</repositories>  
```

--------------------------------

### Windows: 使用 sc 命令停止服务

Source: https://idmpdocs.taosdata.com/administration/installation/install-guide

使用 sc 命令停止 TDengine IDMP 服务。

```batch
sc.exe stop tdengine-idmp-ui  
sc.exe stop tdengine-idmp-backend  
sc.exe stop tdengine-idmp-cls  
sc.exe stop tdengine-idmp-chat  
sc.exe stop tdengine-idmp-h2  

```

--------------------------------

### 跳过 TLS 证书验证

Source: https://idmpdocs.taosdata.com/ai-powered-insights/connecting-to-llm

设置 IDMP_TLS_SKIP_VERIFY=true 跳过 TLS 证书验证，仅建议开发/测试环境使用。

```bash
export IDMP_TLS_SKIP_VERIFY=true  
```

--------------------------------

### Copilot CLI 配置文件 mcp-config.json

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/mcp-interface

直接编辑 ~/.copilot/mcp-config.json 配置远程 MCP Server，包含 type、url 和 Authorization 头。

```json
{
  "mcpServers": {
    "tdengine-idmp": {
      "type": "http",
      "url": "https://<IDMP_HOST>:6034/api/v1/mcp/stream",
      "headers": {
        "Authorization": "Bearer <IDMP_API_KEY>"
      }
    }
  }
}
```

--------------------------------

### 重新启动部署脚本

Source: https://idmpdocs.taosdata.com/administration/all-in-one-deploy/installation-on-linux

如果部署异常退出并需要重新启动，执行此命令。

```bash
~/.apex/deploy-scripts/linux/deploy.sh  
```

--------------------------------

### 验证当前用户

Source: https://idmpdocs.taosdata.com/administration/all-in-one-deploy/docker-deployment

用于确认当前登录用户是否为 root，以解决权限不足问题。

```bash
whoami

```

--------------------------------

### Python：云服务双 Token 认证配置 idmp_sdk

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/client-sdk/authentication

在 Python 中配置云服务认证，设置 access_token 为 BEARER_TOKEN，并通过 api_client 添加 Access-token 请求头。

```python
import os, idmp_sdk  
  
configuration = idmp_sdk.Configuration(  
    host=os.environ["CLOUD_HOST"],  
    access_token=os.environ["BEARER_TOKEN"]  
)  
  
with idmp_sdk.ApiClient(configuration) as api_client:  
    # Add the cloud-specific Access-token header  
    api_client.set_default_header("Access-token", os.environ["CLOUD_TOKEN"])  
    # Proceed with normal API calls
```

--------------------------------

### 在 pom.xml 中添加 IDMP SDK 依赖

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/client-sdk/installation

在项目的 pom.xml 中添加 com.taosdata:idmp-sdk 依赖，版本号留空，需根据实际版本填写。

```xml
<dependency>  
  <groupId>com.taosdata</groupId>  
  <artifactId>idmp-sdk</artifactId>  
  <version></version>  
</dependency>  
```

--------------------------------

### Use idmp-cli structured commands for precise control

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/idmp-cli

Structured commands map directly to OpenAPI service, resource, and method. Use when you need explicit `service / resource / method` relationships or when you want to base execution on schema output.

```bash
idmp-cli element elements list --params '{"current":1,"size":20}' --format table  
idmp-cli analysis analyses list --params '{"elementId":"<ELEMENT_ID>","current":1,"size":20}' --format pretty  

```

--------------------------------

### 设置单个 PEM 文件的 CA 证书路径

Source: https://idmpdocs.taosdata.com/ai-powered-insights/connecting-to-llm

通过环境变量 IDMP_TLS_CA_BUNDLE 指定单个 PEM 文件作为自定义 CA 证书路径。

```bash
export IDMP_TLS_CA_BUNDLE=/etc/idmp/certs/ca.pem  
```

--------------------------------

### 在虚拟环境中安装 Python SDK

Source: https://idmpdocs.taosdata.com/integrating-with-other-systems/client-sdk/installation

建议在虚拟环境中安装以避免依赖冲突。创建虚拟环境并激活，然后安装 SDK。

```bash
python -m venv .venv  
source .venv/bin/activate   # Windows: .venv\Scripts\activate  
pip install .  
```

--------------------------------

### 生成服务器证书和证书包

Source: https://idmpdocs.taosdata.com/excel-add-in/certificate-configuration

在 IDMP 服务器上执行，生成服务器私钥、CSR、签署证书并创建证书包。

```bash
# 1. 生成服务器私钥  
openssl genrsa -out privkey.pem 2048  
  
# 2. 生成证书签名请求（CSR）  
openssl req -new -key privkey.pem -out idmp.csr \  
  -subj "/C=CN/ST=Beijing/L=Beijing/O=TDengine/CN=idmp.tdengine.net"  
  
# 3. 创建扩展配置文件  
cat > idmp.ext <<EOF  
subjectAltName = DNS:idmp.tdengine.net  
EOF  
  
# 4. 使用 CA 证书签署服务器证书（有效期 10 年）  
openssl x509 -req -in idmp.csr -CA ca.crt -CAkey ca.key -CAcreateserial \  
  -out idmp.crt -days 3650 -sha256 -extfile idmp.ext  
  
# 5. 创建证书包  
cat idmp.crt ca.crt > certbundle.pem  
  
# 6. 验证证书内容（确认域名是否正确）  
openssl x509 -in certbundle.pem -text -noout | grep -A1 "Subject Alternative Name"  

```

--------------------------------

### 配置 TDengine TSDB 连接 (application.yml)

Source: https://idmpdocs.taosdata.com/get-started/get-started-installer

在配置文件 /usr/local/taos/idmp/config/application.yml (Linux/macOS) 或 C:\TDengine\idmp\config\application.yml (Windows) 中，配置 tda.default-connection 下的连接信息。url 为 TDengine REST 接口地址，默认端口 6041；explorer-url 为 taosExplorer 访问地址，默认端口 6060，远程访问时必须设置为实际 IP 或域名。

```yaml
tda:  
  default-connection:  
    enable: true  
    auth-type: UserPassword  
    url: http://localhost:6041  
    username: root  
    password: taosdata  
    explorer-url: http://localhost:6060  

```

--------------------------------

### 启动所有容器 - Linux & macOS

Source: https://idmpdocs.taosdata.com/administration/all-in-one-deploy/docker-deployment

进入部署目录并执行 tdengine.sh 启动脚本。

```bash
cd ~/.apex/docker
./tdengine.sh start

```

--------------------------------

### 设置混合模式 CA 证书路径

Source: https://idmpdocs.taosdata.com/ai-powered-insights/connecting-to-llm

同时指定单个文件和目录，支持混合文件+目录模式。

```bash
export IDMP_TLS_CA_BUNDLE=/etc/idmp/certs/ca.pem:/etc/idmp/certs/extra/  
```