alibabacloud-dataworks-infra-manage

DataWorks 基础设施管理

在 Alibaba Cloud DataWorks 工作空间中统一管理数据源、计算资源和资源组，支持创建和查询操作。

架构

DataWorks
├── Workspaces ─── Query and search workspaces
│   ├── Data Sources ─── 50 types: MySQL, Hologres, MaxCompute, ...
│   └── Compute Resources ─── Hologres, MaxCompute, Flink, Spark
└── Resource Groups ─── Serverless resource group management (cross-workspace)

Dependencies:
  Workspace ◀── Data Sources, Compute Resources (must belong to a workspace)
  Workspace ◀── Resource Groups (associated via binding; one resource group can bind to multiple workspaces)
  Connectivity Test ──depends on──▶ Resource Group (must be bound to the workspace of the data source)
  Standard Mode ──requires──▶ Dev (Development) + Prod (Production) dual data sources and compute resources

---

全局规则

前提条件

1. Aliyun CLI >= 3.3.1：aliyun version（安装指南：references/cli-installation-guide.md）
2. 首次使用：aliyun configure set --auto-plugin-install true
3. jq（资源组操作必需）：which jq
4. 凭证状态：aliyun configure list，确认存在有效凭证
5. DataWorks 版本：需要基础版或更高版本

安全规则：不得读取、打印或回显 AK/SK 值，不得让用户直接输入 AK/SK，仅使用 aliyun configure list 检查凭证状态。

命令格式

• User-Agent（必需）：所有 aliyun CLI 命令必须包含 --user-agent AlibabaCloud-Agent-Skills 参数，以标识来源。
• 单行命令：执行 Bash 命令时，必须构造为单行字符串；不得使用 \ 换行。
• jq 分步执行：先执行 aliyun 命令获取 JSON，再使用 jq 格式化（避免多行安全提示）。
• Endpoint 必需：指定 --region 参数时，必须同时添加 --endpoint dataworks.<REGION_ID>.aliyuncs.com。未指定 --region 时无需添加。

参数确认

执行任何命令前，必须让用户确认所有可自定义参数。不得假设或使用默认值。 例外：如果用户在对话中明确指定了参数值，可直接使用，无需再次确认。

资源组相关参数（必须由用户选择）：VPC、VSwitch、资源组 ID（用于绑定/连通性测试）——这些参数涉及网络和计费，不得自动选择；必须向用户展示选项列表，由用户明确选择。即使只有一个选项，也必须确认。

⚠️ 写入 API 执行关卡——每次写入操作前都必须检查

必须执行：调用任何写入 API（创建 / 更新 / 删除 / 绑定 / 解绑 / 关联 / 取消关联 / 测试）之前，必须按顺序完成以下检查：

1. 扫描整个 SKILL.md，查找提及目标 API 或模块的安全限制或禁用操作说明。
2. 如果存在限制：立即阻止操作。不得调用 API。向用户说明：
   • 被阻止的操作及原因
   • 建议的替代方案（例如使用 DataWorks 控制台、联系管理员）
3. 如果不存在限制：正常进行参数确认和执行。

此检查不可省略。 每一项写入操作都必须执行，无一例外。绝不得跳过此步骤。

快速参考——此技能中被阻止的 API：

模块	被阻止的 API	原因
数据源（模块 1）	UpdateDataSource、DeleteDataSource	防止意外数据丢失、凭证泄露以及正在运行的任务中断
计算资源（模块 2）	UpdateComputeResource、DeleteComputeResource	防止正在运行的开发和调度任务中断

允许的写入 API：CreateDataSource、CreateComputeResource、CreateResourceGroup、AssociateProjectToResourceGroup、DissociateProjectFromResourceGroup、TestDataSourceConnectivity

RAM 权限

所有操作都需要 dataworks:<APIAction> 权限。创建资源组还需要 AliyunBSSOrderAccess 以及 vpc:DescribeVpcs、vpc:DescribeVSwitches。

完整的权限矩阵：references/ram-policies.md

---

快速入门：新工作空间基础设施初始化

当用户不确定具体操作或需求较为模糊时，请引导其完成以下流程：

1. 环境检查——根据先决条件检查 CLI 和凭证
2. 确认工作空间——使用 ListProjects 定位工作空间，使用 GetProject 确认模式（Simple/Standard）
3. 创建计算资源——引导用户选择引擎类型；系统会自动创建相应的数据源。Standard Mode 需要 Dev+Prod 配对。只有纯存储类型的数据源（MySQL、Kafka 等）需要单独创建
4. 创建/绑定资源组——查询现有资源组 → 让用户选择 → 绑定。没有可用资源组时，引导用户创建
5. 测试连接——使用已绑定的资源组进行测试；全部通过后，告知用户“基础设施配置完成”

