alibabacloud-odps-project-manage

MaxCompute プロジェクト管理

Alibaba Cloud MaxCompute（ODPS）プロジェクトの作成、クエリ、一覧表示などの操作を管理します。

前提条件

事前確認：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 plugin update を実行してください。

[必須] CLI の User-Agent — aliyun CLI コマンドを実行する際は、必ず次の値を含めてください。 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage

[必須] AI モードのコマンド — aliyun CLI を使用する際は、AI モードのライフサイクルを宣言してください。

1. コマンドの実行前に AI モードを有効にする：

   aliyun configure ai-mode enable
   

2. AI モード用の User-Agent を設定する：

   aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage"
   

3. ワークフローの終了後に AI モードを無効にする：

   aliyun configure ai-mode disable
   

クイックスタート

ユーザーから MaxCompute プロジェクトについて質問された場合は、次の手順に従ってください。

1. 意図を確認する：作成／一覧表示／取得
2. RegionId を確認する：ユーザーにリージョン（例：cn-hangzhou、cn-shanghai）を尋ねます
3. 実行する：適切なコマンドを --region {REGION_ID} および --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage とともに実行します
4. 確認する：結果を確認してユーザーに報告します

実行前チェックリスト（コマンドを実行する前に毎回確認）

コマンドを実行する前に、以下のすべてを必ず確認してください。

• デフォルトを使わず、ユーザーに RegionId を尋ねた
• ユーザーから実際の RegionId の値を取得した（プレースホルダーではない）
• コマンドに --region {ACTUAL_REGION_ID} が含まれている
• コマンドに --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage が含まれている
• AK/SK の値を読み取ったり、表示したりしていない
• ユーザー指定のパラメーターにハードコードされた値を使用していない

いずれかの項目を満たさない場合は、いったん停止し、修正してから続行してください。

タスク完了チェックリスト

重要：すべての手順を順番に完了する必要があります。途中で終了しないでください。

プロジェクトの一覧表示の場合：

1. ユーザーに尋ねます：「どのリージョンを照会しますか？（例：cn-hangzhou、cn-shanghai）」
2. ユーザーに尋ねます：「フィルターに使用するクォータのニックネームは何ですか？（例：os_PayAsYouGoQuota。デフォルトを使用する場合は Enter キーを押してください）」
3. クォータのニックネームのパラメーターを必ず使用します：
   • ユーザーがクォータを指定した場合：--quota-nick-name={USER_QUOTA} を使用します
   • ユーザーが指定しなかった場合：--quota-nick-name=os_PayAsYouGo を使用します
4. 必須パラメーターを指定して実行します：

   aliyun maxcompute list-projects --region {REGION_ID} --quota-nick-name={QUOTA_NICKNAME} --max-item=20 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage
   

5. コマンドの出力を待ちます
6. 400 エラー（クォータが見つからない）が発生した場合：
   • aliyun maxcompute list-quotas --billing-type ALL --region {REGION_ID} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage を呼び出します
   • 利用可能なクォータを提示し、ユーザーに選択してもらいます
   • ユーザーが選択したクォータを指定して list-projects を再実行します
7. 応答を解析して結果を提示します
8. タスクの完了を確認します

禁止事項：

• ❌ ページネーションに --marker を使用する
• ❌ すべてのプロジェクトを取得してから Python/jq でローカルフィルターをかける
• ❌ --quota-nick-name パラメーターなしで API を呼び出す

必須事項：

• ✅ ユーザー指定のクォータ、またはデフォルトのクォータを使って、必ず --quota-nick-name を使用する
• ✅ 必ず --max-item=20 を使用する
• ✅ サーバー側のフィルタリングを API に任せる

プロジェクトの取得の場合：

1. ユーザーに尋ねます：「どのリージョンですか？（例：cn-hangzhou）」
2. ユーザーに尋ねます：「プロジェクト名は何ですか？」
3. 実行します：aliyun maxcompute get-project --region {REGION_ID} --project-name {PROJECT_NAME} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage
4. コマンドの出力を待ちます
5. JSON 応答を解析し、data.name、data.status、data.owner を確認します
6. プロジェクトの詳細をわかりやすい形式でユーザーに提示します
7. タスクの完了をユーザーに確認します

プロジェクトを作成する場合：

