alibabacloud-resourcecenter-search

1. 前提条件

[MUST] CLI User-Agent — すべての aliyun CLI コマンドの実行時に、次を含める必要があります。 --user-agent AlibabaCloud-Agent-Skills/alibabacloud-resourcecenter-search

[MUST] AI-Mode の有効化 — エージェントスキルの実行には AI-mode が必要です。 ほかの aliyun CLI コマンドを実行する前に、次のコマンドを実行してください。

aliyun configure ai-mode enable
aliyun configure ai-mode set-user-agent --user-agent "AlibabaCloud-Agent-Skills/alibabacloud-resourcecenter-search"

事前確認：Aliyun CLI >= 3.3.3 が必要です aliyun version を実行して、バージョンが >= 3.3.3 であることを確認してください。インストールされていない場合、またはバージョンが低い場合は、 curl -fsSL https://aliyuncli.alicdn.com/setup.sh | bash を実行してインストールまたは更新するか、 インストール手順については references/cli-installation-guide.md を参照してください。 次に、[MUST] aliyun configure set --auto-plugin-install true を実行して、自動プラグインインストールを有効にしてください。 次に、[MUST] aliyun plugin update を実行して、ローカルマシン上の既存のプラグインを常に最新の状態にしてください。

事前確認：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 に有効なプロファイルが表示されたら、戻って再実行します

[MUST] すべての終了時に AI-Mode を無効化 — 理由を問わず最終応答を返す前に、必ず最初に AI-mode を無効にしてください。これは、ワークフローの成功、ワークフローの失敗、エラーや例外、ユーザーによるキャンセル、セッションの終了、または CLI コマンドをこれ以上実行しないその他のあらゆる状況を含む、すべての終了経路に適用されます。 AI-mode はエージェントスキルの呼び出し時にのみ使用し、スキルの実行停止後も有効な状態にしておいてはなりません。

aliyun configure ai-mode disable

---

2. パラメーターの確認

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

パラメーター	必須／任意	説明	デフォルト値
Scope	必須（クロスアカウント）	クロスアカウント検索の範囲：リソースディレクトリ ID、ルートフォルダー ID、フォルダー ID、またはメンバー ID	なし
ResourceType	任意	リソースタイプ（例：ACS::ECS::Instance）	なし（すべてのタイプ）
RegionId	任意	リソースのリージョン ID（例：cn-hangzhou）	なし（すべてのリージョン）
ResourceId	任意	リソース ID	なし
ResourceName	任意	リソース名	なし
VpcId	任意	VPC ID（例：vpc-xxx）	なし
VSwitchId	任意	VSwitch（例：vsw-xxx）	なし
IpAddress	任意	IP アドレス	なし
GroupByKey	任意	統計のグループ化ディメンション：ResourceType、RegionId、ResourceGroupId	なし
MaxResults	任意	ページネーション対応 API のページサイズ。	20

---

3. RAM ポリシー

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

推奨されるシステムポリシー：

• 読み取り専用：AliyunResourceCenterReadOnlyAccess
• フルアクセス：AliyunResourceCenterFullAccess

Resource Center を開くと、サービスリンクロール AliyunServiceRoleForResourceMetaCenter が自動的に作成されます。

リソースの可視範囲

RAM ポリシー（ram-policies.md で定義）は、ユーザーが Resource Center API を呼び出せるかどうかを制御します。ただし、検索 API（SearchResources、GetResourceCounts、GetResourceConfiguration、SearchMultiAccountResources、GetMultiAccountResourceCounts、GetMultiAccountResourceConfiguration）では、検索結果に表示されるリソースの範囲は、各クラウド製品固有の権限によって決まります。

単一アカウント

• クラウドリソースの読み取り権限：RAM ユーザーが Resource Center で確認できるのは、対応するクラウド製品で読み取り専用アクセス権を持つリソースのみです。たとえば、ReadOnlyAccess を付与すると、アクセス権のあるすべてのリソースを確認できます。AliyunVPCReadOnlyAccess のみを付与すると、表示範囲は VPC リソースに限定されます。
• リソースグループを対象とする権限：リソースがリソースグループに整理されている場合、特定のリソースグループに限定した読み取りアクセス権を RAM ユーザーに付与できます。ユーザーにはそのグループ内のリソースのみが表示されるため、リソースを分離できます。

クロスアカウント

• クロスアカウントでリソースを検索できるようにするには、Resource Directory 管理アカウントの RAM ユーザーにシステムポリシー AliyunResourceCenterFullAccess を付与します。

