alibabacloud-opensearch-app-manage

Name: alibabacloud-opensearch-app-manage
Author: aliyun

github.com/aliyunクラウド・DevOps281113 回インストール1 日前に更新

リポジトリ

alibabacloud-opensearch-app-manage について

Aliyun CLI で Alibaba Cloud OpenSearch インスタンスを管理するスキルです。インスタンスの作成や一覧・詳細の確認に対応し、パラメーター確認、認証情報の保護、重複リクエスト対策の手順を含みます。

主な機能

01OpenSearch インスタンスの作成
02インスタンスの一覧表示と絞り込み
03インスタンス詳細の取得
04ドライランによる作成パラメーターの検証
05冪等性トークンの使用

活用シーン

01設定を指定して OpenSearch インスタンスを作成
02Alibaba Cloud アカウント内のインスタンスを確認
03インスタンスのクォータと課金情報を確認

インストール

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

$npx skills add https://github.com/aliyun/alibabacloud-aiops-skills --skill alibabacloud-opensearch-app-manage

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

同梱ファイル

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

references/

acceptance-criteria.md

cli-installation-guide.md

ram-policies.md

related-apis.md

verification-method.md

詳細

OpenSearch インスタンス管理

Alibaba Cloud OpenSearch インスタンスの作成やクエリ操作などを管理します。

用語：OpenSearch インスタンスと OpenSearch アプリグループは同義です。このドキュメントでは、どちらも「インスタンス」と表記します。

シナリオの説明

OpenSearch は Alibaba Cloud のインテリジェント検索サービスです。このスキルでは、インスタンス管理の主要な操作を扱います。

インスタンスの作成 - 新しい OpenSearch インスタンスを作成します
インスタンスの一覧表示 - 現在のアカウントに属するインスタンスの一覧を取得します
インスタンスの詳細表示 - 特定のインスタンスの詳細情報を取得します

アーキテクチャ：OpenSearch Instance（AppGroup）

Alibaba Cloud OpenSearch Instance Management
├── CreateAppGroup     (Create Instance)
├── DescribeAppGroup   (Describe Instance)
└── ListAppGroups      (List Instances)

インストール

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

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

# Install/Upgrade Aliyun CLI
curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash
aliyun version  # Ensure >= 3.3.3

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

# Update plugins
aliyun plugin update

[MUST] CLI User-Agent — aliyun CLI コマンドを実行するたびに、次を指定する必要があります。 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

[MUST] AI-Mode — CLI コマンドを実行する前に、次を実行してください。

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage" すべての CLI 操作が完了したら、次を実行してください：aliyun configure ai-mode disable

認証

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

セキュリティルール（必ず遵守してください）：

AK/SK の値を読み取ったり、エコーしたり、表示したりしないでください

会話内で AK/SK を直接入力するようユーザーに求めないでください

リテラルの認証情報を指定して aliyun configure set を実行しないでください

会話内でユーザーから直接提供された AK/SK を受け入れないでください

認証情報は環境変数または事前設定済みの CLI プロファイルからのみ読み取ってください

⚠️ 重要：ユーザーから提供された認証情報の取り扱い

ユーザーが AK/SK を直接提供しようとした場合（例：「私の AK は xxx、SK は yyy です」）：
直ちに停止してください - コマンドを実行しないでください
次のメッセージを使って、丁寧に依頼をお断りしてください：
アカウントのセキュリティを守るため、Alibaba Cloud の AccessKey ID と AccessKey Secret を会話内で直接提供しないでください。

認証情報は、次の安全な方法で設定してください。

方法 1：aliyun configure を使った対話型設定（推奨）
    aliyun configure
    # プロンプトに従って AK/SK を入力します。認証情報はローカルの設定ファイルに安全に保存されます

方法 2：環境変数を使った設定
    export ALIBABA_CLOUD_ACCESS_KEY_ID=<your-access-key-id>
    export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<your-access-key-secret>

設定が完了したら、リクエストを再度お試しください。
認証情報が適切に設定されるまで、Alibaba Cloud の操作を続行しないでください
CLI 設定の確認：
   aliyun configure list
