mcpField
A
alibabacloud-cms-dataset

alibabacloud-cms-dataset

github.com/aliyunデータ・データベース281154 回インストール1 日前に更新
リポジトリ

alibabacloud-cms-dataset について

`aliyun` CLI で Alibaba Cloud CloudMonitor（CMS）のデータセットを管理するエージェントスキルです。データセットのライフサイクル操作と SQL クエリに対応し、ワークスペース、スキーマ、権限も確認します。

主な機能

  1. 01データセットの一覧表示と確認
  2. 02データセットの作成と削除
  3. 03データセットの説明の更新
  4. 04データセットへの SQL クエリ実行
  5. 05クエリ生成前のスキーマ確認

活用シーン

  1. 01CMS ワークスペース内のデータセット確認
  2. 02指定したスキーマでのデータセット作成
  3. 03データセットの説明変更
  4. 04実際のフィールドに基づくデータ検索

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/aliyun/alibabacloud-aiops-skills --skill alibabacloud-cms-dataset

インストール後、Claude Code で/alibabacloud-cms-datasetを入力して読み込まれたか確認します。

同梱ファイル

SKILL.md と一緒にインストールされる参考資料やスクリプト。

references/
acceptance-criteria.md
cli-installation-guide.md
ram-policies.md
related-commands.md
verification-method.md

詳細

CMS データセットのライフサイクル管理とクエリ

aliyun CLI を使用して、CloudMonitor（CMS）のデータセットリソースを管理します。データセットの一覧表示、確認、作成、更新、削除、およびデータセットレベルのクエリを実行できます。

アーキテクチャ：CMS Workspace + Dataset (Schema + Fields) + ExecuteQuery

インストール

Aliyun CLI をインストールする

aliyun version を実行して、バージョンが 3.3.3 以降であることを確認します。インストールされていない場合や古いバージョンの場合は、references/cli-installation-guide.md の手順に従ってインストールまたは更新してください。

プラグインを最新の状態にする

[MUST] 自動プラグインインストールを有効にするため、aliyun configure set --auto-plugin-install true を実行してください。 [MUST] 既存のプラグインを常に最新の状態にするため、aliyun plugin update を実行してください。

AI モードのライフサイクル

コアワークフローの開始時（CLI を呼び出す前）： [MUST] AI モードを有効にする — エージェントスキルの実行には AI モードが必要です。

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-cms-dataset"

[MUST] あらゆる終了時点で AI モードを無効にする — どのような理由であっても、最終応答を返す前に必ず AI モードを無効にしてください。これは、ワークフローの成功、ワークフローの失敗、エラー／例外、ユーザーによるキャンセル、セッションの終了、その他 CLI コマンドをこれ以上実行しないあらゆる状況を含む、すべての終了パスに適用されます。

aliyun configure ai-mode disable

認証

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

セキュリティルール：

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

出力を確認し、有効なプロファイル（AK、STS、または OAuth ID）があることを確かめます。

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

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

RAM ポリシー

必要な権限の全一覧については、references/ram-policies.md を参照してください。

最低限必要なアクション：cms:ListDatasets、cms:GetDataset、cms:CreateDataset、cms:UpdateDataset、cms:DeleteDataset、cms:ExecuteQuery。

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

  1. references/ram-policies.md を読み、この SKILL に必要な権限の全一覧を確認します
  2. ram-permission-diagnose スキルを使用して、必要な権限を申請する手順をユーザーに案内します
  3. 必要な権限が付与されたことをユーザーが確認するまで待機します

パラメーターの確認

IMPORTANT: パラメーターの確認 — コマンドや API 呼び出しを実行する前に、 ユーザーがカスタマイズできるすべてのパラメーター（例：RegionId、インスタンス名、CIDR ブロック、 パスワード、ドメイン名、リソース仕様など）を、必ずユーザーに確認してください。 明示的な承認なしに、デフォルト値を推測したり使用したりしないでください。

パラメーター必須／任意説明デフォルト値
workspace必須CMS ワークスペース ID—
dataset-name必須（ListDatasets を除く）データセット名（4～63 文字）—
region任意リージョン IDCLI プロファイルのリージョン
schema必須（CreateDataset）スキーマ JSON オブジェクト—
description任意データセットの説明—
query必須（ExecuteQuery）クエリテキスト—
type自動入力（ExecuteQuery）クエリタイプのプレースホルダー。常に SQL です。ユーザーに尋ねないでくださいSQL
max-results任意（ListDatasets）ページあたりの最大結果数—
next-token任意（ListDatasets）次のページのページネーショントークン—

