alibabacloud-resourcecenter-search

1. 前置条件

[MUST] CLI User-Agent — 每次调用 aliyun CLI 命令都必须包含： --user-agent AlibabaCloud-Agent-Skills/alibabacloud-resourcecenter-search

[MUST] 启用 AI-Mode — 执行 Agent Skill 必须启用 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 身份）。

如果不存在有效配置，请在此处停止。

1. 从 Alibaba Cloud 控制台获取凭证
2. 在本会话之外配置凭证（通过终端中的 aliyun configure，或在 shell 配置文件中设置环境变量）
3. 返回后重新运行，并确认 aliyun configure list 显示有效配置

[MUST] 在每个退出点禁用 AI-Mode — 无论出于何种原因，在给出最终答复之前，都必须先禁用 AI-mode。适用于所有退出路径：工作流成功、工作流失败、错误/异常、用户取消、会话结束，或任何不会再执行 CLI 命令的情况。 AI-mode 仅用于调用 Agent Skill 的场景，Skill 停止运行后绝不能保持启用状态。

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	可选	交换机（例如，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）用于控制用户能否调用资源中心 API。不过，对于搜索 API（SearchResources、GetResourceCounts、GetResourceConfiguration、SearchMultiAccountResources、GetMultiAccountResourceCounts、GetMultiAccountResourceConfiguration），结果中可见资源的范围由各云产品自身的权限决定：

单账号

• 云资源读取权限：RAM 用户只能在资源中心查看其在相应云产品中拥有只读权限的资源。例如，授予 ReadOnlyAccess 后，用户可以查看其有权访问的所有资源；仅授予 AliyunVPCReadOnlyAccess 则会将可见范围限制为 VPC 资源。
• 资源组范围权限：如果资源按资源组组织，你可以授予 RAM 用户特定资源组范围内的读取权限。用户只能查看该资源组内的资源，从而实现资源隔离。

跨账号

• 向资源目录管理账号的 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	首次使用时需要
检查跨账号状态	资源目录	get-multi-account-resource-center-service-status	多账号场景
启用跨账号服务	资源目录	enable-multi-account-resource-center	需要管理账号或委派管理员

---

场景 2：发现资源类型

需求	账号类型	脚本	说明
按关键词查找资源类型代码	单账号	scripts/query-resource-types.py	搜索 ResourceType、ProductName 和 ResourceTypeName 字段

决策逻辑：

• 当你需要按资源类型筛选，但不知道确切代码时 -> 先使用此脚本
• 找到正确的 ResourceType 代码后 -> 在搜索或计数 API 中使用 --filter 参数

---

场景 3：资源搜索

需求	账号范围	API	关键参数
按条件搜索资源	当前账号	search-resources	--filter
跨账号资源搜索	资源目录	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. 必须明确告知用户相关影响：

• 禁用影响
  • 禁用资源中心后，将无法再在资源中心查看资源数据。具体而言：
    • 对于单个阿里云账号，禁用资源中心后，将无法再查看当前账号中的资源数据。
    • 对于资源目录的管理账号和资源中心的委派管理员账号，禁用资源中心也会关闭跨账号资源搜索功能。将无法再查看当前账号及资源目录成员的资源数据。此外，成员也无法查看其自身账号中的资源数据。
    • 禁用资源中心后，控制台首页的资源管理模块、配置审计服务及其他相关场景也将无法查看资源数据。
• 禁用限制
  • 如果资源目录的管理账号或资源中心的委派管理员账号已被其他账号启用跨账号资源功能，则无法禁用资源中心。
  • 如果有强依赖资源中心的云产品或功能，例如配置审计及关联资源转投，则必须先禁用这些云产品或功能，才能禁用资源中心。

2. 必须获得用户明确确认（例如，用户输入“确认禁用”或其他清晰的确认表述）
3. 未经用户明确确认，不得继续操作

禁用资源中心

**警告：**禁用将删除所有资源数据，并影响依赖服务（例如配置审计）。如果已启用跨账号功能，必须先将其禁用。

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

禁用跨账号资源中心

如果已启用跨账号功能，必须在禁用单账号资源中心前完成此操作。需要管理账号或委派管理员账号。

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

---

7. 最佳实践

1. 每次调用资源中心 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. 启用后等待 — 资源中心激活后需要几分钟来构建数据；大型账号可能需要更长时间
6. 优先使用只读策略 — 对于日常搜索和统计操作，请使用 AliyunResourceCenterReadOnlyAccess 以确保安全
7. 发现 ResourceType — 如果不知道确切的资源类型代码，请使用 第 8 节中说明的辅助脚本（从技能根目录运行）。
8. 发现标签与按标签筛选搜索 — 若要了解“存在哪些标签键/值”，请使用 list-tag-keys / list-tag-values（以及带有 --scope 的多账号变体）。仅在查找符合标签条件的资源时使用 search-resources。

---

8. 可用脚本

脚本	用途	用法
scripts/query-resource-types.py	按关键字查询 Alibaba Cloud 资源中心中的资源类型；标准输出为 JSON（resourceTypes、count、keyword、language；失败时使用 success: false 和 error）	python3 scripts/query-resource-types.py <keyword> [--language LANGUAGE]

---

9. 故障排除

当资源中心 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	去重后的资源中心 API 错误代码目录（HTTP、Code、Message）及查询提示
references/cli-installation-guide.md	Aliyun CLI 安装指南
references/acceptance-criteria.md	仅供维护者/CI 使用：技能测试验收标准、正确的 CLI 命令模式、参数验证规则。**注意：**本文档面向人工维护者和自动化测试，并非最终用户必读内容。