有効なプロファイル（AK、STS、または OAuth ID）があるか、出力を確認してください。

有効な認証情報がない場合は、ここで停止してください。

RAM 権限

[MUST] RAM 権限の事前確認： 操作を実行する前に、現在のユーザーが必要な RAM 権限を持っていることを確認してください。詳しい権限一覧については、references/ram-policies.md を参照してください。

パラメーターの確認

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

必須パラメーター

パラメーター	必須	説明	デフォルト
`name`	はい	インスタンス名	なし
`type`	はい	インスタンスタイプ：`standard`（高性能）／`enhanced`（業界アルゴリズム）	なし
`chargeType`	いいえ	課金タイプ：`POSTPAY`／`PREPAY`	`POSTPAY`
`quota.spec`	はい	仕様タイプ（下表を参照）	なし
`quota.docSize`	はい	ストレージ容量（GB）	なし
`quota.computeResource`	はい	コンピューティングリソース（LCU）	なし
`domain`	いいえ	業界タイプ（enhanced タイプでは必須。下表を参照）	`general`
`order`	条件付き	サブスクリプション注文情報（PREPAY の場合は必須）	なし
`order.duration`	条件付き	サブスクリプション期間の数量	なし
`order.pricingCycle`	条件付き	期間の単位：`Year`／`Month`	なし
`order.autoRenew`	いいえ	自動更新	`false`

仕様タイプ

仕様コード	説明
`opensearch.share.common`	共有共通
`opensearch.private.common`	専用共通
`opensearch.private.compute`	専用コンピューティング
`opensearch.private.storage`	専用ストレージ

業界タイプ（enhanced タイプのみ）

業界コード	説明
`general`	一般（デフォルト）
`ecommerce`	Eコマース
`esports`	ゲーム
`community`	コンテンツコミュニティ
`education`	教育

基本的なワークフロー

注： OpenSearch API は ROA（RESTful） スタイルを使用します。--body を使用して、HTTP リクエストボディを JSON 文字列で指定できます。各タスクの例を参照してください。

冪等性： 書き込み操作（作成、再起動、削除など）では、冪等性を確保するために --client-token パラメーターを必ず使用してください。

clientToken として UUID 形式の一意な識別子を使用してください

リクエストがタイムアウトまたは失敗した場合は、同じ clientToken を使用して安全に再試行できます。再試行の前に10秒待つことをおすすめします

同じ clientToken を使ったリクエストを繰り返しても、操作は複数回実行されません

生成方法：uuidgen（macOS/Linux）または [guid]::NewGuid()（PowerShell）

タスク 1：OpenSearch インスタンスを作成する

# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

aliyun opensearch create-app-group \
  --client-token "$CLIENT_TOKEN" \
  --body '{
    "name": "<instance_name>",
    "type": "<standard|enhanced>",
    "chargeType": "<POSTPAY|PREPAY>",
    "quota": {
      "docSize": <storage_GB>,
      "computeResource": <compute_LCU>,
      "spec": "<spec_type>"
    }
  }' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

オプションパラメーター（ボディに追加）：

domain - 業界タイプ（enhanced タイプのみ）：general（デフォルト）／ecommerce／esports／community／education

冪等性とドライランのサポート（クエリパラメーターを使用）：

--dryRun true - ドライランモード。実際に作成せず、パラメーターを検証します
--client-token <unique_id> - 冪等性トークン。同じトークンを複数のリクエストで使用した場合、作成は1回のみ実行されます

例：従量課金の enhanced（業界アルゴリズム）インスタンスを作成する（Eコマース）

# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

aliyun opensearch create-app-group \
  --client-token "$CLIENT_TOKEN" \
  --body '{
    "name": "my_search_instance",
    "type": "enhanced",
    "chargeType": "POSTPAY",
    "domain": "ecommerce",
    "quota": {
      "docSize": 100,
      "computeResource": 2000,
      "spec": "opensearch.private.common"
    }
  }' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

例：standard（高性能）インスタンスを作成する

# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

aliyun opensearch create-app-group \
  --client-token "$CLIENT_TOKEN" \
  --body '{
    "name": "my_standard_instance",
    "type": "standard",
    "chargeType": "POSTPAY",
    "quota": {
      "docSize": 50,
      "computeResource": 1000,
      "spec": "opensearch.share.common"
    }
  }' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

