企业官网建设流程全解析

aws-cli CloudFormation list-types 命令详解：管理私有资源类型与扩展注册表

【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli

本文基于 AWS CLI（aws-cli 仓库）中的官方示例文档 awscli/examples/cloudformation/list-types.rst，系统讲解aws cloudformation list-types命令的完整用法。该命令用于查询 AWS CloudFormation Registry（扩展注册表）中当前账号可见的扩展类型，包括私有资源类型（Private Resource Type）、模块（Module）与钩子（Hook），以及公开展开（Public Extension）。阅读本文后，你将掌握list-types的基本用法、输出字段含义、常用筛选参数、分页技巧，并能结合仓库中的服务模型源码理解该命令的底层实现与参数约束。

一、命令概览：列出账号内的私有资源类型

list-types对应 CloudFormation 服务 API 的ListTypes操作。在 AWS CLI 中最直接的用法是不带任何参数，列出当前 AWS 账号当前区域中已注册的私有扩展。原文档给出的核心示例如下：

aws cloudformation list-types

输出示例（JSON 格式）：

{ "TypeSummaries": [ { "Description": "WordPress blog resource for internal use", "LastUpdated": "2019-12-04T18:28:15.059Z", "TypeName": "My::WordPress::BlogExample", "TypeArn": "arn:aws:cloudformation:us-west-2:123456789012:type/resource/My-WordPress-BlogExample", "DefaultVersionId": "00000005", "Type": "RESOURCE" }, { "Description": "Customized resource derived from AWS::Logs::LogGroup", "LastUpdated": "2019-12-04T18:28:15.059Z", "TypeName": "My::Logs::LogGroup", "TypeArn": "arn:aws:cloudformation:us-west-2:123456789012:type/resource/My-Logs-LogGroup", "DefaultVersionId": "00000003", "Type": "RESOURCE" } ] }

默认情况下，该命令只返回PRIVATE可见范围的扩展，即当前账号与区域中已注册的私有扩展，以及已激活（Activated）的公开展开。上面的示例展示了两个通过 CloudFormation CLI 开发并注册的私有资源类型，例如My::WordPress::BlogExample，其Type均为RESOURCE。

二、输出结构：TypeSummaries 字段详解

list-types的响应体固定为TypeSummaries数组，每一项是一个TypeSummary结构。结合 awscli/botocore/data/cloudformation/2010-05-15/service-2.json 中TypeSummary的定义，各字段含义如下：

其中DefaultVersionId、LastUpdated等字段在示例输出中的值（如00000005）表明这些类型曾多次注册新版本，DefaultVersionId指向当前默认使用的版本；可用SetTypeDefaultVersionAPI 修改默认版本。

三、核心筛选参数：Visibility、Type 与 ProvisioningType

list-types最常用的价值在于按需过滤扩展。从源码模型 ListTypesInput 的定义可以看到，请求参数包括：

Filters 复合过滤

--filters参数接受一个 JSON 结构（对应TypeFilters，见 service-2.json），支持三个子条件：

• Category：REGISTERED（本账号注册的私有扩展）、ACTIVATED（本账号激活的公开展开）、THIRD_PARTY（非 Amazon 发布者的扩展，含注册的私有扩展与第三方公开展开）、AWS_TYPES（Amazon 发布的扩展）；
• PublisherId：按第三方发布者 ID 过滤（AWS 官方扩展无 PublisherId，需用AWS_TYPES分类）；
• TypeNamePrefix：按类型名前缀过滤，例如My::。

需要注意兼容性约束：Filters必须与Visibility搭配合理才能返回有效结果。例如指定Category=AWS_TYPES且Visibility=PRIVATE会得到空列表，而Visibility=PUBLIC才能返回期望的 AWS 官方类型列表（该约束在Filters参数的源码文档中有明确说明，见 service-2.json）。

四、实战示例：常用过滤组合

1. 列出账号内所有已注册的私有资源类型

aws cloudformation list-types \ --visibility PRIVATE \ --type RESOURCE

2. 只查看已弃用的私有扩展

aws cloudformation list-types \ --deprecated-status DEPRECATED

3. 按类型名前缀过滤（如自定义组织前缀）

aws cloudformation list-types \ --filters '{"TypeNamePrefix": "My::"}'

4. 按发布者分类过滤，例如仅查看 AWS 官方类型

aws cloudformation list-types \ --visibility PUBLIC \ --filters '{"Category": "AWS_TYPES"}'

5. 查看第三方公开展开

aws cloudformation list-types \ --visibility PUBLIC \ --filters '{"Category": "THIRD_PARTY"}'

