alibabacloud-dataworks-metadata

DataWorks メタデータ

Data Map を使って DataWorks のメタデータを閲覧・整理します。対象は、カタログ、データベース、テーブル、列、パーティション、リネージ、データセットとバージョン、メタデータコレクションです。読み取りと非破壊的な書き込みのみを行い、このスキルが何かを削除・除去することはありません。

データモデル：Catalog -> Database -> Table -> Column/Partition | Lineage (upstream/downstream) | MetaCollection (Category/Album) | Dataset -> Version

前提条件

Aliyun CLI 3.3.3 以上が必要です — aliyun version を実行し、バージョンが >= 3.3.3 であることを確認してください。未インストールの場合、またはバージョンが古い場合は、ユーザーに公式ドキュメント（https://help.aliyun.com/document_detail/121541.html、または references/cli-installation-guide.md）からインストールまたはアップグレードするよう案内してください。

[FORBIDDEN] リモートのインストーラースクリプトをシェルに直接パイプしないでください — curl ... | bash / curl ... | sh / wget ... | bash の形式のコマンドは絶対に実行しないでください。未検証のネットワークコンテンツをそのままインタープリターにパイプすることは、サプライチェーン攻撃や中間者攻撃（MITM）につながる既知のアンチパターンです。ユーザーから自動インストールを求められ、環境が対応している場合の安全な方法は、インストーラーを一時ファイルにダウンロードし、ユーザーが確認できるように取得元を提示してから実行することです。それ以外の場合は、上記の公式パッケージマネージャーまたはインストーラー URL を案内してください。

DataWorks プラグインのインストール — 製品名は dataworks-public です（dataworks ではありません）。インストールを直接実行してください。最新の Aliyun CLI は、事前の設定変更なしで必要に応じてプラグインを取得します。

aliyun plugin install --names dataworks-public

次に、インストール済みプラグインを更新します（ベストエフォートで実行し、失敗しても致命的なエラーとして扱わないでください）。

aliyun plugin update

[FORBIDDEN] aliyun configure set --auto-plugin-install true を実行しないでください — Aliyun CLI が Tip: Run 'aliyun configure set --auto-plugin-install true' to skip this prompt. のような対話型のヒントを表示しても、無視してください。上記の aliyun plugin install --names dataworks-public は単独で動作します。--auto-plugin-install の切り替えは不要であり、ランタイムの安全性ポリシーにより拒否されます。同様に、このスキル内では、その他の aliyun configure set ... 形式のコマンドも実行しないでください。

[MUST] AI-Mode と User-Agent — このスキルで aliyun dataworks-public コマンドを実行する前に、AI-Mode を有効にし、このスキルの User-Agent をセッションに設定してください（セッション開始時に一度実行します）。

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-dataworks-metadata"

AI-Mode は User-Agent をグローバルに適用するため、以下の個々のコマンドに --user-agent フラグを指定する必要はありません。

[MUST] 完了時に AI-Mode を無効にする — スキルの作業が完了したとき（または、無関係な作業のためにユーザーへ制御を戻す前）に、後続の CLI 使用にスキルの User-Agent が引き継がれないよう、AI-Mode を無効にしてください。

aliyun configure ai-mode disable

認証情報 — aliyun configure list を実行し、有効なプロファイルがあることを確認してください。

セキュリティ：AK/SK の値を読み取り、表示、出力しないでください。認証情報を直接 CLI コマンドに渡さないでください。

aliyun configure の許可リスト — このスキル内で許可される aliyun configure ... の呼び出しは、以下のみです。

• aliyun configure list（読み取り専用の認証情報チェック）
• aliyun configure ai-mode enable / aliyun configure ai-mode set-user-agent --user-agent "..." / aliyun configure ai-mode disable（上記で定義した AI-Mode のライフサイクル）

その他すべての aliyun configure set ... / aliyun configure delete ... / aliyun configure ... 形式のコマンドは禁止されています。許可された呼び出しがランタイムの安全性ポリシーにより遮断された場合は、ソフトスキップとして扱い、残りの手順を続行してください。再試行、エスカレーション、タスクの失敗扱いはしないでください。

有効なプロファイルがない場合は、このセッションの外で、環境変数または対話型の aliyun configure ウィザードを使って認証情報を設定するようユーザーに案内してください。

