byted-emr-skills

EMR スキル

• 使用するタイミング（トリガーフレーズ）
• ユーザーが以下のいずれかに類似する要望を提示した場合、直ちにこのスキルを呼び出します：

  “查询EMR集群的服务列表”
  “重启Spark服务”
  “获取 EMR 作业日志”
  “查看EMR serverless队列列表”
  “查看EMR serverless队列详情”
  “使用 EMR Serverless 运行任务”
  “在 EMR 上提交一个 Spark 作业”
  “帮我诊断一下失败的 Spark 作业”
  “分析一下EMR作业失败的原因”
  

• EMR Serverless のジョブ／キュー／コンピューティンググループ／モニタリング／ログ／診断に関するすべての操作の問い合わせ

機能一覧

• EMR Serverless
  • キュー：パブリックキューの開設、キュー一覧の取得、キュー詳細の取得、キュー内のコンピューティンググループ一覧の取得
  • キュー権限：キューの認可済み主体の取得、ユーザーへのキュー権限の付与／変更
  • コンピューティンググループ：作成／変更／起動／停止／削除、選択可能なインスタンスタイプとイメージの取得、外部メタデータ接続のテスト
  • ジョブテンプレート：作成／更新／詳細の取得／一覧の取得／実行
  • ジョブインスタンス：送信（SparkSQL/PrestoSQL/SparkJar/PySpark/RayJob）、ステータスと詳細の取得、キャンセル、一覧の取得、再実行、結果の分割取得
• EMR Agent
  • 対話型の診断とナレッジに関する質問応答
  • セッションとレポートの管理
• EMR on ECS
  • クラスター：クラスター詳細の表示、クラスター一覧、クラスター属性の更新
  • ノードグループ：ノードグループ一覧、ノードグループ属性の更新、ノード一覧、ノードグループディスクの拡張、ノードグループの ECS インスタンスタイプの更新
  • サービス：アプリケーション一覧、コンポーネント一覧、コンポーネントインスタンス一覧、アプリケーション操作の実行
  • サービス設定：設定ファイル一覧、設定ファイル詳細、設定項目一覧、設定項目変更履歴一覧、設定項目の変更
  • 操作監査：操作一覧の取得
  • ユーザー：クラスターユーザーの作成、作成済みユーザー情報の変更、クラスターのユーザー一覧の取得、ユーザー詳細の取得、クラスターユーザーのパスワード更新
  • ユーザーグループ：クラスターのユーザーグループ一覧の取得、クラスターのユーザーグループ詳細、クラスターのユーザーグループの作成、クラスターのユーザーグループの更新
• EMR on VKE
  • クラスター：クラスター一覧、クラスター詳細の表示
  • サービス（アプリケーション）：サービス一覧、サービスのコンポーネントインスタンスの表示、サービスまたはコンポーネントインスタンスの再起動、サービス設定パラメーターの表示、サービス設定パラメーターの変更
  • 操作ログ：操作ログ一覧、操作ログ詳細の表示

初期設定

環境変数の設定

方法 1：ARK_SKILL_API 環境変数を使用（推奨）

以下の環境変数が設定済みの場合、火山エンジン API の認証情報を設定する必要はありません：

export ARK_SKILL_API_BASE="your-api-base-url"
export ARK_SKILL_API_KEY="your-api-key"

方法 2：火山エンジン API の認証情報を使用

ARK_SKILL_API 環境変数が設定されておらず、Serverless SDK の機能を使用する必要がある場合、または SDK エラーが発生した場合は、火山エンジン API の認証情報を設定する必要があります：

export VOLCENGINE_AK="your-access-key"
export VOLCENGINE_SK="your-secret-key"
export VOLCENGINE_REGION="cn-beijing"

• EMR Serverless SDK をインストールします。scripts/bin/install_serverless_sdk.sh を実行してインストールしてください。

EMR の管理方法

1. EMR on Serverless の管理

• フルマネージドの Serverless 形態を対象としており、主にジョブの送信とリソースキューの管理を行います。
• OpenAPI では、次のコマンドラインツールの使用を推奨します：python ./scripts/on_serverless/emr_serverless_cli.py --action <Action> --method <GET|POST> --query '<json>' --body '<json>'
  • Region はデフォルトで環境変数 VOLCENGINE_REGION から読み取ります（デフォルトは cn-beijing）
  • Service/Version は Action に基づいて自動的に推定されます（必要に応じて --service/--version を明示的に指定することもできます）
  • カスタム endpoint（LAS など）は、追加で --endpoint las.cn-beijing.volcengineapi.com を指定できます。