6. 限制单页返回数量并使用分页

aws cloudformation list-types --max-results 10 # 使用返回的 NextToken 获取下一页 aws cloudformation list-types --max-results 10 --next-token "TOKEN_VALUE"

7. 使用 --output 与 --query 精简输出

在实际自动化中，常配合--query只提取关键信息，例如仅输出类型名与默认版本：

aws cloudformation list-types \ --query "TypeSummaries[].{Name:TypeName,Version:DefaultVersionId}" \ --output table

五、分页机制与自动化调用

ListTypes是支持分页的 API。在仓库的 paginators-1.json 中，其分页配置为：

"ListTypes": { "input_token": "NextToken", "output_token": "NextToken", "limit_key": "MaxResults", "result_key": "TypeSummaries" }

这意味着 AWS CLI 内置的分页器以NextToken作为输入/输出分页令牌，以MaxResults作为单页大小，结果聚合在TypeSummaries键下。因此可以直接使用--paginate选项自动遍历所有结果，无需手动处理令牌：

aws cloudformation list-types --paginate

在 Shell 脚本中也可以借助--no-paginate与--next-token手动实现循环：

TOKEN="" while :; do if [ -z "$TOKEN" ]; then RESP=$(aws cloudformation list-types --max-results 20) else RESP=$(aws cloudformation list-types --max-results 20 --next-token "$TOKEN") fi echo "$RESP" | jq -r '.TypeSummaries[].TypeName' TOKEN=$(echo "$RESP" | jq -r '.NextToken // empty') [ -z "$TOKEN" ] && break done

六、源码级原理：从服务模型看 ListTypes 操作

在 awscli/botocore/data/cloudformation/2010-05-15/service-2.json 中，ListTypes操作被定义为：

• HTTP 方法POST，请求路径/（CloudFormation 通过X-Amz-Target头路由到具体 API，此类操作在 SDK 模型中以 POST 根路径呈现）；
• 请求体为ListTypesInput，响应体为ListTypesOutput（resultWrapper为ListTypesResult）；
• 唯一错误类型为CFNRegistryException；
• 标记为idempotent（幂等），即重复调用不会产生副作用，适合在自动化脚本中反复查询。

该操作的官方语义是：返回所有扩展的摘要信息，包括账号内的私有资源类型、模块、Hooks，以及来自 AWS 和第三方发布者的公开展开。这正是文档示例中"列出私有资源类型"场景的 API 基础。

从TypeSummary的字段设计还可以推断，list-types是 CloudFormation Registry 管理链路中的"查询入口"，它与以下命令共同构成扩展生命周期管理：

• aws cloudformation register-type：注册扩展，使其可在本账号模板中使用（RegisterType）；
• aws cloudformation describe-type：查看单个扩展的详细信息；
• aws cloudformation set-type-default-version：设置默认版本；
• aws cloudformation deregister-type：注销扩展版本，注销后扩展进入DEPRECATED状态，可通过--deprecated-status DEPRECATED查询；
• aws cloudformation list-type-versions：列出某一扩展的所有版本（对应ListTypeVersions操作，定义在 service-2.json）。

七、使用注意事项

1. 区域隔离：list-types的结果是账号 + 区域维度的。私有扩展只在本注册区域可见，切换区域查询前需注意--region参数；
2. 默认可见范围：不带任何参数时只返回PRIVATE范围；要查看公开展开必须显式指定--visibility PUBLIC；
3. 过滤条件兼容性：Filters.Category与Visibility组合不当会返回空列表，如AWS_TYPES必须配合PUBLIC使用；
4. 默认版本与描述字段：DefaultVersionId、LastUpdated等字段仅对私有扩展（或激活且开启自动更新的公开展开）非空，查询公开展开时这些字段通常为null；
5. 权限要求：该操作依赖 CloudFormation 的读取权限，调用身份需具备对应的 IAM 策略（如cloudformation:ListTypes）才能成功执行。

八、小结

aws cloudformation list-types是管理 CloudFormation Registry 最常用的查询命令：一条不带参数的调用即可快速掌握账号内注册了哪些私有资源类型及其默认版本；配合--visibility、--type、--filters等参数，可以精准定位资源类型、模块、Hooks 与各类公开展开；借助--paginate或手动NextToken循环可在大规模账号中可靠地遍历全部类型。结合 service-2.json 与 paginators-1.json 中的模型定义，开发者可以进一步理解该命令的参数边界与分页行为，将其稳定地集成进 IaC 治理与扩展审计脚本中。

【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli