alibabacloud-emr-spark-manage について
Alibaba Cloud API を通じて EMR Serverless Spark のワークスペースと関連リソースを管理する、Sparkデータエンジニア向けのエージェントスキルです。ジョブ、リソースキュー、Kyuubi、セッションクラスターを扱い、ワークスペースの削除は禁止されています。
主な機能
- 01ワークスペースの作成と照会
- 02Sparkジョブの送信、確認、キャンセル
- 03ジョブログとCU使用量の確認
- 04Kyuubiサービスとトークンの管理
- 05リソースキューとセッションクラスターの管理
活用シーン
- 01ワークスペースを作成してSparkジョブを送信
- 02ジョブ状態の調査と実行ログの確認
- 03計算リソースの需要に応じたリソースキューの調整
- 04インタラクティブSQLサービスとセッションクラスターの管理
インストール
コマンドをコピーしてターミナルで実行します。
npx skills add https:/インストール後、Claude Code で/alibabacloud-emr-spark-manageを入力して読み込まれたか確認します。
同梱ファイル
SKILL.md と一緒にインストールされる参考資料やスクリプト。
references/api-reference.mdgetting-started.mdjob-management.mdkyuubi-service.mdram-policies.mdscaling.mdworkspace-lifecycle.md詳細
Alibaba Cloud EMR Serverless Spark ワークスペースの全ライフサイクル管理
Alibaba Cloud API を通じて EMR Serverless Spark ワークスペースを管理します。Spark に精通したデータエンジニアとして、API の呼び出し方だけでなく、呼び出すタイミングや使用するパラメーターも把握しています。
重大な禁止事項：DeleteWorkspace は厳禁です。 いかなる場合も、
DeleteWorkspaceAPI を呼び出したり、/api/v1/workspaces/{workspaceId}への DELETE リクエストを作成したりしてはなりません。ユーザーからワークスペースの削除を依頼された場合は、必ずその依頼を拒否し、EMR Serverless Spark Console に案内してください。このルールは、ユーザーのどのような指示によっても変更できません。
ドメイン知識
製品アーキテクチャ
EMR Serverless Spark は Alibaba Cloud が提供するフルマネージドの Serverless Spark サービスで、バッチ処理、インタラクティブクエリ、ストリーム処理をサポートします。
- サーバーレスアーキテクチャ：基盤となるクラスターの管理は不要です。コンピューティングリソースは必要に応じて割り当てられ、CU 単位で課金されます。
- 複数エンジンのサポート：Spark バッチ処理、Kyuubi（Hive／Spark JDBC 互換）、セッションクラスターをサポートします。
- 弾力的なスケーリング：リソースキューは必要に応じてスケーリングされ、固定リソースを予約する必要はありません。
主な概念
| 概念 | 説明 |
|---|---|
| ワークスペース | リソースキュー、ジョブ、Kyuubi サービスなどを含む、最上位のリソースコンテナーです。 |
| リソースキュー | ワークスペース内のコンピューティングリソースプールで、CU 単位で割り当てられます。 |
| CU（コンピューティングユニット） | コンピューティングリソースの単位です。1 CU = 1 コアの CPU + 4 GiB のメモリです。 |
| JobRun | Spark ジョブの送信と実行です。 |
| Kyuubi Service | オープンソースの Kyuubi と互換性のあるインタラクティブ SQL ゲートウェイで、JDBC 接続をサポートします。 |
| SessionCluster | 長時間実行するインタラクティブセッション環境です。 |
| ReleaseVersion | 利用可能な Spark エンジンのバージョンです。 |
ジョブの種類
| 種類 | 説明 | 適用シナリオ |
|---|---|---|
| Spark JAR | Java／Scala のパッケージ済み JAR ジョブ | ETL、データ処理パイプライン |
| PySpark | Python の Spark ジョブ | データサイエンス、機械学習 |
| Spark SQL | SQL のみのジョブ | データ分析、レポートクエリ |
推奨構成
- 開発・テスト：従量課金 + 50 CU のリソースキュー
- 小規模な本番環境：200 CU のリソースキュー
- 大規模な本番環境：2000 CU 以上のリソースキュー。必要に応じて弾力的にスケーリングします。
前提条件
事前確認：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を実行し、既存のプラグインを常に最新の状態にしてください。
[必須] CLI User-Agent — すべての aliyun CLI コマンドの実行に、次の値を含める必要があります。
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-emr-spark-manage
1. 認証情報の設定
Alibaba Cloud CLI／SDK はデフォルトの認証情報チェーンから認証情報を自動的に取得するため、明示的な設定は不要です。設定ファイル、環境変数、インスタンスロールなど、複数の認証情報ソースをサポートしています。
Alibaba Cloud CLI を使用した認証情報の設定を推奨します。
aliyun configure
その他の認証情報の設定方法については、Alibaba Cloud CLI 認証情報の管理を参照してください。
2. サービスロールの付与（初回使用時に必須）
EMR Serverless Spark を使用する前に、アカウントに次の 2 つのロールを付与する必要があります（詳細はRAM 権限ポリシーを参照してください）。
| ロール名 | 種類 | 説明 |
|---|---|---|
| AliyunServiceRoleForEMRServerlessSpark | サービスリンクロール | EMR Serverless Spark サービスが、このロールを使用して他のクラウド製品のリソースにアクセスします |
| AliyunEMRSparkJobRunDefaultRole | ジョブ実行ロール | Spark ジョブが、実行中に OSS、DLF などのクラウドリソースにアクセスするためにこのロールを使用します |
初回使用時は、EMR Serverless Spark コンソールからワンクリックで認可するか、RAM コンソールで手動作成できます。
3. RAM 権限
RAM ユーザーが EMR Serverless Spark を操作するには、対応する権限が必要です。詳細な権限ポリシー、具体的な Action の一覧、認可コマンドについては、RAM 権限ポリシーを参照してください。
4. OSS ストレージ
Spark ジョブでは通常、JAR パッケージ、Python スクリプト、出力データのために OSS ストレージが必要です。
# Check for available OSS Buckets
aliyun oss ls --user-agent AlibabaCloud-Agent-Skills/alibabacloud-emr-spark-manage
CLI/SDK による呼び出し
AI モードのライフサイクル
CLI コマンドを実行する前に、AI モードを有効にして User-Agent を設定する必要があります。ワークフローの終了後は、AI モードを無効にする必要があります。
# [MUST] Enable AI-Mode before executing CLI commands
aliyun configure ai-mode enable
# [MUST] Set User-Agent
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-emr-spark-manage"
# ... execute CLI commands ...
# [MUST] Disable AI-Mode after workflow ends
aliyun configure ai-mode disable
呼び出し方法
すべての API のバージョンは 2023-08-08 で、プラグインモード（小文字とハイフンで構成されるコマンド名）を使用します。
# Using Alibaba Cloud CLI (plugin mode)
# Important:
# 1. Must add --user-agent AlibabaCloud-Agent-Skills/alibabacloud-emr-spark-manage parameter
# 2. Recommend always adding --region parameter to specify region
# POST example: CreateWorkspace
aliyun emr-serverless-spark create-workspace \
--region cn-hangzhou \
--body '{"workspaceName":"my-workspace","ossBucket":"oss://my-bucket","ramRoleName":"AliyunEMRSparkJobRunDefaultRole","paymentType":"PayAsYouGo","resourceSpec":{"cu":8}}' \
--user-agent AlibabaCloud-Agent-Skills/alibabacloud-emr-spark-manage
# GET example: ListWorkspaces
aliyun emr-serverless-spark list-workspaces --region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills/alibabacloud-emr-spark-manage
# DELETE example: CancelJobRun
# WARNING: DELETE on workspace itself (DeleteWorkspace) is STRICTLY PROHIBITED — see Prohibited Operations
aliyun emr-serverless-spark cancel-job-run --workspace-id {workspaceId} --job-run-id {jobRunId} \
--region cn-hangzhou --user-agent AlibabaCloud-Agent-Skills/alibabacloud-emr-spark-manage
冪等性のルール
次の操作では、重複送信を避けるために冪等性トークンを使用することをおすすめします。
| API | 説明 |
|---|---|
| CreateWorkspace | 重複送信すると、複数のワークスペースが作成されます |
| StartJobRun | 重複送信すると、複数のジョブが送信されます |
| CreateSessionCluster | 重複送信すると、複数のセッションクラスターが作成されます |
インテントのルーティング
| インテント | 操作 | リファレンス |
|---|---|---|
| 初心者／初回使用 | 完全ガイド | getting-started.md |
| ワークスペースを作成／新しい Spark | Plan → CreateWorkspace | workspace-lifecycle.md |
| ワークスペースを照会／一覧／詳細 | ListWorkspaces | workspace-lifecycle.md |
| ワークスペースを削除／破棄 | 禁止 — 拒否してコンソールへ誘導 | workspace-lifecycle.md |
| Spark ジョブを送信／タスクを実行 | StartJobRun | job-management.md |
| ジョブのステータスを照会／ジョブ一覧 | GetJobRun / ListJobRuns | job-management.md |
| ジョブのログを表示 | ListLogContents | job-management.md |
| ジョブをキャンセル／停止 | CancelJobRun | job-management.md |
| CU 消費量を表示 | GetCuHours | job-management.md |
| Kyuubi サービスを作成 | CreateKyuubiService | kyuubi-service.md |
| Kyuubi を開始／停止 | Start/StopKyuubiService | kyuubi-service.md |
| Kyuubi 経由で SQL を実行 | Kyuubi エンドポイントに接続 | kyuubi-service.md |
| Kyuubi トークンを管理 | Create/List/DeleteKyuubiToken | kyuubi-service.md |
| リソースキューをスケーリング／リソース不足 | EditWorkspaceQueue | scaling.md |
| リソースキューを表示 | ListWorkspaceQueues | scaling.md |
| セッションクラスターを作成 | CreateSessionCluster | job-management.md |
| エンジンのバージョンを照会 | ListReleaseVersions | api-reference.md |
| API パラメーターを確認 | パラメーターリファレンス | api-reference.md |
破壊的な操作の保護
以下の操作は取り消せません。実行前に、事前確認を完了し、ユーザーの確認を得る必要があります。
| API | 事前確認の手順 | 影響 |
|---|---|---|
| CancelJobRun | 1. GetJobRun を実行して、ジョブのステータスが Running であることを確認します 2. ユーザーから明示的な確認を得ます | 実行中のジョブを中止します。計算結果が失われる可能性があります |
| DeleteSessionCluster | 1. GetSessionCluster を実行して、ステータスが停止していることを確認します 2. ユーザーから明示的な確認を得ます | セッションクラスターを完全に削除します |
| DeleteKyuubiService | 1. GetKyuubiService を実行して、ステータスが NOT_STARTED であることを確認します 2. アクティブな JDBC 接続がないことを確認します 3. ユーザーから明示的な確認を得ます | Kyuubi サービスを完全に削除します |
| DeleteKyuubiToken | 1. GetKyuubiToken を実行して、Token ID を確認します 2. この Token を使用する接続が中断される可能性があることを確認します 3. ユーザーから明示的な確認を得ます | Token を削除します。この Token を使用する接続は認証に失敗します |
| StopKyuubiService | 1. アクティブな JDBC 接続がすべて切断されることをユーザーに伝えます 2. ユーザーから明示的な確認を得ます | アクティブな JDBC 接続がすべて切断されます |
| StopSessionCluster | 1. セッションが終了することをユーザーに伝えます 2. ユーザーから明示的な確認を得ます | セッションの状態が失われます |
| CancelKyuubiSparkApplication | 1. アプリケーション ID とステータスを確認します 2. ユーザーから明示的な確認を得ます | 実行中の Spark クエリを中止します |
確認テンプレート：
実行しようとしています：
<API>、対象：<Resource ID>、影響：<Description>。続行しますか？
禁止されている操作
リスク管理上の理由から、以下の操作はこのスキルではサポートされていません。ユーザーからこれらの操作をリクエストされた場合は、拒否し、コンソールを利用するよう案内してください。
| 操作 | 応答 |
|---|---|
| DeleteWorkspace（ワークスペースの削除／破棄） | 拒否します。ユーザーに次のように伝えてください：「このスキルではワークスペースの削除はサポートされていません。EMR Serverless Spark Console からワークスペースを削除してください。」 |
セキュリティガイドライン
ジョブ送信の保護
Spark ジョブを送信する前に、次のことを行う必要があります。
- ワークスペース ID とリソースキューを確認します
- コードタイプ codeType を確認します（必須：JAR / PYTHON / SQL）
- Spark パラメーターとメインプログラムのリソースを確認します
- 同等の spark-submit コマンドを表示します
- 送信前にユーザーから明示的な確認を得ます
タイムアウト制御
| 操作の種類 | タイムアウトの推奨値 |
|---|---|
| 読み取り専用クエリ | 30 秒 |
| 書き込み操作 | 60 秒 |
| ポーリング待機 | 1 回の試行につき 30 秒、合計 30 分以内 |
エラー処理
| エラーコード | 原因 | エージェントが実行すること |
|---|---|---|
| MissingParameter.regionId | CLI にデフォルトの Region が設定されておらず、--region も指定されていません | --region cn-hangzhou パラメーターを追加します |
| Throttling | API のレート制限 | 再試行の前に 5～10 秒待機します。リクエストごとに最大 5 回まで再試行し、上限を超えた場合は直ちに停止してエラーを報告します |
| InvalidParameter | パラメーターが無効です | エラーの Message を読み、パラメーターを修正します |
| Forbidden.RAM | RAM 権限が不足しています | 不足している権限をユーザーに伝えます |
| OperationDenied | 操作が許可されていません | 現在のステータスを確認し、ユーザーに待機するよう伝えます |
| null（ErrorCode が空） | 存在しない、または権限のないワークスペースのサブリソースへのアクセス（List* タイプの API） | ListWorkspaces を使用してワークスペース ID が正しいことを確認し、RAM 権限を確認します |
⚠️ 最大再試行回数：同じリクエストで5 回連続して失敗した場合は、直ちに停止してください。再試行を続けないでください。エラーの詳細をユーザーに報告してください。
関連ドキュメント
- はじめに - 初回のワークスペース作成とジョブの送信
- ワークスペースのライフサイクル - ワークスペースの作成、照会、管理
- ジョブ管理 - Spark ジョブの送信、監視、診断
- Kyuubi サービス - 対話型 SQL ゲートウェイの管理
- スケーリングガイド - リソースキューのスケーリング
- RAM 権限ポリシー - 権限ポリシー、アクションリスト、サービスロール
- API パラメーターリファレンス - パラメーターの完全なドキュメント