每完成一步后，都要主动建议下一步操作。

---

后续步骤引导

每次写入操作完成并验证后，都要主动建议后续操作：

已完成的操作	建议的下一步
创建计算资源	Standard Mode：“创建对应的 Dev 资源？”；“测试连接？”
单独创建数据源	“测试连接？”；Standard Mode：“创建 Dev/Prod 环境数据源？”
创建资源组	“绑定到工作空间？”
绑定资源组	“测试数据源连接？”
连接测试通过	“基础设施已就绪。”
连接测试失败	分析错误原因并引导用户修复
解绑资源组	“绑定到另一个工作空间？”

---

触发规则

触发场景：创建/查询数据源，创建/查询计算资源，资源组管理，基础设施初始化，口语化别称（DW 数据库连接失败，配置 holo/mc 资源，创建 rg）

不触发：数据开发任务，调度配置，MaxCompute 表管理，数据集成任务，ECS/RDS/OSS，工作空间成员管理，数据质量/血缘/预览。单独的工作空间查询由 alibabacloud-dataworks-workspace-manage skill 处理。

交互流程

所有操作都遵循：识别模块 → 环境检查 → 收集参数 → 执行命令 → 验证结果 → 引导下一步

常见别称：DW=DataWorks，holo=Hologres，mc/MC/odps=MaxCompute，pg=PostgreSQL，rg=Resource Group，ds=Data Source，RDS=InstanceMode MySQL/PG/SQLServer，ADB=AnalyticDB

命名建议：数据源 {type}_{business}_{purpose}，计算资源 {type}_{business}，资源组 dw_{purpose}_rg_{env}

---

模块 0：工作空间查询

如果有 alibabacloud-dataworks-workspace-manage skill，优先使用它查询工作空间。以下内容仅作为备用方案。

aliyun dataworks-public ListProjects --user-agent AlibabaCloud-Agent-Skills --Status Available --PageSize 100

按名称搜索时，先获取完整列表，然后使用 jq 按 Name/DisplayName 筛选 .PagingInfo.Projects[]。

---

模块 1：数据源管理

支持 50 种数据源类型。详情请参阅 references/data-sources/README.md。

何时需要单独创建数据源？ 创建计算资源（模块 2）时会自动创建相应的数据源。只有纯存储类型的数据库（MySQL、PostgreSQL、Kafka、MongoDB 等）需要单独创建。

注意：以下类型目前不支持 OpenAPI：hdfs

连接模式：UrlMode（可自托管数据库，需要主机/端口）或 InstanceMode（阿里云托管实例，需要 instanceId）。不确定时，请主动询问用户。优先使用 InstanceMode。

实例查询 API：references/data-sources/instance-apis.md

⚠️ 安全限制 — 有关强制预检，请参阅写入 API 执行门禁（全局规则）

重要：DataWorks 服务支持 DeleteDataSource 和 UpdateDataSource API，但出于安全原因，此技能已禁用修改或删除数据源的功能。尝试任何写入操作前，Agent 必须检查写入 API 执行门禁部分。 如果需要修改或删除数据源，请直接使用 DataWorks 控制台或联系管理员。

连接模式快速参考

ConnectionPropertiesMode 的选择决定必填字段。两种模式都可用时，优先使用 InstanceMode。

模式	类型	数量
两者均支持	mysql, postgresql, sqlserver, polardb, polardbo, polardb-x-2-0, apsaradb_for_oceanbase, drds, starrocks, analyticdb_for_mysql, analyticdb_for_postgresql, milvus, mongodb, redis, elasticsearch, kafka	16
仅 InstanceMode	hologres, dlf, opensearch	3
仅 UrlMode	oracle, mariadb, dm, db2, tidb, vertica, gbase8a, kingbasees, saphana, snowflake, maxcompute, hive, clickhouse, doris, selectdb, redshift, hbase, lindorm, oss, s3, ftp, ssh, tablestore, memcache, graph_database, datahub, loghub, restapi, salesforce, httpfile, bigquery	31

hdfs — 不支持通过 OpenAPI 使用。 完整详情：references/data-sources/README.md

工作空间模式

环境说明：**Prod（生产）**用于生产数据处理；**Dev（开发）**用于开发和调试，与生产环境物理隔离。

aliyun dataworks-public GetProject --user-agent AlibabaCloud-Agent-Skills --Id <PROJECT_ID> — 检查 DevEnvironmentEnabled：

• false → 简单模式（1 个数据源，envType=Prod）
• true → 标准模式（2 个数据源，Dev + Prod，物理隔离）