1. ユーザーに尋ねます：「どのリージョンに作成しますか？（例：cn-hangzhou）」
2. ユーザーに尋ねます：「プロジェクト名は何ですか？」
3. 必須の検証： プロジェクト名が空、または空白文字のみの場合は処理を停止し、ユーザーにもう一度尋ねます：「プロジェクト名は空にできません。有効なプロジェクト名を指定してください。」
4. 重要： ユーザーが指定したプロジェクト名をそのまま保存します。プレースホルダーテキストは使用しないでください
5. 必ず list-quotas を呼び出します： 次を実行します：aliyun maxcompute list-quotas --billing-type ALL --region {REGION_ID} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage
6. コマンドの出力を待ちます
7. list-quotas の応答を解析します： nickName とそのセカンダリークォータを持つクォータを探します（data.quotas[].subQuotas などを確認します）
8. 厳密な検証： list-quotas の応答にあるセカンダリークォータの nickNameを選択します（プライマリークォータは選択しないでください）
9. 空白文字を削除： クォータの nickName の先頭と末尾にある空白を削除します。nickName に内部の空白が含まれている場合は、それを削除するか、別のクォータを選択します
10. 実行前の確認： REGION_ID、PROJECT_NAME、SECONDARY_QUOTA_NICKNAME（前後の空白を削除済みで、空白なし）の実際の値があることを確認します
11. typeSystem を確認（任意）： 「どの typeSystem を使用しますか？（1=MaxCompute、2=MaxCompute2、hive=Hive 互換。デフォルト：2）」
12. typeSystem を検証： 「1」、「2」、「hive」のいずれかである必要があります。未指定または無効な場合は、デフォルトの「2」を使用します
13. 実際の値を指定して作成コマンドを実行します：

    aliyun maxcompute create-project --region {ACTUAL_REGION} --body '{"name":"ACTUAL_PROJECT_NAME","defaultQuota":"SECONDARY_QUOTA_NICKNAME","productType":"payasyougo","typeSystem":"TYPE_SYSTEM_VALUE"}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage
    

    実際の値を使った例：

    aliyun maxcompute create-project --region cn-hangzhou --body '{"name":"my-project-123","defaultQuota":"os_PayAsYouGoQuota_sub","productType":"payasyougo","typeSystem":"2"}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage
    

14. コマンドの出力を待ちます
15. 作成応答を確認： 作成コマンドがエラー（2xx 以外）を返した場合は、処理を停止してエラーをユーザーに報告します。検証には進まないでください
16. 作成が成功した場合のみ： 次を実行して検証します：aliyun maxcompute get-project --region {REGION_ID} --project-name {PROJECT_NAME} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage
17. 重要： 応答に正しいプロジェクト名（別のプロジェクトではなく、ユーザーが指定したプロジェクト名）が含まれていることを確認します
18. ステータスを確認： 応答に "status":"AVAILABLE" が含まれていることを確認します
19. 検証で 403／アクセス拒否が返された場合： 必要な権限をユーザーに伝え、処理を停止します
20. プロジェクトが見つからない場合： 「プロジェクトの作成に失敗しました。作成後にプロジェクトが見つかりませんでした」と報告します
21. 別のプロジェクトが返された場合： エラーを報告します。代わりに別のプロジェクトを使用しないでください
22. すべての確認に合格した場合のみ： ユーザーに次のように伝えます：「プロジェクト {PROJECT_NAME} がステータス AVAILABLE で正常に作成されました」

ユーザーが削除を依頼した場合：

次のように応答します：「このスキルではプロジェクトの削除はサポートされていません。Alibaba Cloud Console を使用するか、管理者にお問い合わせください。」

よくあるエラーと解決方法

エラー	原因	解決方法
ProjectNotFound	プロジェクトが存在しません	プロジェクト名のスペルとリージョンを確認してください
ProjectAlreadyExist	名前がすでに使用されています	別のプロジェクト名をユーザーに尋ねてください
get project default quota error	有効なクォータがありません	まず list-quotas を実行し、クォータが存在することを確認してください
InvalidProjectName	命名形式が正しくありません	小文字、数字、アンダースコアのみを使用してください（3～28 文字）
NoPermission または 403 Access Denied	RAM 権限の問題です	ユーザーに次のように伝えてください：「list-quotas、create-project、get-project の実行には odps 権限が必要です。管理者にお問い合わせください。」
RegionId required	--region が指定されていません	コマンドには必ず --region {REGION_ID} を追加してください
ODPS-0420095: Access Denied	読み取り権限がありません	必要な権限についてユーザーに伝え、処理を中止してください