例：サブスクリプション（前払い）インスタンスを作成する

注：サブスクリプションインスタンスでは、order パラメーターを必ず指定してください

# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

aliyun opensearch create-app-group \
  --client-token "$CLIENT_TOKEN" \
  --body '{
    "name": "my_prepay_instance",
    "type": "enhanced",
    "chargeType": "PREPAY",
    "domain": "ecommerce",
    "quota": {
      "docSize": 100,
      "computeResource": 2000,
      "spec": "opensearch.private.common"
    },
    "order": {
      "duration": 1,
      "pricingCycle": "Year",
      "autoRenew": true
    }
  }' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

ドライランモードの例（パラメーターのみを検証し、実際には作成しません）：

aliyun opensearch create-app-group \
  --dryRun true \
  --body '{
    "name": "my_search_instance",
    "type": "enhanced",
    "chargeType": "POSTPAY",
    "quota": {
      "docSize": 100,
      "computeResource": 2000,
      "spec": "opensearch.private.common"
    }
  }' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

冪等性を考慮した作成の例（重複作成を防止します）：

# Generate idempotency token
CLIENT_TOKEN=$(uuidgen)

aliyun opensearch create-app-group \
  --client-token "$CLIENT_TOKEN" \
  --body '{
    "name": "my_search_instance",
    "type": "enhanced",
    "chargeType": "POSTPAY",
    "quota": {
      "docSize": 100,
      "computeResource": 2000,
      "spec": "opensearch.private.common"
    }
  }' \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

タスク 2：インスタンスを一覧表示する

aliyun opensearch list-app-groups \
  --engine-type ha3 \
  --page-number <page> \
  --page-size <size> \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

サポートされているフィルターパラメーター：

--engine-type ha3 - エンジンタイプ（デフォルトは ha3。明示的に指定する必要があります）
--name <instance_name> - 名前でフィルター
--instance-id <instance_id> - インスタンス ID でフィルター
--type <standard|enhanced> - タイプでフィルター
- standard：高性能
- enhanced：業界アルゴリズム
--sort-by <field> - 並べ替えフィールド

例：インスタンスを一覧表示する

aliyun opensearch list-app-groups \
  --engine-type ha3 \
  --page-number 1 \
  --page-size 10 \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

タスク 3：インスタンスの詳細を取得する

aliyun opensearch describe-app-group \
  --app-group-identity <instance_name_or_id> \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

例：インスタンスの詳細を取得する

aliyun opensearch describe-app-group \
  --app-group-identity my_search_instance \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

レスポンスに含まれる情報：

基本情報（instanceId、name、type、status）
クォータ情報（quota：docSize、computeResource、spec）
課金情報（chargeType、chargingWay）
バージョン情報（currentVersion、versions）
ステータス情報（lockMode、produced）
エンジン情報（engineType）

成功の確認

操作の確認については、references/verification-method.md を参照してください

簡易確認

インスタンス作成の確認：

aliyun opensearch describe-app-group \
  --app-group-identity <instance_name> \
  --connect-timeout 3 \
  --read-timeout 10 \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-opensearch-app-manage

result.instanceId フィールドが空でないことを確認します。空でなければ、インスタンスの作成は成功です。

リソースのクリーンアップ

インスタンスを削除するには、OpenSearch コンソールを使用してください。

API とコマンドのリファレンス

API の一覧については、references/related-apis.mdを参照してください。

操作	CLI コマンド	API アクション
インスタンスの作成	`aliyun opensearch create-app-group`	CreateAppGroup
インスタンスの一覧表示	`aliyun opensearch list-app-groups`	ListAppGroups
インスタンスの詳細表示	`aliyun opensearch describe-app-group`	DescribeAppGroup

ベストプラクティス

書き込み操作のパラメーター確認（必須）

重要：書き込み操作（インスタンスの作成など）を実行する前に、以下のパラメーターを必ずユーザーに確認してください。

作成前の確認チェックリスト：