命名規則

データセット名とスキーマのフィールド名は、次の条件を満たす必要があります。

  • 長さ：4～63 文字
  • 小文字で始まる
  • 小文字、数字、アンダースコアのみ使用可能
  • 先頭または末尾のアンダースコア、および連続するアンダースコアは使用不可

正規表現：^[a-z](?!.*__)[a-z0-9_]{2,61}[a-z0-9]$

無効な名前を黙って正規化してはいけません。ユーザーに有効な名前を提示するよう求めてください。

コアワークフロー

[CRITICAL] 製品の固定： このスキルのデータセット操作では、cms 製品のみを使用します。 正しいコマンドの形式は aliyun cms <action> --api-version 2024-03-30 です。 データセット操作に他の製品を使用してはいけません。 このシナリオでは、dataworks、adb、sls、maxcompute、opensearch、pai、dashvector、その他のサービスは誤りです。 コマンドが失敗した場合は、パラメーターと権限を確認してください。別の製品に切り替えてはいけません。

すべてのコマンドで --api-version 2024-03-30 を使用します。デフォルトでは --endpoint を渡さないでください。リージョンを指定する際は、--region-id ではなく --region を使用します。

0. ワークスペースの存在を確認する

[MUST] データセット操作を実行する前に、get-workspace を呼び出してワークスペースが存在することを確認してください。この手順を省略したり、ListDatasets からワークスペースの存在を推測したりしてはいけません。

aliyun cms get-workspace --api-version 2024-03-30 \
  --workspace <workspace>

ワークスペースが存在しない場合（エラーが返される場合）は、put-workspace を使用して作成します。

aliyun cms put-workspace --api-version 2024-03-30 \
  --workspace-name <workspace> \
  --sls-project <sls-project>

--sls-project は必須です。ユーザーが指定しない場合は、ワークスペース名と同じ値を使用します。

1. データセットの一覧表示
aliyun cms list-datasets --api-version 2024-03-30 \
  --workspace <workspace> \
  [--dataset-name <filter>] \
  [--max-results <n>] \
  [--next-token <token>]
2. データセットの取得
aliyun cms get-dataset --api-version 2024-03-30 \
  --workspace <workspace> \
  --dataset-name <dataset-name>
3. データセットの作成

安全性： 作成前に ListDatasets を使用して、データセットがすでに存在するか確認してください。すでに存在する場合はユーザーに伝え、続行するか確認してください（API は重複に対してエラーを返します）。ユーザーが作成を依頼した場合は、必ず CreateDataset を呼び出してください。黙ってスキップしてはいけません。

スキーマ JSON は、単一引用符で囲んだ文字列として直接渡します。

aliyun cms create-dataset --api-version 2024-03-30 \
  --workspace <workspace> \
  --dataset-name <dataset-name> \
  --schema '{"message_text":{"type":"text","chn":true,"embedding":"text-embedding-v4"},"service_name":{"type":"text","chn":false}}' \
  [--description "<description>"]

スキーマの規則：

  • --schema の値はフィールド定義オブジェクトそのものです（API ボディでラップしません）。
  • 各トップレベルキーはフィールド名です。各値には type、任意で chn、任意で embedding、任意で jsonKeys を指定します。
  • embedding を有効にできるのは type: "text" のフィールドのみです。テキスト以外のフィールドでの embedding は拒否してください。
  • jsonKeys は、ネストされた JSON キー構造を定義します。ネストされたキーで指定できるのは type と chn のみです（embedding は指定できません）。
{
  "event_data": {
    "type": "text",
    "chn": false,
    "jsonKeys": {
      "source": {
        "type": "text",
        "chn": false
      },
      "message": {
        "type": "text",
        "chn": true
      }
    }
  }
}
4. データセットの更新

安全性： 更新前に現在の説明を読み取り、表示してください。

制限： UpdateDataset で変更できるのは説明のみです。この API ではスキーマを更新できません。スキーマを変更する必要がある場合は、データセットを削除して再作成する必要があります。

# Show current state
aliyun cms get-dataset --api-version 2024-03-30 \
  --workspace <workspace> --dataset-name <dataset-name>

# Update after user confirms
aliyun cms update-dataset --api-version 2024-03-30 \
  --workspace <workspace> \
  --dataset-name <dataset-name> \
  --description "<new-description>"
5. データセットの削除

安全性： データセットを読み取って表示した後、削除する前に、ワークスペース名とデータセット名を明示してユーザーに確認してください。

# Show dataset to confirm
aliyun cms get-dataset --api-version 2024-03-30 \
  --workspace <workspace> --dataset-name <dataset-name>

