alibabacloud-pai-workspace-manage

PAI ワークスペース管理

Alibaba Cloud Platform for AI（PAI）でワークスペースを作成、照会、一覧表示します。ワークスペースは、AI モデルのトレーニング、データ処理、および関連タスクのための分離された管理単位です。

アーキテクチャ：PAI AIWorkSpace（Workspace）

ワークスペースモード：

• シンプルモード：本番環境のみ（prod）
• 標準モード：開発環境（dev）＋本番環境（prod）

---

インストール

事前確認：Aliyun CLI >= 3.3.3 が必要です aliyun version を実行して、バージョンが 3.3.3 以上であることを確認してください。インストールされていない場合や、バージョンが低い場合は、 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash を実行してインストールまたは更新するか、 インストール手順については references/cli-installation-guide.md を参照してください。 続いて、自動プラグインインストールを有効にするため、[必須] aliyun configure set --auto-plugin-install true を実行してください。 さらに、ローカルマシン上の既存プラグインを常に最新の状態に保つため、[必須] aliyun plugin update を実行してください。

[必須] CLI User-Agent — aliyun CLI コマンドを実行する際は、毎回次を含める必要があります： --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage

aliyun version
aliyun configure set --auto-plugin-install true
aliyun plugin update

---

認証情報の確認

事前確認：Alibaba Cloud の認証情報が必要です

セキュリティルール：

• 絶対に AK/SK の値を読み取ったり、エコーしたり、表示したりしないでください（例：echo $ALIBABA_CLOUD_ACCESS_KEY_ID は禁止です）
• 絶対に会話やコマンドラインで AK/SK を直接入力するようユーザーに求めないでください
• 絶対にaliyun configure set をリテラルの認証情報値とともに使用しないでください
• 認証情報の状態を確認するには、必ずaliyun configure list のみを使用してください

機密データのマスキング：

• API レスポンス内の以下のフィールドには個人を特定できる情報が含まれるため、ユーザーに表示する前に必ずマスキングしてください：

  • Owner.UserId / Creator — 末尾 4 桁のみ表示します（例：****1234）
  • Owner.UserKp — 絶対に表示せず、完全に省略します
  • Owner.UserName / Owner.DisplayName — 先頭の 1 文字と *** のみ表示します（例：z***）
  • AdminNames 内のアカウント — u***@example.com 形式でマスキングします