完整的模式对比：references/data-sources/README.md

任务 1.1：创建数据源（CreateDataSource）

aliyun dataworks-public CreateDataSource --user-agent AlibabaCloud-Agent-Skills [--region <REGION_ID> --endpoint dataworks.<REGION_ID>.aliyuncs.com] --ProjectId <PROJECT_ID> --Name <NAME> --Type <TYPE> --ConnectionPropertiesMode <UrlMode|InstanceMode> --ConnectionProperties '<JSON>' --Description "<DESC>"

ConnectionProperties 通用结构：

• UrlMode：{"envType":"Prod","address":[{"host":"<IP>","port":<PORT>}],"database":"<DB>","username":"<USER>","password":"<PWD>"}
• InstanceMode：{"envType":"Prod","instanceId":"<ID>","regionId":"<REGION>","database":"<DB>","username":"<USER>","password":"<PWD>"}

特殊类型结构（Oracle、MaxCompute、HBase 等）：请参阅 references/data-sources/ 中各类型的文档

跨账号数据源配置：references/cross-account-datasources.md

任务 1.2：获取数据源（GetDataSource）

aliyun dataworks-public GetDataSource --user-agent AlibabaCloud-Agent-Skills --Id <DATASOURCE_ID> [--region <REGION_ID> --endpoint dataworks.<REGION_ID>.aliyuncs.com]

任务 1.3：列出数据源（ListDataSources）

aliyun dataworks-public ListDataSources --user-agent AlibabaCloud-Agent-Skills --ProjectId <PROJECT_ID> [--Types '["mysql"]'] [--EnvType <Dev|Prod>] [--PageNumber 1] [--PageSize 20]

返回嵌套结构 DataSources[].DataSource[]；Name/Type 位于外层，Id/Description 位于内层。

任务 1.4：测试连通性（TestDataSourceConnectivity）

流程：查询资源组列表 → 让用户选择一个资源组 → 执行测试。

# Step 1: Query project resource groups
aliyun dataworks-public ListResourceGroups --user-agent AlibabaCloud-Agent-Skills --ProjectId <PROJECT_ID>

# Step 2: Execute test after user selects a resource group
aliyun dataworks-public TestDataSourceConnectivity --user-agent AlibabaCloud-Agent-Skills --DataSourceId <ID> --ProjectId <PROJECT_ID> --ResourceGroupId "<RG_ID>"

如果出现错误 "resourceGroupId is not in the project"，则需要先绑定资源组（与用户确认后，再执行 AssociateProjectToResourceGroup）。

---

模块 2：计算资源管理

支持 Hologres、MaxCompute、Flink、Spark 等类型。创建时，系统将自动创建相应的数据源。

⚠️ 安全限制 — 必须先查看写入 API 执行门控（全局规则）

重要：出于安全原因，此技能不支持修改或删除计算资源。**在尝试任何写入操作之前，Agent 必须检查“写入 API 执行门控”部分。**这些操作已禁用，以防止：

• 意外丢失数据或中断服务
• 干扰正在运行的数据开发和调度任务
• 意外更改生产计算资源配置

如果需要修改或删除计算资源，请直接使用 DataWorks 控制台，或联系管理员。

authType 规则

• 开发环境：authType 固定为 Executor
• 生产环境：可选项为 PrimaryAccount（推荐）、TaskOwner、SubAccount、RamRole。除非用户有特殊要求，否则默认推荐使用 PrimaryAccount

authType 详情和指南：references/compute-resources/README.md

特定类型说明

• Hologres：仅支持 InstanceMode，需要 instanceId、securityProtocol
• MaxCompute：仅支持 UrlMode，需要 project、endpointMode

完整的 ConnectionProperties 示例：references/compute-resources/README.md

任务 2.1：创建计算资源（CreateComputeResource）

aliyun dataworks-public CreateComputeResource --user-agent AlibabaCloud-Agent-Skills [--region <REGION_ID> --endpoint dataworks.<REGION_ID>.aliyuncs.com] --ProjectId <PROJECT_ID> --Name <NAME> --Type <TYPE> --ConnectionPropertiesMode <InstanceMode|UrlMode> --ConnectionProperties '<JSON>' [--Description "<DESC>"]

创建后，使用 ListDataSources 验证是否已自动生成对应的数据源。

任务 2.2：获取计算资源（GetComputeResource）

aliyun dataworks-public GetComputeResource --user-agent AlibabaCloud-Agent-Skills --Id <ID> --ProjectId <PROJECT_ID>

任务 2.3：列出计算资源（ListComputeResources）