• ジョブの送信には、次のコマンドラインツールの使用を推奨します：python ./scripts/on_serverless/emr_serverless_submit_cli.py <sql|jar|pyspark|ray> ...

リソースキューの管理方法

• 対応機能一覧
  • キュー一覧：すべてのリソースキューとその設定（最大リソース、現在の使用量など）を表示します。キュー一覧の取得には、必ず OpenAPI の ListTagQueue を使用してください。
  • キュー詳細：バインドされたネットワークやストレージなど、キューの詳細情報を取得します。キュー詳細の取得には、必ず OpenAPI の GetQueue を使用してください。
  • キューの作成：パブリックキューをワンクリックで作成します。キューの作成には、必ず OpenAPI の CreateQueueSilently または CreateOrderInOneStep を使用してください。
  • キューのコンピューティンググループ一覧：指定したキュー内のコンピューティンググループ（Queue Component）の一覧と詳細を取得します。キューのコンピューティンググループ一覧の取得には、必ず OpenAPI の ListQueueComponent を使用してください。
• キュー機能のすべての操作の詳細については、references/emr_serverless/queue/emr_serverless_queue_guide.md の説明に厳密に従って操作してください。

キュー権限の管理方法

• 対応機能一覧
  • キュー権限一覧の取得：指定したキューに対する権限を持つユーザー／ユーザーグループの一覧を取得します。キュー権限一覧の取得には、必ず OpenAPI の ListAuthorizedPrincipalsForQueue を使用してください。
  • キュー権限のあいまい検索：ユーザー名でユーザー一覧をあいまい検索し、ユーザーが指定したキューの権限をすでに持っているかどうかも確認します。キュー権限一覧の取得には、必ず OpenAPI の ListIAMUsersWithQueueRole を使用してください。
  • ユーザー権限の追加：ユーザーに指定したデータオブジェクトの権限を付与します。ユーザー権限の追加には、必ず OpenAPI の GrantQueuePrivilege を使用してください。
  • ユーザーのキュー権限の変更：指定したキューに対するユーザーの権限を変更します。ユーザー権限の変更には、必ず OpenAPI の AlterQueuePrivilege を使用してください。
• 各機能の操作の詳細については、references/emr_serverless/privilege/emr_serverless_privilege_guide.md の説明に厳密に従って操作してください。

ジョブテンプレートの管理方法

• ジョブテンプレートとジョブインスタンスの違いに注意してください：
  • ジョブテンプレート：コードパス、パラメーター、環境変数など、ジョブの共通設定を定義します。
  • ジョブインスタンス：ジョブテンプレートに基づいて作成される具体的な実行インスタンスで、ジョブ ID、実行パラメーター、ステータスなどを含みます。
• 対応するジョブテンプレート機能一覧
  • ジョブテンプレートの作成：コードパス、パラメーター、環境設定などを含むジョブテンプレートを定義します。ジョブテンプレートの作成には、必ず OpenAPI の CreateJobDefinition を使用してください。
  • ジョブテンプレートの実行：既存のジョブテンプレートに基づいて実行を開始します。ジョブテンプレートの実行には、必ず OpenAPI の RunJobDefinition を使用してください。
  • ジョブテンプレートの変更：実行リソース、コードパス、エントリーコマンドなどのジョブテンプレート設定を変更します。送信済みのジョブインスタンスには影響しません。ジョブテンプレートの変更には、必ず OpenAPI の AlterJobDefinition を使用してください。
  • ジョブテンプレート詳細の取得：ジョブテンプレートの詳細な設定情報を取得します。ジョブテンプレート詳細の取得には、必ず OpenAPI の GetJobDefinition を使用してください。
  • ジョブテンプレート一覧の取得：作成済みのすべてのジョブテンプレートの一覧を取得します。ジョブテンプレート一覧の取得には、必ず OpenAPI の ListJobDefinitions を使用してください。
• すべてのジョブテンプレート（ジョブ定義）の詳細な操作ガイドについては、references/emr_serverless/job/emr_serverless_job_guide.md の説明に厳密に従って操作してください。

ジョブインスタンスの管理方法

• ジョブインスタンスの機能一覧
  • ジョブの送信：SparkSQL、PrestoSQL、SparkJar、PySpark、RayJob などのタイプに対応しています。SparkJar/PySpark/RayJob では、ジョブ実行スクリプトにローカルパスを指定できます（SDK によって TOS に自動アップロードされます。詳細はジョブインスタンスガイドを参照してください）。
  • ジョブインスタンスの取得：ステータスと詳細の取得には、OpenAPI の QueryGetJobV2 の使用を推奨します。
  • ジョブインスタンスの終了：OpenAPI の QueryCancelQueryV2。
  • 結果データの分割取得：SQL 系のジョブでは、OpenAPI の QueryFetchResultsByBatch を使用して結果を分割取得できます。
  • ジョブインスタンス一覧：OpenAPI の ListJobInstances。
• すべてのジョブインスタンスの詳細な操作ガイドについては、references/emr_serverless/job_instance/emr_serverless_job_instance_guide.md の説明に厳密に従って操作してください。

コンピューティンググループ（Serverless リソースユニット）の管理方法

• コンピューティンググループの設定を作成／変更します。

操作ログの取得方法

• 機能一覧
  • グローバル操作ログページ、およびキューとコンピューティンググループの操作一覧の取得
• 操作ログの取得については、references/emr_serverless/operation_audit/emr_serverless_operation_audit_guide.md の説明に厳密に従って操作してください。

2. EMR Agent（EMR AI アシスタント）

対話型の問題診断とナレッジに関する質問応答

• 機能一覧
  • すべての EMR 形態に対応し、対話型の問題診断とナレッジに関する質問応答を提供します。
• 料金について
  • EMR コンソール上の EMR Agent は現在、利用申請によるホワイトリスト登録が必要ですが、API 呼び出しには不要で、そのまま使用できます。
  • 現在、一定の無料利用枠があります。今後は利用状況に応じて課金されます。

如何管理诊断会话和报告管理

• 功能列表
  • 报告列表：获取历史诊断报告列表。
  • 查看报告详情：获取已有报告内容。
  • 会话列表：获取分析诊断和问答历史会话列表。
  • 查看会话详情：获取会话的详细信息，包括问题描述、回答内容、会话状态等。
• 所有分析诊断会话和报告操作，请严格按照references/emr_agent/emr_agent_guide.md中的说明进行操作。

3. EMR on ECS 集群管理

• 支持对基于 ECS 的传统 Hadoop 集群进行全生命周期管理。

如何管理集群

• 功能列表
  • 查看集群详情：获取集群基础信息、状态、计费类型、访问地址等，必须使用OpenAPIGetCluster查询集群详情。
  • 集群列表：按条件筛选、分页查询，必须使用OpenAPIListClusters查询集群列表。
  • 更新集群属性：修改集群名称、描述等，必须使用OpenAPIUpdateClusterAttribute更新集群属性。
• 所有集群管理操作详情，请严格按照references/emr_on_ecs/cluster/emr_on_ecs_cluster_guide.md中的说明进行操作。

节点组管理

• 功能列表
  • 列出节点组：查看集群内的节点组（如 Master、Core、Task）及其配置，必须使用OpenAPIListNodeGroups列出节点组列表。
  • 更新节点组属性：修改节点组名称、实例规格（支持升级）、磁盘扩容，必须使用OpenAPIUpdateNodeGroupAttribute更新节点组属性。
  • 节点列表：查看节点组内所有 ECS 实例的详细信息，必须使用OpenAPIListNodes查询节点组内所有节点实例的详细信息。
  • 扩容节点组磁盘：扩容指定节点组的磁盘容量，必须使用OpenAPIResizeNodeGroupDisk扩容节点组磁盘。
  • 更新节点组ECS规格：修改指定节点组的ECS实例规格，必须使用OpenAPIUpdateNodeGroupEcsSpec更新节点组ECS规格。
• 所有节点组管理操作详情，请严格按照references/emr_on_ecs/node_group/emr_on_ecs_node_group_guide.md中的说明进行操作。

应用管理

