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 のエディション：Basic エディション以上が必要です

セキュリティルール：AK/SK の値を読み取る、表示する、または出力することは絶対にしないでください。ユーザーに AK/SK を直接入力させることも絶対にしないでください。認証情報の状態の確認には、aliyun configure list のみを使用してください。

コマンドの形式

• User-Agent（必須）：すべての aliyun CLI コマンドに、呼び出し元を識別するための --user-agent AlibabaCloud-Agent-Skills パラメーターを必ず含めてください。
• 1 行のコマンド：Bash コマンドを実行する際は、必ず 1 行の文字列として組み立ててください。改行に \ を使用しないでください。
• jq の段階的な実行：まず aliyun コマンドを実行して JSON を取得し、その後 jq で整形してください（複数行のセキュリティ確認を避けるため）。
• エンドポイントの指定は必須：--region パラメーターを指定する場合は、必ず --endpoint dataworks.<REGION_ID>.aliyuncs.com も追加してください。--region を指定しない場合は不要です。

パラメーターの確認

コマンドを実行する前に、ユーザーが変更可能なすべてのパラメーターを必ずユーザーに確認してください。値を推測したり、デフォルト値を使用したりしないでください。 例外：会話の中でユーザーがパラメーターの値を明示している場合は、再確認せず、その値を使用してください。

リソースグループ関連のパラメーター（ユーザーによる選択が必須）：VPC、VSwitch、リソースグループ ID（バインド／接続テスト用）。これらはネットワークや課金に関わるため、自動選択しないでください。候補一覧を表示し、ユーザーが明示的に選択する必要があります。選択肢が 1 つしかない場合も確認してください。

⚠️ 書き込み 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 モードでは Dev と Prod のペアが必要です。純粋なストレージタイプのデータソース（MySQL、Kafka など）のみ、個別に作成する必要があります
4. リソースグループの作成／バインド — 既存のリソースグループを検索してユーザーに選択してもらい、バインドします。リソースグループがない場合は、作成を案内します
5. 接続テスト — バインド済みのリソースグループでテストします。すべて成功したら、「インフラストラクチャの設定が完了しました」と伝えます

各手順の後、次の操作を積極的に提案します。

---

次の手順の案内

書き込み操作を完了して検証した後は、次の操作を積極的に提案します。

完了した操作	推奨される次の手順
コンピューティングリソースの作成	Standard モード：「対応する Dev リソースを作成しますか？」「接続テストを行いますか？」
データソースを個別に作成	「接続テストを行いますか？」「Standard モードの場合、Dev／Prod 環境のデータソースを作成しますか？」
リソースグループの作成	「ワークスペースにバインドしますか？」
リソースグループのバインド	「データソースの接続テストを行いますか？」
接続テストに成功	「インフラストラクチャの準備ができました。」
接続テストに失敗	エラーの原因を分析し、修正を案内します
リソースグループのバインド解除	「別のワークスペースにバインドしますか？」

---

トリガールール

トリガーされるシナリオ：データソースの作成／照会、コンピューティングリソースの作成／照会、リソースグループの管理、インフラストラクチャの初期化、口語的な別名（DW データベース接続エラー、holo／mc リソースの設定、rg の作成）

トリガーされないシナリオ：データ開発タスク、スケジューリング設定、MaxCompute テーブル管理、データ統合タスク、ECS／RDS／OSS、ワークスペースメンバー管理、データ品質／リネージュ／プレビュー。単独のワークスペース照会には alibabacloud-dataworks-workspace-manage スキルを使用します。

対話フロー

すべての操作は次の手順に従います：モジュールの特定 → 環境の確認 → パラメーターの収集 → コマンドの実行 → 結果の検証 → 次の手順の案内

一般的な別名：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 スキルが利用可能な場合は、ワークスペースの照会に優先して使用してください。以下はフォールバック用です。

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

名前で検索する場合は、最初に一覧全体を取得してから、jq を使用して .PagingInfo.Projects[] を Name／DisplayName で絞り込みます。

---

モジュール 1：データソース管理

50 種類のデータソースをサポートしています。詳細は references/data-sources/README.md を参照してください。

データソースを個別に作成する必要があるのはどのような場合ですか？ コンピューティングリソース（モジュール 2）を作成すると、対応するデータソースが自動的に作成されます。純粋なストレージタイプのデータベース（MySQL、PostgreSQL、Kafka、MongoDB など）のみ、個別に作成する必要があります。

注：次のタイプは現在 OpenAPI をサポートしていません：hdfs

接続モード：UrlMode（セルフホストのデータベース。ホスト／ポートが必要）または InstanceMode（Alibaba Cloud のマネージドインスタンス。instanceId が必要）。判断に迷う場合は、ユーザーに積極的に確認してください。InstanceMode を推奨します。

インスタンス照会 API：references/data-sources/instance-apis.md

⚠️ セキュリティ上の制限 — 必須の事前確認については Write API Execution Gate（グローバルルール）を参照してください

重要：DeleteDataSource API と UpdateDataSource API は DataWorks サービスでサポートされていますが、このスキルではセキュリティ上の理由から、データソースの変更および削除を無効化しています。書き込み操作を試みる前に、エージェントは必ず Write API Execution Gate セクションを確認してください。 データソースを変更または削除する必要がある場合は、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 → Simple Mode（データソース 1 個、envType=Prod）
• true → Standard Mode（データソース 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 実行ゲート（グローバルルール）を参照してください

重要：セキュリティ上の理由から、このスキルではコンピュートリソースの変更および削除はサポートしていません。書き込み操作を試みる前に、エージェントは必ず「書き込み 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"

作成後、ステータスが Normal になるまで GetResourceGroup をポーリングしてください（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。エンドポイント：dataworks.<region-id>.aliyuncs.com

全リスト：references/related-apis.md

ベストプラクティス

1. 操作前に確認する — 作成操作の前に現在の状態を確認します
2. 環境ごとに管理する — Dev と Prod のリソースを別々に管理します
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 パラメーターの詳細とリージョンエンドポイント