禁止されている操作

重大：以下の操作は絶対に行わないでください。

1. 絶対に AK/SK の値を読み取ったり、表示したりしないでください（例：echo $ALIBABA_CLOUD_ACCESS_KEY_ID）
2. 絶対にハードコードされた値を使用しないでください。必ずパラメーターをユーザーに尋ね、プレースホルダーテキストではなく、ユーザーが実際に回答した値を使用してください
3. 絶対にリテラルの認証情報を指定して aliyun configure set を使用しないでください
4. 絶対に aliyun ram コマンドを実行しないでください
5. 絶対に --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage を指定せずにコマンドを実行しないでください
6. 絶対に RegionId を尋ねる手順を省略しないでください。これは常に必須です
7. 絶対にデフォルトのリージョンを想定しないでください。必ずユーザーに尋ねてください
8. 絶対に大文字の API アクション形式を CLI コマンドとして使用しないでください。必ず小文字とハイフンを使ったプラグイン形式を使用してください（例：create-project）
9. 絶対に aliyun maxcompute delete-project を実行しないでください。このスキルではプロジェクトの削除はサポートされていません

悪い例

❌ 間違い	✅ 正しい
大文字の API アクション名を CLI コマンドとして使用する	aliyun maxcompute create-project（小文字とハイフンを使ったプラグイン形式）
'{"name":"{PROJECT_NAME}"}'（プレースホルダー）	'{"name":"actual-name"}'（実際の値）
--region cn-hangzhou（ハードコード）	先にユーザーに尋ね、その回答を使用する
--user-agent がない	--user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage を必ず含める
echo $ALIBABA_CLOUD_ACCESS_KEY_ID	認証情報を読み取ったり表示したりしない
aliyun ram ... コマンド	RAM コマンドは対象範囲外です
aliyun maxcompute delete-project	プロジェクトの削除はサポートされていません
失敗時に別のプロジェクトを確認する	失敗を報告し、別のプロジェクトに置き換えない

アーキテクチャ

MaxCompute Service
    └── Project (Workspace)
          ├── defaultQuota (Compute Resource - MUST exist before project creation)
          ├── productType (payasyougo/subscription)
          └── typeSystem ("1", "2", or "hive"; default: "2")

依存関係

前提条件：プロジェクトを作成する前に、クォータが存在している必要があります。

すべての MaxCompute プロジェクトには、コンピューティングクォータ（defaultQuota）が必要です。クォータはアカウントにすでに存在している必要があります。存在しない場合、create-project 呼び出しは get project default quota error で失敗します。

クォータの作成または照会には、alibabacloud-odps-quota-manage スキルを使用してください。

• 従量課金：aliyun maxcompute create-quota --charge-type payasyougo --commodity-code odps --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage
• サブスクリプション：すべてのパラメーター（partNickName、CU、ord_time など）については、alibabacloud-odps-quota-manage スキルを参照してください
• 既存のクォータの一覧表示：aliyun maxcompute list-quotas --billing-type ALL --region <region> --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage

クォータを作成するか、存在することを確認した後、プロジェクト作成時にその nickName を defaultQuota パラメーターとして使用してください。

インストール

事前確認：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 CLI プラグインの更新が必要です

[必須] aliyun configure set --auto-plugin-install true を実行し、プラグインの自動インストールを有効にしてください。 [必須] aliyun plugin update を実行し、既存のプラグインが常に最新であることを確認してください。

# Install/Update Alibaba Cloud CLI
curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash

# Verify version (must be >= 3.3.3)
aliyun version

# Enable auto plugin installation
aliyun configure set --auto-plugin-install true

# Update plugins
aliyun plugin update

環境変数

標準的な Alibaba Cloud 認証情報以外に、追加の環境変数は必要ありません。

認証

重要：いかなる操作の前にも、必ず認証情報を確認してください。

許可されている認証情報の確認（このコマンドのみ）：

aliyun configure list

確認する項目：

• 出力に mode: AK または mode: StsToken のプロファイルが少なくとも 1 つ表示されている
• プロファイルに access_key_id: ******** が表示されている（マスキングされていても問題ありません）

有効なプロファイルがない場合：

• ユーザーに「先に aliyun configure を実行して認証情報を設定してください。」と伝えます。
• 停止 — MaxCompute コマンドを実行してはいけません

禁止事項 — 絶対に実行しないでください：