---

4. コアワークフロー

ステップ 1：ユーザーの要件に基づいて API を特定する

ユーザーの具体的なシナリオに基づいて、必要な API を判断します。以下のシナリオカードを参照してください。

ステップ 2：［必須］ CLI を呼び出す前に、毎回 API ドキュメントを読む

重大な警告：references/related-apis.md で正確なパラメーター形式を確認する前に、aliyun resourcecenter コマンドを実行しないでください。

失敗パターン：--filter の形式などを推測すると、エラーになります。正しい JSON 構造は、ドキュメントから必ずコピーしてください。

必須の操作：CLI コマンドを作成する前に、references/related-apis.md の該当する API のセクションを開いて読みます。

---

シナリオカード

シナリオ 1：サービスの有効化

要件	アカウント種別	API	説明
有効かどうかを確認	単一アカウント	get-resource-center-service-status	サービスのステータスを返します
サービスを有効化	単一アカウント	enable-resource-center	初回利用時に必要です
クロスアカウントのステータスを確認	Resource Directory	get-multi-account-resource-center-service-status	マルチアカウントのシナリオ
クロスアカウントサービスを有効化	Resource Directory	enable-multi-account-resource-center	管理アカウントまたは委任管理者が必要です

---

シナリオ 2：ResourceType の検出

要件	アカウント種別	スクリプト	説明
キーワードでリソースタイプコードを検索	単一アカウント	scripts/query-resource-types.py	ResourceType、ProductName、ResourceTypeName の各フィールドを検索します

判断ロジック：

• リソースタイプで絞り込みたいものの、正確なコードがわからない場合 → 最初にこのスクリプトを使用します
• 正しい ResourceType コードがわかったら → 検索 API または件数取得 API で --filter パラメーターを指定して使用します

---

シナリオ 3：リソース検索

要件	アカウント範囲	API	主なパラメーター
条件に基づいてリソースを検索	現在のアカウント	search-resources	--filter
クロスアカウントのリソースを検索	Resource Directory	search-multi-account-resources	--scope + --filter
削除済みリソースを含めて検索	現在のアカウント	search-resources	--include-deleted-resources=true

シナリオ 4：リソースの詳細を表示する

要件	アカウントの範囲	API	ユースケース
単一リソースの設定を取得する	現在のアカウント	get-resource-configuration	設定の詳細をすべて取得する
複数リソースの設定を一括取得する	現在のアカウント	batch-get-resource-configurations	複数のリソースを一度に取得する
別のアカウントのリソース設定を取得する	リソースディレクトリ	get-multi-account-resource-configuration	アカウント間で表示する

---

シナリオ 5：統計と分析

要件	アカウントの範囲	API	グループ化のディメンション
リソース数をカウントする	現在のアカウント	get-resource-counts	ResourceType、RegionId、ResourceGroupId
アカウント間の統計	リソースディレクトリ	get-multi-account-resource-counts	ResourceType、RegionId、ResourceGroupId

---

シナリオ 6：タグの確認

要件	アカウントの範囲	API	説明
すべてのタグキーを一覧表示する	現在のアカウント	list-tag-keys	タグカタログを確認する
特定のタグキーの値を一覧表示する	現在のアカウント	list-tag-values	例：env のすべての値を一覧表示する
アカウント間のタグキー	リソースディレクトリ	list-multi-account-tag-keys	マルチアカウントのシナリオ
アカウント間のタグ値	リソースディレクトリ	list-multi-account-tag-values	マルチアカウントのシナリオ

---

5. 成功の確認

各ワークフローステップの詳細な確認手順とコマンドについては、references/verification-method.md を参照してください。

---

6. 注意事項

[MUST] 高リスク操作の確認 — disable-resource-center または disable-multi-account-resource-center を実行する前に、次の対応が必要です。

1. 影響についてユーザーに明確に伝える必要があります。

• 無効化による影響
  • Resource Center を無効にすると、Resource Center でリソースデータを表示できなくなります。具体的には、次のとおりです。
    • 単一の Alibaba Cloud アカウントで Resource Center を無効にすると、現在のアカウントのリソースデータを表示できなくなります。
    • Resource Directory の管理アカウントおよび Resource Center の委任管理者アカウントで Resource Center を無効にすると、アカウント間のリソース検索機能も無効になります。現在のアカウントと Resource Directory のメンバーのリソースデータを表示できなくなります。また、メンバーは自身のアカウントのリソースデータも表示できなくなります。
    • Resource Center を無効にすると、コンソールのホームページにあるリソース管理モジュール、Config Audit サービス、その他の関連シナリオでもリソースデータを表示できなくなります。