• 功能列表
  • 列出应用：查看集群已安装的大数据组件，必须使用OpenAPIListApplications列出应用列表。
  • 组件列表：查看每个服务的角色分布，必须使用OpenAPIListComponents列出组件列表。
  • 组件实例列表：查看每个组件的实例列表，必须使用OpenAPIListComponentInstances列出组件实例的实例列表。
  • 执行应用操作：对组件进行启动、停止、重启、滚动重启等操作，必须使用OpenAPIRunApplicationAction执行应用操作。
• 所有应用管理操作详情，请严格按照references/emr_on_ecs/application/emr_on_ecs_application_guide.md中的说明进行操作。

应用配置管理

• 功能列表
  • 配置文件列表：查看集群中指定应用的配置文件列表，必须使用OpenAPIListApplicationConfigFiles列出应用配置文件列表。
  • 配置文件详情：查看集群中指定应用的配置文件内容、修改时间等信息，必须使用OpenAPIGetApplicationConfigFile查询应用配置文件详情。
  • 配置项列表：查看集群中指定应用的配置项列表，包括配置项名称、当前值、默认值等信息，必须使用OpenAPIListApplicationConfigs列出应用配置项列表。
  • 配置项修改历史列表：查看集群中指定应用的配置项修改历史列表，必须使用OpenAPIListApplicationConfigHistories列出应用配置项修改历史列表。
  • 修改配置项：修改集群中指定应用的配置项值，必须使用OpenAPIUpdateApplicationConfig更新应用配置项。
• 所有应用配置管理操作详情，请严格按照references/emr_on_ecs/application_config/emr_on_ecs_application_config_guide.md中的说明进行操作。

操作审计管理

• 操作列表查询：查看集群中所有操作日志、支持分页查询，必须使用OpenAPIListOperations列出操作列表。
• 所有操作审计管理操作详情，请严格按照references/emr_on_ecs/operation/emr_on_ecs_operation_guide.md中的说明进行操作。

用户管理

• 功能列表
  • 创建集群用户：为集群新增用户，需指定用户名、密码等信息，必须使用OpenAPICreateClusterUser创建集群用户。
  • 修改已创建用户信息：修改指定集群中已存在用户的用户组或描述信息，必须使用OpenAPIUpdateClusterUser更新集群用户信息。
  • 获取集群用户列表：查询指定集群的用户信息列表，必须使用OpenAPIListClusterUsers列出集群用户列表。
  • 获取用户详情: 查询指定集群的详细用户信息，必须使用OpenAPIGetClusterUsers查询集群用户详情。
  • 更新集群用户密码：修改指定集群中已存在用户的登录密码，必须使用OpenAPIUpdateClusterUserPassword更新集群用户密码。
• 所有用户管理操作详情，请严格按照references/emr_on_ecs/user/emr_on_ecs_user_guide.md中的说明进行操作。

用户组管理

• 功能列表
  • 获取集群用户组列表: 查询指定集群的用户组信息列表，必须使用OpenAPIListClusterUserGroups列出集群用户组列表。
  • 集群用户组详情: 查询指定集群的详细用户组信息，必须使用OpenAPIGetClusterUserGroups查询集群用户组详情。
  • 创建集群用户组：为指定集群创建新的用户组，必须使用OpenAPICreateClusterUserGroup创建集群用户组。
  • 更新集群用户组：修改指定集群中已存在用户组的描述或成员信息，必须使用OpenAPIUpdateClusterUserGroup更新集群用户组。
• 所有用户组管理操作详情，请严格按照references/emr_on_ecs/user_group/emr_on_ecs_user_group_guide.md中的说明进行操作。

EMR on VKE 集群管理

• 所有集群管理操作详情，请严格按照references/emr_on_vke/emr_on_vke_guide.md中的说明进行操作。

Available Scripts