# Delete after explicit confirmation
aliyun cms delete-dataset --api-version 2024-03-30 \
  --workspace <workspace> \
  --dataset-name <dataset-name>
6. クエリを実行する

安全性： 可能な場合は、まず GetDataset でデータセットのスキーマを確認し、フィールド名を実際のスキーマに基づいて指定します。

aliyun cms execute-query --api-version 2024-03-30 \
  --workspace <workspace> \
  --dataset-name <dataset-name> \
  --type SQL \
  --query '<query>'
  • --type は必須のプレースホルダーです。必ず SQL を渡してください。
  • ユーザーが完全なクエリを指定した場合は、安全なシェルクォートを除き、そのまま保持してください。
  • 自然言語からクエリを生成する場合： ユーザーがクエリを提示せず、自然言語で分析の意図を説明した場合は、まず GetDataset を呼び出して実際のスキーマとフィールド名を取得し、そのフィールド名に基づいてクエリを生成してください。スキーマを確認せずにフィールド名を推測してはいけません。
  • 完全な JSON レスポンスを最初に提示し、その後、進捗状況、返された行数、影響を受けた行数、経過時間を要約してください。

成功の確認

各操作の確認コマンドについては、手順を追って説明した references/verification-method.md を参照してください。

クリーンアップ

このセッション中に作成したデータセットを削除するには：

aliyun cms delete-dataset --api-version 2024-03-30 \
  --workspace <workspace> \
  --dataset-name <dataset-name>

出力の要件

  • API レスポンスは、必ず完全な JSON を最初に表示してください。
  • その後、人が読みやすい簡潔な要約を提示してください。
  • 書き込みのプレビューには、ワークスペース、データセット名、リージョン、説明、スキーマ全体を含めてください。
  • クエリ結果には、進捗状況、行数、影響を受けた行数、経過時間を含めてください。

コマンド一覧

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

コマンド説明
aliyun cms get-workspaceワークスペースが存在することを確認する
aliyun cms put-workspaceワークスペースを作成または更新する
aliyun cms list-datasetsワークスペース内のデータセットを一覧表示する
aliyun cms get-datasetデータセットの詳細とスキーマを取得する
aliyun cms create-datasetスキーマを指定して新しいデータセットを作成する
aliyun cms update-datasetデータセットの説明を更新する
aliyun cms delete-datasetデータセットを削除する
aliyun cms execute-queryデータセットに対してクエリを実行する

ベストプラクティス

  1. 常に --api-version 2024-03-30 を指定してください。デフォルトの CMS バージョン（2019-01-01）はデータセット操作に対応していません。
  2. CreateDataset を呼び出す前に、データセット名とフィールド名が命名規則の正規表現に適合していることを検証してください。
  3. クエリを生成する前に GetDataset でスキーマを確認し、推測ではなく実際のフィールド名を使用してください。
  4. シェルのクォートによる問題を避けるため、スキーマ JSON は単一引用符で囲んだ文字列として直接渡してください。
  5. 書き込み操作（Create、Update、Delete）は、実行前に必ずユーザーに確認してください。
  6. 重複を避けるため、作成前にデータセットが存在するか確認してください。
  7. リージョンを明示的に指定する場合は、--region（--region-id ではなく）を使用してください。
  8. 明示的に必要とされない限り --endpoint は渡さないでください。必要な場合は cms.<region>.aliyuncs.com を使用してください。
  9. ExecuteQuery では、必須のプレースホルダーとして必ず --type SQL を渡してください。
  10. 一時ファイルの管理を避けるため、--schema にはインライン JSON を使用してください。
  11. 製品を切り替えてはいけません。 cms コマンドが失敗した場合は、パラメーターや権限を調査してください。dataworks、adb、sls、maxcompute、その他の製品を試してはいけません。このスキルでいう「ワークスペース」は CMS ワークスペースであり、DataWorks／SLS／MaxCompute のプロジェクトではありません。
  12. タイムアウトを明示的に設定してください。 メタデータ操作（list/get/create/update/delete）には --read-timeout 30 --connect-timeout 10 を使用してください。クエリに時間がかかることがあるため、ExecuteQuery には --read-timeout 120 --connect-timeout 10 を使用してください。

参考リンク

参考資料説明
references/ram-policies.mdRAM 権限の要件
references/related-commands.mdCLI コマンドの完全なリファレンス
references/verification-method.md成功の確認手順
references/acceptance-criteria.md正しい例と誤った例
references/cli-installation-guide.mdCLI のインストールガイド

コメント

Markdown 対応