• 無効化の制限
  • Resource Directory の管理アカウントまたは Resource Center の委任管理者アカウントで、別のアカウントによってアカウント間のリソース機能が有効になっている場合、Resource Center を無効にすることはできません。
  • Config Audit や関連するリソース転送など、Resource Center に強く依存するクラウド製品または機能がある場合は、Resource Center を無効にする前に、それらのクラウド製品または機能を無効にする必要があります。

2. ユーザーから明示的な確認を得る必要があります（例：「confirm disable」と入力する、または同等の明確な肯定を示す）。
3. ユーザーの明示的な承認なしに続行してはいけません。

Resource Center を無効にする

警告： 無効にすると、すべてのリソースデータが削除され、依存するサービス（例：Config Audit）に影響します。アカウント間機能が有効な場合は、まず無効にする必要があります。

aliyun resourcecenter disable-resource-center \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-resourcecenter-search

アカウント間の Resource Center を無効にする

単一アカウントの Resource Center を無効にする前に実行する必要があります（アカウント間機能が有効な場合）。管理アカウントまたは委任管理者が必要です。

aliyun resourcecenter disable-multi-account-resource-center \
  --user-agent AlibabaCloud-Agent-Skills/alibabacloud-resourcecenter-search

---

7. ベストプラクティス

1. すべての Resource Center CLI 呼び出しに --user-agent を付ける — このスキルの aliyun resourcecenter の例にはすべて --user-agent AlibabaCloud-Agent-Skills/alibabacloud-resourcecenter-search が含まれています。このスキルのコマンドを実行するときは、使用状況を検証時やメンテナーの期待、各種自動チェックと一致させるため、必ず同じフラグを指定してください。
2. 対象を絞り込む検索にはフィルターを使う — ResourceType、RegionId、Tag の各フィルターを組み合わせると、検索効率が向上します。
3. 手早く統計を取得するには GroupByKey を使う — リソースを反復処理せずに、タイプ、リージョン、リソースグループごとの分布を取得できます。
4. クロスアカウントのスコープ選択 — 検索結果を絞り込むには、最も具体的なスコープ（メンバー ID > フォルダー ID > ルートフォルダー ID > ディレクトリ ID）を使います。
5. 有効化後は待機する — Resource Center は有効化後、データの構築に数分かかります。大規模アカウントでは、さらに時間がかかる場合があります。
6. 読み取り専用ポリシーを優先する — 日常的な検索や統計操作には、セキュリティ確保のため AliyunResourceCenterReadOnlyAccess を使います。
7. ResourceType の特定 — 正確なリソースタイプコードが不明な場合は、セクション 8 に記載されているヘルパースクリプトを使います（スキルのルートディレクトリから実行してください）。
8. タグの調査とタグで絞り込んだ検索 — 「どのようなタグキー／値があるか」を調べるには、list-tag-keys／list-tag-values（および --scope を使うマルチアカウント版）を使います。タグ条件に一致するリソースを探す場合に限り、search-resources を使います。

---

8. 利用可能なスクリプト

スクリプト	目的	使用方法
scripts/query-resource-types.py	Alibaba Cloud Resource Center からキーワードでリソースタイプを検索します。標準出力は JSON です（resourceTypes、count、keyword、language。失敗時は success: false と error を使用）	python3 scripts/query-resource-types.py <keyword> [--language LANGUAGE]

---

9. トラブルシューティング

Resource Center API 呼び出しまたは aliyun resourcecenter コマンドが失敗した場合は、レスポンスの HTTP ステータス、Code（エラーコード）、Message を確認し、カタログと照合してください。

エラーの全リスト： references/error-codes.md

---

10. 参考リンク

参考資料	説明
references/related-apis.md	すべての CLI コマンドの一覧
references/ram-policies.md	RAM 権限ポリシー
references/verification-method.md	各ワークフローの検証手順
references/error-codes.md	重複を除いた Resource Center API エラーコードカタログ（HTTP、Code、Message）と検索のヒント
references/cli-installation-guide.md	Aliyun CLI のインストールガイド
references/acceptance-criteria.md	メンテナー／CI 専用：スキルのテスト受け入れ基準、正しい CLI コマンドパターン、パラメーター検証ルール。注： このドキュメントは人間のメンテナーと自動テストを対象としており、エンドユーザーが読む必要はありません。