Create Maxcompute Data Source

创建 MaxCompute 数据源并验证连通性

1. Scenario Description

将 MaxCompute 项目接入 Dataphin 作为数据源，使下游数据开发任务可以读写该 MaxCompute 项目中的数据。

Architecture：Dataphin Tenant → DataSource (MAX_COMPUTE) → MaxCompute Project

支持两种项目模式：

• Basic 项目：仅创建生产环境数据源
• DEV-PROD 项目（开发-生产分离）：先创建生产环境数据源，再创建开发环境数据源并关联

2. Installation

aliyun plugin install --names aliyun-cli-dataphin-public

（详见 references/cli-installation-guide.md）

3. Environment Variables

凭证与环境变量由父 skill alibabacloud-dataphin-skills 统一声明并预检（父 §3 + §4 Authentication + §8 Step 0，先于路由到本 skill 执行）；本 skill 不重复声明。

4. Authentication

Pre-check: Alibaba Cloud Credentials Required

Security Rules:

• NEVER read, echo, or print AK/SK values to terminal or logs
• NEVER ask the user to input AK/SK directly in the conversation or command line
• NEVER use aliyun configure set with literal credential values
• ONLY use aliyun configure list to check credential status

aliyun configure list

Check the output for a valid profile (AK, STS, or OAuth identity).

If no valid profile exists, STOP here.

1. Obtain credentials from Alibaba Cloud Console
2. Configure credentials outside of this session (via aliyun configure in terminal or environment variables in shell profile)
3. Return and re-run after aliyun configure list shows a valid profile

Pre-check: Aliyun CLI >= 3.4.8 required

Run aliyun version to verify >= 3.4.8. If not installed or version too low, install/update from https://aliyuncli.alicdn.com (see references/cli-installation-guide.md for the OS-specific script), or see references/cli-installation-guide.md for installation instructions.

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.

5. RAM Policy

最小权限策略详见 ../../ram-policies.md。

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

1. Read ../../ram-policies.md to get the full list of permissions required by this SKILL
2. Use ram-permission-diagnose skill to guide the user through requesting the necessary permissions
3. Pause and wait until the user confirms that the required permissions have been granted

6. Parameter Confirmation

IMPORTANT: Parameter Confirmation — Before executing any command or API call, ALL user-customizable parameters (e.g., RegionId, instance names, CIDR blocks, passwords, domain names, resource specifications, etc.) MUST be confirmed with the user. Do NOT assume or use default values without explicit user approval.

Endpoint 参考：http://service.<region>.maxcompute.aliyun.com/api，常见 region 如 cn-hangzhou、cn-shanghai、cn-beijing。

7. Observability (MUST follow for every aliyun command)

session-id 由父 skill alibabacloud-dataphin-skills 在套件入口加载时生成（32-char 小写 hex），本子 skill 加载时直接继承同一 session-id，不再重新生成。

Rule: Every aliyun CLI command that calls a cloud API MUST include the --user-agent flag. Local utility commands (e.g. configure, plugin, version) do not support this flag and should be excluded.

--user-agent AlibabaCloud-Agent-Skills/create-maxcompute-data-source/{session-id}

Example (assuming session-id is a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6):

aliyun dataphin-public list-data-source-with-config --op-tenant-id "1234567890123456789" \
  --list-query '{"TypeList":["MAX_COMPUTE"],"Page":1,"PageSize":20}' \
  --user-agent AlibabaCloud-Agent-Skills/create-maxcompute-data-source/a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6

Do not skip, alter the format, or omit --user-agent on any aliyun API command invocation.

8. Core Workflow

TENANT_ID="<19位租户ID>"
SESSION_ID="<inherited from alibabacloud-dataphin-skills>"
UA="--user-agent AlibabaCloud-Agent-Skills/create-maxcompute-data-source/$SESSION_ID"

Step 1：连通性预检（可选但推荐）

创建前先验证 MaxCompute 配置是否连通：

aliyun dataphin-public check-data-source-connectivity \
  --op-tenant-id "$TENANT_ID" \
  --check-command '{
    "Type": "MAX_COMPUTE",
    "ConfigItemList": [
      {"Key": "maxcompute.endpoint", "Value": "<MC_ENDPOINT>"},
      {"Key": "maxcompute.project", "Value": "<MC_PROJECT>"},
      {"Key": "maxcompute.access.id", "Value": "<MC_ACCESS_ID>"},
      {"Key": "maxcompute.access.key", "Value": "<MC_ACCESS_KEY>"}
    ]
  }' $UA

期望返回 "ConnectStatus": true。若为 false，请检查 endpoint / project / AK 是否正确后重试。

Step 2：创建数据源

分支 A：Basic 项目（仅生产环境）

aliyun dataphin-public create-data-source \
  --op-tenant-id "$TENANT_ID" \
  --create-command '{
    "ProdDataSourceCreate": {
      "Name": "<DS_NAME>",
      "Type": "MAX_COMPUTE",
      "Description": "<DS_DESCRIPTION>",
      "CheckActivity": true,
      "ConfigItemList": [
        {"Key": "maxcompute.endpoint", "Value": "<MC_ENDPOINT>"},
        {"Key": "maxcompute.project", "Value": "<MC_PROJECT>"},
        {"Key": "maxcompute.access.id", "Value": "<MC_ACCESS_ID>"},
        {"Key": "maxcompute.access.key", "Value": "<MC_ACCESS_KEY>"}
      ]
    }
  }' $UA