aliyun dataworks-public ListComputeResources --user-agent AlibabaCloud-Agent-Skills --ProjectId <PROJECT_ID> [--Name <FILTER>] [--EnvType <Dev|Prod>] [--PageSize 20] [--SortBy CreateTime] [--Order Desc]

返回嵌套结构 ComputeResources[].ComputeResource[]；Name/Type 位于外层，Id 位于内层。

---

模块 3：资源组管理

管理 Serverless 资源组的完整生命周期。

任务 3.1：创建资源组（CreateResourceGroup）

需要 AliyunBSSOrderAccess 权限。

交互流程（每一步都让用户选择，禁止自动选择）：

1. 查询并选择 VPC：

aliyun vpc DescribeVpcs --user-agent AlibabaCloud-Agent-Skills --RegionId "<REGION_ID>" --PageSize 50

如果列表为空，引导用户创建 VPC；禁止自动创建。

2. 查询并选择 VSwitch：

aliyun vpc DescribeVSwitches --user-agent AlibabaCloud-Agent-Skills --RegionId "<REGION_ID>" --VpcId "<VPC_ID>" --PageSize 50

3. 确认名称和规格 → 执行创建：

aliyun dataworks-public CreateResourceGroup --user-agent AlibabaCloud-Agent-Skills [--region <REGION_ID> --endpoint dataworks.<REGION_ID>.aliyuncs.com] --Name "<NAME>" --PaymentType PostPaid --VpcId "<VPC_ID>" --VswitchId "<VSWITCH_ID>" --ClientToken "$(uuidgen 2>/dev/null || echo "token-$(date +%s)")" --Remark "Created by Agent"

创建后，轮询 GetResourceGroup，直到状态变为 Normal（每 10 秒一次，最长 10 分钟）。

任务 3.2：获取资源组（GetResourceGroup）

aliyun dataworks-public GetResourceGroup --user-agent AlibabaCloud-Agent-Skills --Id "<ID>"

任务 3.3：列出资源组（ListResourceGroups）

aliyun dataworks-public ListResourceGroups --user-agent AlibabaCloud-Agent-Skills [--ProjectId <PROJECT_ID>] [--Statuses '["Normal"]'] --PageSize 100

任务 3.4：绑定资源组（AssociateProjectToResourceGroup）

流程：查询可用资源组 → 向用户显示列表以供选择 → 用户确认后再绑定。

aliyun dataworks-public AssociateProjectToResourceGroup --user-agent AlibabaCloud-Agent-Skills --ResourceGroupId "<RG_ID>" --ProjectId "<PROJECT_ID>"

任务 3.5：查询绑定关系

aliyun dataworks-public ListResourceGroupAssociateProjects --user-agent AlibabaCloud-Agent-Skills --ResourceGroupId "<RG_ID>"

任务 3.6：解绑资源组（DissociateProjectFromResourceGroup）

aliyun dataworks-public DissociateProjectFromResourceGroup --user-agent AlibabaCloud-Agent-Skills --ResourceGroupId "<RG_ID>" --ProjectId "<PROJECT_ID>"

---

成功验证

完成所有写入操作后，使用相应的 Get/List 命令验证结果。

常见错误

错误代码	解决方案
Forbidden.Access / PermissionDenied	检查 RAM 权限，参见 references/ram-policies.md
InvalidParameter	检查 ConnectionProperties JSON 和必需参数
EntityNotExists	确认 ID 和 Region 正确
QuotaExceeded	删除未使用的资源，或申请提高配额
Duplicate*	使用其他名称

地域

常见地域：cn-hangzhou、cn-shanghai、cn-beijing、cn-shenzhen。Endpoint：dataworks.<region-id>.aliyuncs.com

完整列表：references/related-apis.md

最佳实践

1. 先查询，再操作 — 创建前确认当前状态
2. 按环境管理 — 分别管理开发和生产资源
3. 验证操作 — 每次写入操作后使用 Get/List 进行验证
4. 主动提供指导 — 每个步骤完成后建议下一步操作
5. 保护数据源和计算资源 — 切勿通过此技能修改或删除数据源或计算资源；请使用 DataWorks 控制台执行此类操作

参考链接

参考	描述
references/data-sources/README.md	数据源类型列表和 ConnectionProperties 示例
references/data-sources/	各数据源类型的详细配置文档（50 个文件）
references/cross-account-datasources.md	跨账号数据源配置指南
references/compute-resources/README.md	计算资源 ConnectionProperties 示例
references/cli-installation-guide.md	Aliyun CLI 安装指南
references/ram-policies.md	RAM 权限配置和策略示例
references/related-apis.md	API 参数详情和区域终端节点