校验数据源连通性 skill

适用场景

建源前预检：在 create-data-source 之前先用本命令验证 Key/Value 是否正确
调试连接失败：已建数据源改密后先本地验证
不需要真实创建的 ad-hoc 连通性排查

命令 & 官方文档

CLI：aliyun dataphin-public check-data-source-connectivity --help
OpenAPI：CheckDataSourceConnectivity

Authentication

Pre-check: Credentials Required

Security Rules:

NEVER 读取、回显或打印凭证环境变量（禁止对 AccessKey ID / Secret 做任何输出或日志）

NEVER 要求用户在本会话或命令行直接输入 AK/SK

NEVER 使用 aliyun configure set 写入字面量凭证

ONLY 使用 aliyun configure list 检查凭证状态
aliyun configure list
检查输出中是否存在有效 profile（AK、STS 或 OAuth 身份）。

如果没有有效 profile，请在此停止。 先在会话外执行 aliyun configure 配置凭证，aliyun configure list 确认有效后再继续。

Pre-check: Aliyun CLI plugin update required

[MUST] run aliyun configure set --auto-plugin-install true to enable automatic plugin installation. [MUST] run aliyun plugin update to ensure that any existing plugins are always up-to-date.

执行前确认 CLI 与插件版本：
aliyun version
aliyun plugin list

详见 CLI 安装指南。

RAM Policy

[MUST] Permission Failure Handling: When any command or API call fails due to permission errors at any point during execution, follow this process:

Read ../../ram-policies.md to get the full list of permissions required by this SKILL

Use ram-permission-diagnose skill to guide the user through requesting the necessary permissions

Pause and wait until the user confirms that the required permissions have been granted

本 skill 最小权限（dataphin:CheckDataSourceConnectivity / dataphin:CheckDataSourceConnectivityById）见 ../../ram-policies.md。连通性校验为只读探测，不创建/修改任何资源。

IMPORTANT: Parameter Confirmation

执行连通性校验命令前必须向用户确认以下参数，禁止静默提交：

参数	说明
`--tenant-id`	租户 ID（`--op-tenant-id` 的别名，profile 已配置时可省）
`--type`	数据源类型枚举（大写，如 `MYSQL` / `MAX_COMPUTE`）
`--config-item-list`	连接配置项 JSON 对象列表（含 `jdbc.url` / 账号 / 密码等敏感信息，确认后再执行）

本命令为只读探测，不创建数据源；但 --config-item-list 会携带目标库账号密码，务必确认无误、避免误连生产库。

Observability

版本 {version}（Shell 变量 SKILL_VERSION）来自套件 references/manifest.json 的 version 字段，与 session-id 一同继承父技能 §7。直接加载本子技能时先完成父层初始化；所有 CLI / SDK 调用使用父技能名称与同一版本，跨 Shell 调用须重新注入这些值。

本 Skill 属于 alibabacloud-dataphin-skills 套件，继承父 Skill alibabacloud-dataphin-skills 生成的 session-id，子 Skill 不再重新生成。

所有调用 Alibaba Cloud API 的 aliyun 命令必须携带：

--user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/{session-id} skill-version/{version}"

其中 {session-id} 替换为父 Skill 生成的 32 位小写十六进制字符串。

顶层参数骨架

--op-tenant-id, --tenant-id <int>   必填 | 租户 ID（profile 已配置时可省略）
--type <string>                     必填 | 数据源类型枚举（大写，如 MYSQL / MAX_COMPUTE）
--config-item-list <JSON>...        必填 | 连接配置项列表，每个配置项一个 JSON 对象，可重复

⚠ 致命易错点（作者曾踩坑）：本命令没有 --check-command 参数。API 请求体里的 CheckCommand 对象由 CLI 用 --type + --config-item-list 自动组装。若照 --check-command '{...}' 写法调用，该参数会被 CLI 静默忽略、生成空请求体 → 必然失败。可用 --cli-dry-run 先确认组装出的 Body 形如 {"CheckCommand":"{\"ConfigItemList\":[...],\"Type\":\"MYSQL\"}"}。

--config-item-list 写法

--config-item-list 是列表参数：每个配置项写成一个独立 JSON 对象，空格分隔、可重复。CLI 会把它与 --type 一起组装成 API 的 CheckCommand 体（{ "Type": ..., "ConfigItemList": [...] }），无需手写外层结构。

--config-item-list '{"Key":"<k1>","Value":"<v1>"}' '{"Key":"<k2>","Value":"<v2>"}' ...

单个配置项对象结构（Key / Value 均必填）：

{ "Key": "<配置 key>", "Value": "<配置值>" }

Type 与 Key 清单

--type 的枚举值及每种 Type 对应的 ConfigItemList Key 清单，与同套件子 skill create-data-source 完全同构（服务端复用同一套 Provider）。参见该 skill（经套件入口 alibabacloud-dataphin-skills 路由加载）的 "Type 枚举与 ConfigItemList Key 清单" 章节。

✓ MYSQL

aliyun dataphin-public check-data-source-connectivity \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/{session-id} skill-version/{version}" \
  --tenant-id <tenant-id> \
  --type MYSQL \
  --config-item-list \
    '{"Key":"jdbc.url","Value":"<jdbc-url>"}' \
    '{"Key":"jdbc.username","Value":"<your-db-username>"}' \
    '{"Key":"jdbc.password","Value":"<your-db-password>"}'

✓ MAX_COMPUTE

aliyun dataphin-public check-data-source-connectivity \
  --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataphin-skills/{session-id} skill-version/{version}" \
  --tenant-id <tenant-id> \
  --type MAX_COMPUTE \
  --config-item-list \
    '{"Key":"maxcompute.access.id","Value":"<ak_id>"}' \
    '{"Key":"maxcompute.access.key","Value":"<ak_secret>"}' \
    '{"Key":"maxcompute.endpoint","Value":"<endpoint>"}' \
    '{"Key":"maxcompute.project","Value":"<odps_project_name>"}'

⚠ 其他 21 种（unverified）

查阅：CreateDataSource 官方文档末尾的"补充说明"即为各 Type 的 Key 清单（Check 与 Create 共享同一份清单）。

返回判读

响应体关键字段（以 OpenAPI 2023-06-30 CheckDataSourceConnectivity 元数据为准）：

字段	含义
`Success` (boolean)	请求是否成功（仅表示调用链路正常）
`Code` (string)	`OK` 表示请求正常；非 `OK` 通常是参数结构问题（Type 名拼错或 Key 缺失必填）
`Message` (string)	请求错误信息
`Data` (boolean)	连通性校验结果：`true` = 连通，`false` = 不连通

判读规则：

Success: true + Data: true → 连通
Success: true + Data: false → 网络可达但认证/配置错（或白名单未放行），根据 Message 排查
Code 非 OK → 请求参数结构问题（通常是 Type 名拼错或 Key 缺失必填）

注：早期文档曾写 CheckResult: { Connected, Reason } 字段，实为误写；以上字段以 API 元数据为准。

常见坑

Type 必须大写、使用元数据里列出的枚举（如 MYSQL 不是 Mysql）
私有化 MySQL / Oracle 需确保 Dataphin 出口 IP 在目标库白名单内，否则 Connected=false / timeout
MaxCompute endpoint 必须带 https:// 与 /api 后缀
Check 通过不代表 Create 必过；Create 还会校验 Name 唯一性、权限等

check-data-source-connectivity