响应：

{
  "Code": "OK",
  "CreateResult": { "ProdDataSourceId": 7461272386043530112 }
}

记录 ProdDataSourceId（字符串保存）。

分支 B：DEV-PROD 项目（生产 + 开发环境）

Step 2a — 创建生产环境数据源（同分支 A），记录 ProdDataSourceId。

Step 2b — 创建开发环境数据源（关联生产侧）：

PROD_DS_ID="<Step 2a 返回的 ProdDataSourceId>"

aliyun dataphin-public create-data-source \
  --op-tenant-id "$TENANT_ID" \
  --create-command '{
    "DevDataSourceCreate": {
      "ProdDataSourceId": "'"$PROD_DS_ID"'",
      "DataSourceCreate": {
        "Name": "<DS_NAME>",
        "Type": "MAX_COMPUTE",
        "Description": "<DS_DESCRIPTION> (DEV)",
        "CheckActivity": true,
        "ConfigItemList": [
          {"Key": "maxcompute.endpoint", "Value": "<MC_ENDPOINT>"},
          {"Key": "maxcompute.project", "Value": "<MC_PROJECT_DEV>"},
          {"Key": "maxcompute.access.id", "Value": "<MC_ACCESS_ID>"},
          {"Key": "maxcompute.access.key", "Value": "<MC_ACCESS_KEY>"}
        ]
      }
    }
  }' $UA

提示：开发环境的 maxcompute.project 推荐与生产环境使用不同的 MaxCompute 项目以实现数据隔离。

记录 DevDataSourceId。

执行前确认（写操作必备）

本 skill 涉及写操作（create-data-source），执行前必须向用户确认：

• 即将创建的数据源名称和类型（MAX_COMPUTE）
• 目标租户 ID
• 项目模式（Basic / DEV-PROD）
• MaxCompute 连接配置（endpoint / project / access.id，不打印 access.key）
• 是否可回滚（可通过 delete-data-source 删除）

仅当用户明确回复"确认 / yes / 执行"后才发起创建命令。

9. Success Verification

Step 1：检查 API 返回

Code: "OK" 且 CreateResult.ProdDataSourceId 非空。

注意：Code: OK 仅代表请求被受理，不代表数据源连通可用。

Step 2：列表反查

aliyun dataphin-public list-data-source-with-config \
  --op-tenant-id "$TENANT_ID" \
  --list-query '{"TypeList":["MAX_COMPUTE"],"Name":"<DS_NAME>","Page":1,"PageSize":20}' $UA

确认返回列表中包含刚创建的数据源（按 Name 匹配）。

Step 3：连通性校验

aliyun dataphin-public check-data-source-connectivity-by-id \
  --op-tenant-id "$TENANT_ID" \
  --id "$PROD_DS_ID" $UA

期望返回 "ConnectStatus": true。

10. Cleanup

aliyun dataphin-public delete-data-source \
  --op-tenant-id "$TENANT_ID" \
  --delete-command '{"Mode":"DEV_PROD","ProdDataSourceId":"'"$PROD_DS_ID"'"}' $UA

Mode 枚举值：

• DEV — 仅删除开发环境数据源
• DEV_PROD — 同时删除开发和生产环境数据源

11. Command Tables

详见 references/related-commands.md。

12. Best Practices + Reference Links

1. 大整数 ID（19 位 snowflake）一律字符串传参（引号包住）
2. 写操作（create/delete）执行前必须 HITL 二次确认
3. DEV-PROD 项目建议开发与生产使用不同的 MaxCompute 项目，实现数据隔离
4. CheckActivity: true 会在创建时自动验证连通性，建议始终开启

常见坑

[Agent 自主发现] deploy.type 自动回填

• 现象：MaxCompute 数据源不需要显式传 deploy.type，服务端会自动填回 RDS
• 结论：可省略 deploy.type，但私有化环境建议显式传入以兼容

[Agent 自主发现] DEV 环境数据源需关联 PROD

• 现象：DEV-PROD 项目下，开发环境数据源必须通过 ProdDataSourceId 关联到已有的生产环境数据源，不能独立创建
• 结论：必须先创建生产环境数据源，获取 ID 后再创建开发环境数据源

[L3 实测发现] delete-data-source 的 ProdDataSourceId 必须字符串传参

• 现象：ProdDataSourceId 以裸整数传入 JSON 时（如 7468647409615827520），CLI 序列化会精度丢失，服务端报“数据源不存在”
• 结论：19 位 snowflake ID 在 --delete-command 和 --create-command 的 JSON 中必须加引号传为字符串（如 "ProdDataSourceId":"7468647409615827520"）

Reference Links

• references/cli-installation-guide.md
• ../../ram-policies.md
• references/acceptance-criteria.md
• references/related-commands.md