パラメーター	説明	例
リージョン	インスタンスのリージョン	`cn-hangzhou` / `cn-shanghai` / `cn-beijing`
インスタンス名（name）	ユーザー指定の名前（小文字、数字、アンダースコア）	`my_search_instance`
インスタンスタイプ（type）	高性能／業界アルゴリズム	`standard` / `enhanced`
課金タイプ（chargeType）	従量課金／サブスクリプション	`POSTPAY` / `PREPAY`
仕様タイプ（quota.spec）	共有／専有	`opensearch.share.common`
ストレージ（quota.docSize）	GB 単位	`100`
コンピューティング（quota.computeResource）	LCU 単位	`2000`
業種（domain）	enhanced タイプの場合のみ	`ecommerce` / `general`
サブスクリプション期間（order）	PREPAY の場合のみ	1 年／6 か月

確認フローの例：

You are about to create the following OpenSearch instance, please confirm:

- Region: cn-hangzhou (China East 1)
- Instance Name: my_search_instance
- Instance Type: Industry Algorithm (enhanced)
- Industry: E-commerce (ecommerce)
- Charge Type: Pay-as-you-go (POSTPAY)
- Spec Type: Dedicated Common (opensearch.private.common)
- Storage: 100 GB
- Compute: 2000 LCU

Confirm creation? (yes/no)

冪等性に関するベストプラクティス

書き込み操作（作成、再起動、削除）では、以下の冪等性に関するベストプラクティスに従ってください。

各操作の前に一意のトークンを生成する：uuidgen を使用して UUID を生成します。
タイムアウト時の再試行では同じトークンを再利用する：リクエストがタイムアウトした場合は、同じ clientToken を使用して再試行します。
操作ごとに異なるトークンを使用する：独立した各操作には、新しい clientToken が必要です。
トークンの有効期間：clientToken の有効期間は通常 24 時間です。

# Example: Safe retry pattern
CLIENT_TOKEN=$(uuidgen)
echo "Using clientToken: $CLIENT_TOKEN"

# First attempt
aliyun opensearch create-app-group --client-token $CLIENT_TOKEN ...

# If timeout, retry with same Token
aliyun opensearch create-app-group --client-token $CLIENT_TOKEN ...

その他のベストプラクティス

命名規則：インスタンス名は英字で始める必要があります。使用できるのは小文字、数字、アンダースコア（_）のみで、ハイフン（-）は禁止です。最大 30 文字です。
- ✅ 正しい例：my_search_instance、video_search、product_search_2024
- ❌ 誤った例：my-search-instance、My_Search、123_search
クォータの計画：実際のデータ量とクエリ要件に基づいて、ストレージとコンピューティングリソースを計画します。
課金タイプの選択：
- テスト／開発環境：従量課金（POSTPAY）を使用します。
- 本番環境：コスト削減のため、サブスクリプション（PREPAY）を検討します。
- 注：サブスクリプションインスタンスでは、order パラメーター（期間と pricingCycle を含む）を必ず指定する必要があります。
インスタンスタイプの選択：
- 高性能（standard）：一般的な検索シナリオに適しています。
- 業界アルゴリズム（enhanced）：特定の業種のシナリオに適しており、domain パラメーターが必要です。
業種の選択（業界アルゴリズム）：
- E コマース：ecommerce
- ゲーム：esports
- コンテンツコミュニティ：community
- 教育：education
- 一般：general（デフォルト）
仕様の選択：
- 共有共通：小規模なシナリオに適しています。
- 専有：本番環境に適しており、より安定したパフォーマンスを提供します。
リソースのクリーンアップ：不要になった従量課金インスタンスは速やかに削除し、余計なコストが発生しないようにします。

Reference Links

Document	Description
references/related-apis.md	Complete API List
references/ram-policies.md	RAM Policies
references/verification-method.md	Verification Methods
references/cli-installation-guide.md	CLI Installation Guide
references/acceptance-criteria.md	Acceptance Criteria

Markdown 対応

ログインしてコメント

基本情報

作者: aliyun
リポジトリ: aliyun/alibabacloud-aiops-skills
カテゴリ: クラウド・DevOps
インストール数: 113
GitHub スター: 281

問題を報告