• ❌ echo $ALIBABA_CLOUD_ACCESS_KEY_ID
• ❌ echo $ALIBABA_CLOUD_ACCESS_KEY_SECRET
• ❌ aliyun configure get | grep access-key
• ❌ 実際の認証情報の値を表示するコマンド

RAM ポリシー

[必須] RAM 権限の事前確認： ワークフローを実行する前に、現在のユーザーが必要な権限を持っていることを確認してください。

必要な権限は references/ram-policies.md に記載されています。

注： CLI コマンドで RAM 権限を確認する必要はありません。ram-policies.md に記載されている権限は、ユーザー向けの参考情報です。ユーザーが適切な権限を設定済みであることを前提に、ワークフローを進めてください。

パラメーター

以下の値は必ずユーザーに確認してください。デフォルト値を仮定してはいけません：

パラメーター	必須	説明
RegionId	はい	リージョン ID（cn-hangzhou、cn-shanghai など）
projectName	はい	プロジェクト名
quotaNickName	作成時	クォータのエイリアス（list-quotas から取得）

会話例

一覧表示： ユーザーが依頼 → エージェントが RegionId を確認 → エージェントが list-projects を実行 → エージェントが結果を提示

作成： ユーザーが依頼 → エージェントが RegionId を確認 → エージェントが projectName を確認 → エージェントが list-quotas を呼び出す → エージェントがプロジェクトを作成 → エージェントが確認 → エージェントが成功を報告

コマンド

プロジェクトの一覧表示

# Ask user for quota nickname first, then:
aliyun maxcompute list-projects --region {REGION_ID} --quota-nick-name={QUOTA_NICKNAME} --max-item=20 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage

必須： 常に --quota-nick-name パラメーターを使用してください（ユーザー指定またはデフォルト）。すべてを取得してローカルで絞り込んではいけません。

プロジェクトの取得

aliyun maxcompute get-project --region {REGION_ID} --project-name {PROJECT_NAME} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage

プロジェクトの作成

1. まずクォータを一覧表示します：

aliyun maxcompute list-quotas --billing-type ALL --region {REGION_ID} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage

2. 応答から取得したクォータの nickName を指定して作成します：

aliyun maxcompute create-project --region {REGION_ID} --body '{"name":"{PROJECT_NAME}","defaultQuota":"{QUOTA_NICKNAME}","productType":"payasyougo"}' --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage

成功確認の方法

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

確認コマンド：

aliyun maxcompute get-project --region {REGION_ID} --project-name {PROJECT_NAME} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage

成功条件：

• 応答に "status":"AVAILABLE" が含まれている
• 応答に、作成したプロジェクトと一致する正しい "name" が含まれている
• 応答に、指定したクォータと一致する正しい "defaultQuota" が含まれている

確認に失敗した場合：

1. エラーメッセージで具体的な問題を確認します
2. 失敗の理由をユーザーに報告します
3. エラーの種類に応じた是正措置を提案します

制限事項

以下の操作は CLI/API では実行できず、コンソールへのアクセスが必要です：

操作	理由	代替手段
請求明細の表示	コンソールへのアクセスが必要	Billing Console を使用
IAM ポリシーの視覚的な管理	コンソール限定の機能	ポリシー管理には RAM CLI を使用
リソースのリアルタイム監視	コンソールのダッシュボードが必要	CloudMonitor API を使用

API とコマンドの一覧

完全な API リファレンスについては、references/related-apis.md を参照してください。

操作	CLI コマンド（プラグインモード）	API アクション名
プロジェクトの作成	aliyun maxcompute create-project	create-project
プロジェクトの取得	aliyun maxcompute get-project	get-project
プロジェクトの一覧表示	aliyun maxcompute list-projects	list-projects
クォータの一覧表示	aliyun maxcompute list-quotas	list-quotas

スキルの完了条件（skill_pass で必須）

skill_pass_rate を成功させるには、以下のすべてを満たす必要があります。

共通要件（すべての操作）：

1. ✅ ユーザーに RegionId を尋ね、回答を得ている
2. ✅ すべてのコマンドで --region {USER_PROVIDED_VALUE} を使用している（ハードコードしていない）
3. ✅ すべてのコマンドに --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage が含まれている
4. ✅ 禁止された操作を行っていない（認証情報の表示、ram コマンドの使用など）
5. ✅ タスクの結果をユーザーにはっきりと報告している

操作ごとの要件：

LIST：