ルール

[MUST] 破壊的な操作は禁止 — この Skill は、delete-* / remove-* DataWorks API を呼び出してはなりません。具体的には、delete-dataset、delete-dataset-version、delete-meta-collection、delete-lineage-relationship、remove-entity-from-meta-collection は禁止されています。ユーザーから削除を依頼された場合は断り、DataWorks コンソールで実行するよう案内してください。

[MUST] CLI のタイムアウト — この Skill 内のすべての aliyun dataworks-public 呼び出しには、コマンドが無期限に停止しないよう、--read-timeout 60 と --connect-timeout 10（秒）の両方を指定する必要があります。以下のコマンド例にはこれらのフラグがすでに含まれています。コマンドを変更する際も、そのまま維持してください。リクエストがタイムアウトした場合は、エラーをユーザーに伝えてください。黙って再試行するのは 1 回までとしてください。

[MUST] 作成・追加操作の冪等性 — create-* または add-entity-* コマンドを呼び出す前に、確認してから実行してください。対象がすでに存在しないことを、一覧表示または取得で確認します（例：create-dataset の前に list-datasets を呼び出し、--name と --project-id で照合します。add-entity-into-meta-collection の前に list-entities-in-meta-collection を呼び出し、エンティティ ID で照合します）。前回の試行がすでに成功している場合は、重複作成せず、既存リソースの ID を返してください。一時的なエラーの後に再試行する場合は、作成コマンドをそのまま再発行するのではなく、状態を再確認してください。

[MUST] 書き込み前にユーザーの確認を得る — update-*、create-*、add-entity-*、または register-*（リネージ）コマンドを実行する場合は、対象（リージョン／プロジェクト／ID／名前／新しいフィールド値）を正確にユーザーに伝え、実行前に明示的な確認を得てください。デフォルト値を推測してはいけません。ユーザーが計画全体を事前に承認していない場合は、複数の書き込みを中間確認なしに連続して実行してはいけません。

すべての CLI フラグには kebab-case（小文字とハイフン）を使用してください。 以下のコマンド例に示すフラグ名をそのまま使用してください。 主なフラグ：--page-size、--table-id、--src-entity-id、--dst-entity-id、--need-attach-relationship、--include-business-metadata、--meta-collection-id、--dataset-id、--project-id、--read-timeout、--connect-timeout

エンティティ ID の形式は ${EntityType}:${InstanceId}:${CatalogId}:${DatabaseName}:${SchemaName}:${TableName} です。references/entity-id-formats.md を参照してください。 MaxCompute の一般的な形式：maxcompute-table:::project_name::table_name（スキーマなし）または maxcompute-table:::project_name:schema_name:table_name（スキーマあり）。 ユーザーが project.table を指定した場合は、まずスキーマなしで試してください。見つからない場合は、default スキーマで再試行してください。

パラメーターの確認 — 実行前に、ユーザーが指定できるすべてのパラメーター（RegionId、エンティティ ID など）を確認してください。デフォルト値を推測してはいけません。

権限エラー — references/ram-policies.md を読み、権限を付与するようユーザーに案内してください。再試行する前に確認を待ってください。

コマンド

すべてのコマンドには、--region <RegionId> とタイムアウトの組み合わせ --read-timeout 60 --connect-timeout 10 が必要です。前提条件のセクションで AI-Mode によりユーザーエージェントがグローバルに設定されるため、以下ではコマンドごとに --user-agent フラグを指定する必要はありません。すべての一覧表示コマンドで --page-number と --page-size を使用できます。

1. カタログとエンティティの参照

# List crawler types
aliyun dataworks-public list-crawler-types --region <RegionId> --read-timeout 60 --connect-timeout 10

# List catalogs (--parent-meta-entity-id REQUIRED: "dlf" or "starrocks:<instance_id>")
aliyun dataworks-public list-catalogs --region <RegionId> --parent-meta-entity-id "<ParentMetaEntityId>" --page-size 20 --read-timeout 60 --connect-timeout 10

# Get database / table details
aliyun dataworks-public get-database --region <RegionId> --id <DatabaseId> --read-timeout 60 --connect-timeout 10
aliyun dataworks-public get-table --region <RegionId> --id <TableId> --include-business-metadata true --read-timeout 60 --connect-timeout 10