• scripts/on_serverless/emr_serverless_manager.py：统一的 EMR Serverless OpenAPI 调用入口（manage_emr_serverless），用于队列/作业实例/计算组等运维类接口调用。
• scripts/config/config.py: 封装EMR所用到的配置、SDK Client构造等。
• scripts/emr_agent/expert.py：与 EMR Agent 交互，实现智能诊断和知识问答。
• scripts/emr_agent/emr_agent_manager.py：获取EMR Agent的会话列表，报告列表等。
• scripts/bin/install_serverless_sdk.sh：安装 EMR on Serverless 形态的 Python SDK，用于 Serverless 队列管理、作业提交等操作。
• scripts/on_ecs/emr_on_ecs_manager.py：统一的 EMR on ECS 形态的 OpenAPI 调用入口（manage_emr_on_ecs），用于集群/节点组/应用等运维类接口调用。
• scripts/on_ecs/emr_on_ecs_cli.py：EMR on ECS 形态的命令行工具，用于集群/节点组/应用等运维类接口调用。
• scripts/on_vke/emr_on_vke_manager.py：EMR on VKE 形态 产品的管理脚本

References

• references/emr_serverless/queue/emr_serverless_queue_guide.md：EMR on Serverless形态的资源队列详细管理操作指南
• references/emr_serverless/job_instance/emr_serverless_job_instance_guide.md：EMR on Serverless形态的作业实例详细管理操作指南
• references/emr_serverless/job/emr_serverless_job_guide.md: EMR on Serverless形态的作业模板（即作业定义）管理操作指南
• references/emr_serverless/compute/emr_serverless_compute_guide.md: EMR on Serverless形态的计算组详细管理操作指南
• references/emr_agent/emr_agent_guide.md：EMR Agent 详细操作指南，包括问题分析、获取历史会话、获取历史诊断报告等。
• references/emr_on_ecs/cluster/emr_on_ecs_cluster_guide.md：EMR on ECS 集群管理操作指南，包括集群列表查询、集群详情查询、更新集群属性等。
• references/emr_on_ecs/node_group/emr_on_ecs_node_group_guide.md：EMR on ECS 节点组管理操作指南，包括节点组列表查询、节点组详情查询、更新节点组属性等。
• references/emr_on_ecs/application/emr_on_ecs_application_guide.md：EMR on ECS 应用管理操作指南，包括应用列表查询、组件列表查询、组件实例列表查询、执行应用操作等。
• references/emr_on_ecs/application_config/emr_on_ecs_application_config_guide.md：EMR on ECS 应用配置管理操作指南，包括配置文件列表查询、配置文件详情查询、配置项列表查询、配置项修改历史列表查询、修改配置项等。
• references/emr_on_ecs/operation/emr_on_ecs_operation_guide.md：EMR on ECS 操作审计管理操作指南，包括操作列表查询等。
• references/emr_on_ecs/user/emr_on_ecs_user_guide.md：EMR on ECS 用户管理操作指南，包括创建用户、修改用户信息、查询用户列表、查询用户详情、更新用户密码等。
• references/emr_on_ecs/group/emr_on_ecs_group_guide.md：EMR on ECS 用户组管理操作指南，包括查询用户组列表、查询用户组详情、创建用户组、更新用户组等。
• references/emr_on_vke/emr_on_vke_guide.md：EMR on VKE集群管理操作指南。包括查询集群列表和详情、查询服务列表与详情、查询操作日志列表与详情、重启服务、查询和更新服务配置参数等。

Assets

• assets/libs/python_serverless-1.*-py3-none-any.whl: EMR on Serverless 形态的 Python SDK 包，用于 EMR Serverless 作业提交等操作。
• assets/emr-serverless-job-template.json：Serverless 作业提交模板，包含 PySpark 作业参数示例。

Requirements

• 如果需要写临时文件（比如编写脚本、记录备忘录等），必须将文件放在./tmp文件夹下。
• 当遇到作业、服务、集群失败或者用户有诊断需求的时候，必须优先使用EMR Agent的诊断功能，而不是自己去分析诊断。EMR Agent诊断需要消耗一定时间，应该等待其诊断完成，不要中途kill诊断任务
• 不要去读取scripts下脚本的内容，按照guide文档的说明执行即可，除非你有必须读的理由（比如执行频繁遭遇失败需要排查问题或用户咨询实现细节等）
• 当你通过python代码引入script下的包时，你需要将emr-skills的根目录加入path：sys.path.append(${emr_skill_root})
• 当你通过python代码提交任务并等待完成时，你需要分为两个python脚本，先执行提交任务脚本，得到job_id后，再执行状态获取脚本；状态获取脚本不要在脚本内用While循环一直获取状态，而是应该仅获取一次状态，通过多次运行脚本持续获取状态