• [MUST] 生の機密データを stdout、実行ログ、ディスク、会話に出してはなりません：実行フレームワークは、すべてのコマンドの stdout を実行ログ／トランスクリプト（例：ran-scripts/executed-actions.log）に記録します。そのため、get-workspace または list-workspaces のすべての実行（--verbose を指定しない基本クエリを含む）には、| jq -r によるパイプフィルタリングを含める必要があります。Creator は常に返され、機密情報であるためです。コマンド出力に生の API JSON が中間段階であっても現れる実行ステップを設けてはなりません。| jq -r のパイプは、単一のパイプラインコマンドの一部でなければなりません：

  基本クエリ（--verbose なし）：

  aliyun aiworkspace get-workspace --workspace-id <ID> --region <RegionId> \
    --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage \
    | jq -r '"Workspace: \(.WorkspaceName) (ID: \(.WorkspaceId))
  Status: \(.Status)
  Environment: \(.EnvTypes | join(", "))
  Created: \(.GmtCreateTime)
  Creator ID: \(.Creator // "" | if length > 0 then "****" + .[-4:] else "N/A" end)"'
  

  詳細クエリ（--verbose true を指定）：

  aliyun aiworkspace get-workspace --workspace-id <ID> --verbose true --region <RegionId> \
    --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage \
    | jq -r '"Workspace: \(.WorkspaceName) (ID: \(.WorkspaceId))
  Status: \(.Status)
  Owner: \(.Owner.UserName // "" | if length > 0 then .[0:1] + "***" else "N/A" end) (ID: \(.Owner.UserId // "" | if length > 0 then "****" + .[-4:] else "N/A" end))
  Creator ID: \(.Creator // "" | if length > 0 then "****" + .[-4:] else "N/A" end)
  Administrators: \(.AdminNames // [] | map(.[0:1] + "***") | join(", "))"'
  

  生の API レスポンスはパイプ内を通過し、シェルの stdout に出力されることはありません。実行フレームワークに記録されるのは、マスキング済みの値と自然言語のキーを含む jq の出力のみです。以下はすべて禁止です：

  • | jq によるパイプフィルタリングを行わずに CLI コマンドを実行すること（基本クエリであっても禁止です。Creator フィールドは常に返され、機密情報であるためです）
  • 2 段階処理 — まず CLI コマンドを実行して生の出力を取得し、その後、別途マスキングすること。マスキング前の生の JSON が実行トランスクリプトに記録されます。| jq -r は同じ単一のパイプラインコマンドに含める必要があります
  • 生の出力をシェル変数に取り込むこと — 例：response=$(aliyun ...) を実行してから echo "$response" | jq ... とすること。変数への代入により、生データが実行ログに記録されます
  • 出力リダイレクト（> file.json、>> file.log、| tee file）
  • ディスクに保存したシェルスクリプト経由でコマンドを実行すること（例：ran-scripts/*.sh）
  • 生の API レスポンスデータをスクリプトやコードファイルに埋め込むこと — 例：生の JSON 値を文字列リテラル、変数、データ構造として含む Python／シェルスクリプト（ran_scripts/process_workspace_data.py など）を作成すること。データ処理はすべて | jq -r のパイプ内で完結させてください。生データを含む中間処理スクリプトを作成しないでください
  • 会話内に生の JSON の断片を表示すること

• [MUST] 出力キーとして元の API フィールド名を使用してはなりません：値がマスキング済みであっても、会話やファイルの出力において、元の API フィールド名（UserId、UserName、UserKp、AdminNames など）を JSON キーや構造化出力のキー名として使用することは禁止です。代わりに自然言語のキー名を使用してください：

  • UserId / Creator → Owner ID または Creator ID
  • UserName → Username
  • DisplayName → Display Name
  • AdminNames → Administrators

  正しい方法：get-workspace または list-workspaces の実行はすべて、末尾に | jq -r を付けた単一のパイプラインコマンドにする必要があります。エージェントは、CLI コマンドを実行してから別のステップで出力を処理してはなりません。マスキング前の生の JSON が実行トランスクリプトに記録されてしまいます。データの抽出、マスキング、書式設定はすべて jq フィルター内で行ってください。ファイルに保存する場合は、CLI の出力ではなく jq の出力を、パイプラインの末尾に > file.md を指定してリダイレクトしてください。このルールは、基本クエリ、詳細クエリ、一覧表示を含むすべてのクエリに適用されます。

aliyun configure list

有効なプロファイル（AK、STS、または OAuth の ID）があることを出力で確認してください。

有効なプロファイルがない場合は、ここで停止してください。

1. Alibaba Cloud Console から認証情報を取得します
2. このセッションの外で認証情報を設定します（ターミナルで aliyun configure を実行するか、シェルプロファイルで環境変数を設定します）
3. aliyun configure list で有効なプロファイルが表示されたら、戻って再実行します

---

RAM 権限

必要な権限（ポリシー JSON および手順を含む）については、references/ram-policies.md を参照してください。

[MUST] 権限エラーへの対応： 実行中のいずれかの時点で、コマンドまたは API 呼び出しが権限エラーにより失敗した場合は、次の手順に従ってください。

1. references/ram-policies.md を読み、この SKILL に必要な権限の一覧をすべて確認します
2. ram-permission-diagnose スキルを使用して、必要な権限をユーザーがリクエストできるよう案内します
3. 必要な権限が付与されたことをユーザーが確認するまで、一時停止して待ちます

---

パラメーターの確認

重要：パラメーターの確認 — コマンドまたは API 呼び出しを実行する前に、 ユーザーがカスタマイズできるパラメーター（例：RegionId、WorkspaceName、Description、EnvTypes など）をすべてユーザーに確認する必要があります。明示的な承認なしに、値を仮定したりデフォルト値を使用したりしないでください。

パラメーター	必須／任意	説明	例
--region	必須	リージョン ID（グローバルパラメーター）。ユーザーが指定する必要があります。デフォルト値は使用しないでください	cn-hangzhou
--workspace-name	必須	ワークスペース名：3～23 文字、英字で始まり、英字、数字、アンダースコアを使用できます。リージョン内で一意である必要があります	myworkspace
--description	必須	ワークスペースの説明。最大 80 文字	My AI workspace
--env-types	必須	環境タイプ（リスト形式）：prod（シンプルモード）または dev prod（標準モード）	prod
--display-name	任意	表示名。デフォルトは WorkspaceName です	My Workspace
--resource-group-id	任意	リソースグループ ID。指定しない場合はデフォルトのリソースグループを使用します	rg-xxxxxxxx

注： --resource-group-id を設定すると、CLI／コードから変更できません。変更するには、コンソールを使用するか、ワークスペースを再作成してください。

---

タイムアウトの設定

API 呼び出しでは、タイムアウトを秒単位で設定できます。

オプション 1：コマンドラインパラメーター（現在のコマンドのみ適用）：

• --connect-timeout <seconds> — 接続タイムアウト
• --read-timeout <seconds> — I/O 読み取りタイムアウト

オプション 2：永続的な設定（グローバルに適用され、現在のプロファイルに書き込まれます）：

aliyun configure set --connect-timeout 10 --read-timeout 30

コマンドラインパラメーターは、永続的な設定より優先されます。設定されていない場合、CLI は組み込みのデフォルト値を使用します。timeout または context deadline exceeded エラーが発生した場合は、--read-timeout を増やしてください（例：30～60 秒）。

---

コアワークフロー

すべての CLI コマンドテンプレートとパラメーターの詳細については、references/related-commands.md を参照してください。

前提条件：リージョンの選択と PAI の有効化状況の確認

[MUST] デフォルトのリージョンを使用しない： エージェントはデフォルトのリージョンを仮定したり、使用したりしてはいけません。使用するリージョンをユーザーに明示的に確認する必要があります。

[MUST] リージョンを初めて使用する際に PAI の有効化を確認する： ユーザーがリージョンを指定した後（またはセッションで初めてリージョンを使用する際）、エージェントは後続のワークスペース操作を実行する前に list-products を呼び出し、そのリージョンで PAI が有効化されているか確認する必要があります。

ステップ 1：リージョンの確認

使用するリージョンをユーザーに確認します。ユーザーがリージョンを指定していない場合は、選択肢として一般的なリージョンの一覧を提示します（references/related-commands.md の「一般的なリージョン ID」表を参照）。デフォルトのリージョンを自動的に選択してはいけません。

ステップ 2：PAI の有効化状況の確認

aliyun aiworkspace list-products を使用して、ユーザーが指定したリージョンで PAI および依存する製品が有効化されているか確認します。

aliyun aiworkspace list-products \
  --region <UserSpecifiedRegionId> \
  --product-codes PAI_share \
  --verbose true \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-pai-workspace-manage

ステップ 3：チェック結果を処理する

返された Products 配列を確認し、一致する製品エントリを探します。

判断ロジック：

1. IsPurchased == true → PAI は有効化されています。以降のワークフローに進みます
2. IsPurchased == false → PAI は有効化されていません。ユーザーに有効化を案内します：
   • HasPermissionToPurchase フィールドを確認します：
     • true → ユーザーには権限があります。PurchaseUrl のリンクを表示し、続行する前にコンソールで有効化を完了するよう促します
     • false → ユーザーには権限がありません（プライマリアカウント、または pai:CreateOrder 権限を持つ RAM ユーザーが必要です）。プライマリアカウントの管理者に連絡するようユーザーに伝えます
   • PAI が有効化されていない場合は、ワークスペースの作成やクエリに進まないでください

ワークフロー 1：ワークスペースを作成する（CreateWorkspace）

aliyun aiworkspace create-workspace を使用してワークスペースを作成します。必須パラメーターは --region、--workspace-name、--description、--env-types です。シンプルモードでは --env-types prod、標準モードでは --env-types dev prod を使用します。必要に応じて --display-name と --resource-group-id を追加します。

ステップ 1：入力パラメーターの検証

[MUST] パラメーター形式の検証：API を呼び出す前に、エージェントは以下のとおりユーザーが指定したパラメーターを検証する必要があります。検証に失敗した場合は、入力を修正するようユーザーに促してください。要件に準拠しないパラメーターを送信しないでください。

パラメーター	検証ルール	例
--workspace-name	3～23 文字で、英字で始まる必要があります。英字、数字、アンダースコア（_）のみ使用できます。ハイフン（-）、スペース、中国語の文字、その他の特殊文字は使用できません	my_workspace_01
--description	最大 80 文字です。特殊文字を含む場合は引用符で囲みます	"My AI workspace"
--env-types	prod または dev prod である必要があります。リスト形式で指定します	prod
--display-name	省略可能で、形式に厳密な制限はありません	My Workspace

ステップ 2：名前の存在確認（チェックしてから実行する冪等性パターン）

[MUST] 冪等性の保証：CreateWorkspace API は ClientToken をサポートしていないため、チェックしてから実行するパターンで冪等性を確保します。作成する前に、名前がすでに存在するか確認するため、list-workspaces --option CheckWorkspaceExists --workspace-name <name> を必ず呼び出してください。

判断ロジック：

• TotalCount == 0 → 名前は使用可能です。ステップ 3 に進んで作成します
• TotalCount >= 1 → 名前はすでに存在します。以下を実行します：
  1. 返された Workspaces[0] から既存の WorkspaceId を取得します
  2. get-workspace --workspace-id <id> を呼び出して詳細情報を取得します
  3. 既存のワークスペースの主要パラメーター（EnvTypes、Description など）を、現在のリクエストパラメーターと比較します
  4. 一致する → 作成済みとして扱い、既存の WorkspaceId をそのまま返します。再作成はしないでください
  5. 一致しない → 名前はすでに異なる設定で使用されていることをユーザーに伝え、別の名前を選ぶよう依頼します

ステップ 3：作成を実行する

パラメーターの検証に合格し、名前が存在しない場合は、create-workspace コマンドを実行します。成功すると WorkspaceId が返されます。作成時に WorkspaceNameAlreadyExists エラーが返された場合（同時実行のケース）は、ステップ 2 の TotalCount >= 1 のロジックに従って処理します。

ワークフロー 2：ワークスペースの詳細を取得する（GetWorkspace）

[MUST] 単一ワークスペースのクエリには get-workspace を使用してください：特定のワークスペース 1 件 の詳細を照会する場合は、aliyun aiworkspace get-workspace --workspace-id <id> を 必ず 使用してください。代わりに list-workspaces --workspace-ids を使用して はいけません。get-workspace は GetWorkspace API を呼び出し、単一ワークスペースの完全な詳細を返します。

受け付けるのは --workspace-id（必須）と --verbose（任意）のみです。リージョンはグローバルパラメーター --region で指定します。Status が ENABLED の場合、ワークスペースは準備完了です。

[MUST] --verbose true のトリガー規則：--verbose true を指定すると、Owner（UserKp、UserId、UserName、DisplayName）と AdminNames（管理者アカウントの一覧）が返されます。エージェントは以下の規則に従う必要があります。

1. トリガー条件 — ユーザーのリクエストに以下のキーワードが含まれる場合、コマンドを組み立てる際に 必ず --verbose true を追加してください（API の呼び出し前に判定し、API の成功可否には依存しません）。
   • 中国語のキーワード：所有者、拥有者、创建者、管理员、负责人、归属
   • 英語のキーワード：owner、admin、administrator、verbose
   • フィールド名：Owner、AdminNames
2. トリガーされない場合 — ユーザーが基本情報（ステータス、環境タイプなど）のみを照会する場合、--verbose は追加しないでください
3. マスキング規則 — UserId/Creator：末尾 4 桁のみ（****1234）、UserKp：完全に省略、UserName/DisplayName：先頭の 1 文字のみ（z***）、AdminNames の各エントリー：u***@example.com
4. 標準出力、実行ログ、ディスク、または出力に機密データを生で含めないでください — get-workspace（--verbose の有無を問わず）または list-workspaces の すべての 実行は、末尾に | jq -r を付けた 単一のパイプラインコマンド にする必要があります。エージェントは、CLI コマンドを先に実行してから別途出力をマスキングして はいけません。生の JSON が実行トランスクリプトに表示されるためです。2 段階の処理、変数への格納（response=$(aliyun ...)）、中間スクリプトは禁止です。マスキングはすべて、同じパイプラインの jq フィルター内で行う必要があります。テンプレートについては、「機密データのマスキング」セクションと references/related-commands.md を参照してください

[MUST] 404 エラーの処理：get-workspace が StatusCode: 404, Code: 100400027, Message: Workspace not exists を返した場合、そのワークスペース ID は存在しません。エージェントは、ユーザーが指定した元の workspace-id を含め、ワークスペースが存在しないことを ユーザーに直接報告する必要があります。404 を受け取った後に、ワークスペースを「見つける」ために list-workspaces やその他の API にフォールバックしては いけません。エラーを黙って無視しても いけません。その後、ユーザーが新しい workspace-id を指定した場合、エージェントは最初の呼び出しと 同じパラメーター（--verbose true などを含む）で get-workspace を再試行する必要があります。

ワークフロー 3：ワークスペースの一覧表示（ListWorkspaces）

aliyun aiworkspace list-workspaces を使用してワークスペースを一覧表示します。次のフィルターおよびソート用パラメーターに対応しています。

• --workspace-name <name> — 名前であいまい検索
• --workspace-ids <id1,id2,...> — ID リストによる一括検索。カンマ区切りです（例：--workspace-ids "123,456,789"）
• --status <STATUS> — ステータスでフィルターします。列挙値はすべて大文字です：ENABLED | INITIALIZING | FAILURE | DISABLED | FROZEN | UPDATING
• --sort-by <Field> — ソートフィールド（大文字と小文字を区別）：GmtCreateTime（デフォルト）| GmtModifiedTime
• --order <ORDER> — ソート順（すべて大文字）：ASC（デフォルト）| DESC
• --page-number <n> / --page-size <n> — ページネーション用パラメーター
• --option GetResourceLimits — ワークスペース一覧の代わりにリソース上限情報を取得します
• --option CheckWorkspaceExists — 指定した名前のワークスペースがすでに存在するか確認します（作成前の確認です。--workspace-name と併用してください）

[MUST] API の選択ルール：単一の ID を照会する場合は get-workspace --workspace-id（GetWorkspace API）を使用します。複数の ID（2 つ以上）を 1 回の一括クエリで照会する場合は list-workspaces --workspace-ids "id1,id2,..."（ListWorkspaces API）を使用します。ID ごとに get-workspace を個別に呼び出さないでください。

[MUST] 一括クエリの結果が最終結果です：list-workspaces --workspace-ids が返す Workspaces 配列には、各ワークスペースの完全な情報（Status、EnvTypes、GmtCreateTime など）がすでに含まれています。追加情報を取得するために、一括クエリ結果に含まれるいずれかの ID について get-workspace を呼び出してはいけません。応答に含まれていない ID は存在しません。その旨をユーザーに直接伝えてください。

[MUST] 列挙値では大文字と小文字が区別されます：--sort-by には GmtCreateTime または GmtModifiedTime（キャメルケース）、--order には ASC または DESC（すべて大文字）、--status には ENABLED のようにすべて大文字の値を指定する必要があります。大文字と小文字を誤って指定すると（例：desc、gmtCreateTime、enabled）、API エラーや予期しない結果が発生します。

[MUST] ListWorkspaces の機密フィールドのマスキング：list-workspaces が返す各ワークスペースオブジェクトには、Creator（作成者のユーザー ID）と AdminNames（管理者アカウントのリスト）が常に含まれます。--verbose true は必要ありません。Agent は表示時にこれらのフィールドをマスキングする必要があります（Creator：末尾 4 桁のみ、AdminNames：先頭の文字 + ***）。生の値を含む JSON を出力したり、リダイレクト（> file）やスクリプトを使って生の応答をファイルに保存したりしないでください。

---

成功の確認

確認対象	方法	成功条件
WorkspaceId が返される	作成コマンドの応答を解析	WorkspaceId が空ではない
ワークスペースのステータスが正常	get-workspace コマンド	Status == "ENABLED"
コンソールに表示される	PAI Console にログインして手動で確認	新しいワークスペースが一覧に表示される

詳細な確認方法については references/verification-method.md を参照してください

---

クリーンアップ（ワークスペースの削除）

警告：ワークスペースの削除は、内部のすべてのリソースを削除する取り消し不能な操作です。慎重に進めてください。

注記：ワークスペースの削除は CLI から直接実行できません（aiworkspace プラグインは現在 delete-workspace に対応していません）。次の方法を使用してください。

1. コンソールから削除：PAI Console にログイン -> Workspace List -> ワークスペースを選択 -> Delete
2. API 呼び出し：DELETE /api/v1/workspaces/{WorkspaceId} エンドポイントを使用します（SDK または HTTP の直接呼び出し）

---

ベストプラクティス

1. 命名規則：WorkspaceName には、プロジェクト名やチーム識別子のプレフィックスを使用します。例：nlp_prod、cv_dev（ハイフンは使用できないため、アンダースコアを使用してください）
2. 環境の選択：開発リソースと本番リソースを分離するため、本番プロジェクトでは標準モード（dev + prod）を使用します
3. 説明：管理しやすいように、説明には目的、チーム、またはプロジェクトを記載します
4. リージョンの選択：データ転送の遅延を最小限に抑えるため、データストレージに最も近いリージョンを選択します
5. リソースグループの管理：複数のプロジェクトがある場合は、コスト配分と権限管理を容易にするため、異なるリソースグループを使用します
6. DisplayName：WorkspaceName には英語の識別子を使用し、表示名にはビジネスで分かりやすい名前を使用します

---

リファレンスドキュメント

ドキュメント	説明
references/ram-policies.md	RAM 権限ポリシー、Policy JSON、および手順
references/related-commands.md	CLI コマンドテンプレート、パラメータ表、列挙値、戻り値フィールドの一覧
references/verification-method.md	検証手順とスクリプト
references/acceptance-criteria.md	CLI コマンドの受け入れ基準（正しいパターン／誤ったパターン）
references/cli-installation-guide.md	Aliyun CLI のインストールと設定
ListWorkspaces API Doc	ListWorkspaces API リファレンス
CreateWorkspace API Doc	CreateWorkspace API リファレンス
GetWorkspace API Doc	GetWorkspace API リファレンス
ListProducts API Doc	ListProducts API リファレンス（製品の有効化状態の確認）