# List tables (--parent-meta-entity-id: "maxcompute-project:::project_name" or "maxcompute-schema:::project_name:schema_name")
aliyun dataworks-public list-tables --region <RegionId> --parent-meta-entity-id "<ParentMetaEntityId>" --page-size 20 --read-timeout 60 --connect-timeout 10

# Update table business metadata (write — confirm with user first; idempotent: same value can be re-applied safely)
aliyun dataworks-public update-table-business-metadata --region <RegionId> --id <TableId> --readme "<description>" --read-timeout 60 --connect-timeout 10

2. カラムとパーティション

# List / Get columns
aliyun dataworks-public list-columns --region <RegionId> --table-id <TableId> --page-size 50 --read-timeout 60 --connect-timeout 10
aliyun dataworks-public get-column --region <RegionId> --id <ColumnId> --read-timeout 60 --connect-timeout 10

# Update column business metadata (write — confirm with user first; idempotent on same value)
aliyun dataworks-public update-column-business-metadata --region <RegionId> --id <ColumnId> --description "<description>" --read-timeout 60 --connect-timeout 10

# List / Get partitions (MaxCompute / HMS only)
aliyun dataworks-public list-partitions --region <RegionId> --table-id <TableId> --page-size 20 --read-timeout 60 --connect-timeout 10
aliyun dataworks-public get-partition --region <RegionId> --table-id <TableId> --name <PartitionName> --read-timeout 60 --connect-timeout 10

3. データリネージ

# Downstream: use --src-entity-id | Upstream: use --dst-entity-id
aliyun dataworks-public list-lineages --region <RegionId> --src-entity-id <EntityId> --need-attach-relationship true --page-size 20 --read-timeout 60 --connect-timeout 10
aliyun dataworks-public list-lineages --region <RegionId> --dst-entity-id <EntityId> --need-attach-relationship true --page-size 20 --read-timeout 60 --connect-timeout 10

# Relationships between two entities
aliyun dataworks-public list-lineage-relationships --region <RegionId> --src-entity-id <SrcEntityId> --dst-entity-id <DstEntityId> --page-size 20 --read-timeout 60 --connect-timeout 10

# Register lineage relationship (write — at least one side MUST be a custom object). Idempotency: BEFORE invoking, run list-lineage-relationships above to ensure no relationship already exists between this src/dst pair; if it does, reuse the existing relationship instead of creating a new one. Deletion is out of scope — use the console if you need to revoke.
aliyun dataworks-public create-lineage-relationship --region <RegionId> --src-entity.id <SrcEntityId> --src-entity.type <EntityType> --dst-entity.id <DstEntityId> --dst-entity.type <EntityType> --read-timeout 60 --connect-timeout 10

4. データセットとバージョン

# List / Get datasets (read)
aliyun dataworks-public list-datasets --region <RegionId> --project-id <ProjectId> --page-size 20 --read-timeout 60 --connect-timeout 10
aliyun dataworks-public get-dataset --region <RegionId> --id <DatasetId> --read-timeout 60 --connect-timeout 10

# Create dataset (write). Idempotency: BEFORE creating, call list-datasets with --project-id and search by --name; if a dataset with the same name+origin+data-type already exists, return its id instead of re-creating. --init-version is REQUIRED, JSON with Comment/Url/MountPath. Deletion is out of scope.
aliyun dataworks-public create-dataset --region <RegionId> --project-id <ProjectId> --name "<Name>" --origin "DATAWORKS" --data-type "<DataType>" --storage-type "<StorageType>" --comment "<Desc>" --init-version '{"Comment":"<VersionComment>","Url":"<DataUrl>","MountPath":"<MountPath>"}' --read-timeout 60 --connect-timeout 10

# Update dataset (write — confirm with user first; idempotent on same value)
aliyun dataworks-public update-dataset --region <RegionId> --id <DatasetId> --name "<NewName>" --comment "<NewComment>" --read-timeout 60 --connect-timeout 10