• 実行したコマンド：aliyun maxcompute list-projects --region {REGION} --quota-nick-name=os_PayAsYouGo --max-item=20 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage
• 初回の試行では --quota-nick-name=os_PayAsYouGo パラメーターを必ず含める
• --max-item=20 パラメーターを必ず含める
• 初回の試行が 400 エラーで失敗した場合は、--quota-nick-name=os_PayAsYouGoQuota を指定して再試行する
• 結果をユーザーに提示する（プロジェクトの一覧、または「プロジェクトが見つかりませんでした」）

GET：

• 実行したコマンド：aliyun maxcompute get-project --region {REGION} --project-name {NAME} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage
• プロジェクトの詳細をユーザーに提示する

CREATE：

• ユーザーに RegionId と projectName を尋ね、実際の値を取得している

• 最初にクォータの一覧を取得する：aliyun maxcompute list-quotas --billing-type ALL --region {REGION} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage

• リクエストボディには実際の値を使用する。{PROJECT_NAME} のようなプレースホルダーは使用しない

• 作成コマンドの形式：--body '{"name":"ACTUAL_NAME","defaultQuota":"ACTUAL_QUOTA","productType":"payasyougo"}'

• 続行する前に、作成レスポンスにエラーがないか必ず確認する

• 検証コマンドを実行する：aliyun maxcompute get-project --region {REGION} --project-name {NAME} --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage

• レスポンス内のプロジェクト名が、要求されたプロジェクト名と一致することを必ず確認する

• ステータスが AVAILABLE であることを必ず確認する

• 権限エラー（403）により検証に失敗した場合は、ユーザーに伝えて終了する

• プロジェクトが見つからない場合、または異なるプロジェクトが返された場合は、失敗を報告する

• 検証に成功した場合（status=AVAILABLE）、ユーザーに成功を伝える

• ユーザーが削除を要求した場合は、Alibaba Cloud Console を利用するよう案内する

スキルの最終確認：

Before responding to user, verify:
□ I followed the correct workflow for the operation type
□ I asked for ALL required parameters from user
□ I used user's actual values in commands (not placeholders or defaults)
□ I included --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage in EVERY command
□ I did NOT perform any forbidden actions
□ I reported the final result to user

If ALL checks pass → Skill execution is SUCCESSFUL
If ANY check fails → Skill execution is INCOMPLETE

最終確認（タスク完了とする前に）

タスクが完了したことをユーザーに伝える前に、以下のすべてを必ず確認してください。

LIST の場合：

• RegionId を尋ね、ユーザーから回答を得た
• --region {USER_ANSWER} と --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage を指定して list-projects を実行した
• 結果をユーザーにはっきりと提示した

GET の場合：

• RegionId を尋ね、ユーザーから回答を得た
• projectName を尋ね、ユーザーから回答を得た
• ユーザーの値と --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage を指定して get-project を実行した
• プロジェクトの詳細をユーザーにはっきりと提示した

CREATE の場合：

• RegionId を尋ね、ユーザーから回答を得た
• projectName を尋ね、ユーザーから回答を得た
• 有効なクォータを取得するために list-quotas を実行した
• ユーザーの値と --user-agent AlibabaCloud-Agent-Skills/alibabacloud-odps-project-manage を指定して create-project を実行した
• get-project を呼び出して作成を検証した
• ユーザーに成功を伝えた

DELETE の場合：

• 削除はサポートされていないことをユーザーに伝え、代わりに Alibaba Cloud Console を利用するよう提案します

いずれかの確認に失敗した場合、タスクは完了していません。

ベストプラクティス

1. 命名規則：プロジェクト名には小文字、数字、アンダースコアを使用します
2. クォータの選択：ワークロードの要件に応じて適切なクォータを選択します
3. 製品タイプ：開発／テストには payasyougo、予測可能なワークロードの本番環境には subscription を使用します
4. 型システム：Hive との互換性が必要な場合を除き、新しいプロジェクトには 2（MaxCompute）を使用します
5. リソースのクリーンアップ：不要なコストを避けるため、テストプロジェクトは必ずクリーンアップします

参考リンク

ドキュメント	説明
references/related-apis.md	API リファレンス一式
references/ram-policies.md	必要な RAM 権限
references/verification-method.md	検証手順
references/cli-installation-guide.md	CLI のインストールガイド
MaxCompute Product Page	公式製品ドキュメント
create-project API	API リファレンス
get-project API	API リファレンス
list-projects API	API リファレンス