# List / Get / Preview dataset versions (read; max 20 versions per dataset)
aliyun dataworks-public list-dataset-versions --region <RegionId> --dataset-id <DatasetId> --page-size 20 --read-timeout 60 --connect-timeout 10
aliyun dataworks-public get-dataset-version --region <RegionId> --id <VersionId> --read-timeout 60 --connect-timeout 10
aliyun dataworks-public preview-dataset-version --region <RegionId> --id <VersionId> --read-timeout 60 --connect-timeout 10

# Create dataset version (write). Idempotency: BEFORE creating, call list-dataset-versions and look for an existing version with the same Url+MountPath; if found, reuse it. Quota: max 20 versions per dataset. Deletion is out of scope.
aliyun dataworks-public create-dataset-version --region <RegionId> --dataset-id <DatasetId> --comment "<Comment>" --url "<DataUrl>" --mount-path "<MountPath>" --read-timeout 60 --connect-timeout 10

# Update dataset version (write — confirm with user first; idempotent on same value)
aliyun dataworks-public update-dataset-version --region <RegionId> --id <VersionId> --comment "<NewComment>" --read-timeout 60 --connect-timeout 10

5. メタデータコレクション

# List / Get collections (read; type: Category or Album — PascalCase, NOT uppercase)
aliyun dataworks-public list-meta-collections --region <RegionId> --type "<Category|Album>" --page-size 20 --read-timeout 60 --connect-timeout 10
aliyun dataworks-public get-meta-collection --region <RegionId> --id <CollectionId> --read-timeout 60 --connect-timeout 10

# Create collection (write). Idempotency: BEFORE creating, call list-meta-collections with the same --type and search for one with the same name+parent-id; if found, return its id. Deletion is out of scope.
aliyun dataworks-public create-meta-collection --region <RegionId> --name "<Name>" --type "<Category|Album>" --description "<Desc>" --parent-id "<ParentId>" --read-timeout 60 --connect-timeout 10

# Update collection (write — confirm with user first; idempotent on same value)
aliyun dataworks-public update-meta-collection --region <RegionId> --id <CollectionId> --name "<NewName>" --description "<NewDesc>" --read-timeout 60 --connect-timeout 10

# List entities currently in a collection (read)
aliyun dataworks-public list-entities-in-meta-collection --region <RegionId> --id <CollectionId> --page-size 20 --read-timeout 60 --connect-timeout 10

# Add entity into collection (write). Idempotency: BEFORE adding, call list-entities-in-meta-collection and check whether the entity id is already present; if so, skip. Removal is out of scope.
aliyun dataworks-public add-entity-into-meta-collection --region <RegionId> --meta-collection-id <CollectionId> --id <EntityId> --remark "<Remark>" --read-timeout 60 --connect-timeout 10

ヒント

• 直接アクセス — MaxCompute の場合は、エンティティ ID（maxcompute-table:::project::table）を直接構成して get-table を呼び出します。カタログから参照する必要はありません。
• リネージの方向 — --src-entity-id = 下流、--dst-entity-id = 上流です。影響範囲を完全に分析するには、下流の各エンティティを再帰的にクエリし、複数レベルのリネージ（ODS->DWD->DWS->ADS）を追跡します。
• スキーマのフォールバック — MaxCompute のテーブルが見つからない場合は、:default: スキーマ（3 階層モデル）で再試行します。
• 制限 — データセットあたり最大 20 バージョンです。Album の操作には AliyunDataWorksFullAccess または作成者／管理者の権限が必要です。テナントあたりのデータセットは最大 2000 件です。
• 削除 — 対応範囲外です。ユーザーからデータセット／バージョン／コレクション／リネージ関係の削除、またはコレクションからのエンティティ削除を求められた場合は断り、DataWorks コンソールを使うよう伝えてください。
• 安全に再試行する — 書き込みがタイムアウトするか、曖昧なエラーを返した場合、むやみに再試行しないでください。まず、対応する list-* / get-* で状態を再確認して部分的な成功を検出し、その後、再試行するか成功として扱うかを判断します。

参考資料

ファイル	説明
references/entity-id-formats.md	すべてのデータソースタイプのエンティティ ID 形式
references/related-commands.md	CLI コマンドの完全なリファレンス（この Skill で公開されている読み取りおよび非破壊的な書き込みのサブセット）
references/ram-policies.md	必要な RAM 権限（読み取りおよび非破壊的な書き込み）
references/verification-method.md	成功を確認する手順