AWS CLI 实战：使用aws cloudfront get-distribution查询 CloudFront 分发配置与 ETag
【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli
get-distribution是 AWS CLI 中用于查询单个 CloudFront 分发（distribution）完整信息的核心命令，它返回分发的基础元数据（ID、ARN、状态、域名）以及完整的DistributionConfig配置结构，同时通过响应头返回用于并发更新的ETag。本篇以 AWS CLI 仓库中 get-distribution.rst 官方示例为骨架，结合 service-2.json 服务模型与仓库内配套示例，逐字段讲解命令用法、输出含义、ETag 的实战价值，以及它与create-distribution、list-distributions、update-distribution等命令的协作关系，读完即可在真实环境中熟练查询与审计 CloudFront 分发。
get-distribution命令的作用与适用场景
CloudFront 是 AWS 的全球内容分发网络服务，一个"分发"（distribution）对应一套完整的加速配置：源站（origin）、默认缓存行为（default cache behavior）、TTL、价格分级、证书、地理限制等。当需要对已有分发进行状态审计、配置核对、或为后续修改做准备时，就需要把该分发的当前配置完整读取出来。
get-distribution正是为此设计的只读查询操作，它有两个不可替代的价值：
- 返回分发的完整配置快照：包括
Status（是否已部署到全部边缘节点）、DomainName（分配的加速域名）、LastModifiedTime、以及完整的DistributionConfig配置对象； - 返回当前版本的
ETag：这是后续执行update-distribution、delete-distribution等写操作时必须携带的并发控制令牌，防止基于过期配置进行覆盖式修改。
在 AWS CLI 仓库的 CloudFront 示例集中，官方给出了多条配套示例，共同构成"创建 → 查询 → 修改 → 删除"的完整操作链：
- create-distribution.rst：创建分发，返回新分发的 ID 与 ETag；
- list-distributions.rst：列出账号下所有分发的摘要信息；
- get-distribution-config.rst：仅返回配置对象（不含分发级元数据）；
- update-distribution.rst：修改分发，必须携带
--if-match传入最新 ETag。
命令语法与参数详解
根据 service-2.json 中GetDistribution操作的输入定义（shapeGetDistributionRequest），该命令只有一个必填参数：
| 参数 | 是否必填 | 说明 |
|---|---|---|
--id | 必填 | 分发的 ID（形如EDFDVBD6EXAMPLE）。该 ID 来自create-distribution或list-distributions的返回结果。 |
从服务模型看，Id字段通过"location": "uri"注入到请求 URL 路径中，因此它属于 REST 风格接口的路径参数，必须在命令行中显式给出。此外，命令还支持 AWS CLI 的通用参数，例如：
--output json：以 JSON 格式输出（默认）；--query 'Distribution.DistributionConfig.DefaultCacheBehavior.DefaultTTL'：仅提取某个字段；--region/--profile：指定区域或凭证配置文件。
该操作的响应结构（shapeGetDistributionResult）包含两个成员：Distribution（分发完整信息）和ETag（从 HTTP 响应头ETag解析而来，模型中标注为"location": "header"）。
官方示例与完整输出解读
仓库文档 get-distribution.rst 给出的核心命令如下：
aws cloudfront get-distribution \ --id EDFDVBD6EXAMPLE其中EDFVBD6EXAMPLE是示例分发 ID（文档中注释说明：该 ID 由create-distribution和list-distributions命令返回）。命令输出如下（原样继承官方示例）：
{ "ETag": "E2QWRUHEXAMPLE", "Distribution": { "Id": "EDFVBD6EXAMPLE", "ARN": "arn:aws:cloudfront::123456789012:distribution/EDFVBD6EXAMPLE", "Status": "Deployed", "LastModifiedTime": "2019-12-04T23:35:41.433Z", "InProgressInvalidationBatches": 0, "DomainName": "d111111abcdef8.cloudfront.net", "ActiveTrustedSigners": { "Enabled": false, "Quantity": 0 }, "DistributionConfig": { "CallerReference": "cli-example", "Aliases": { "Quantity": 0 }, "DefaultRootObject": "index.html", "Origins": { "Quantity": 1, "Items": [ { "Id": "amzn-s3-demo-bucket.s3.amazonaws.com-cli-example", "DomainName": "amzn-s3-demo-bucket.s3.amazonaws.com", "OriginPath": "", "CustomHeaders": { "Quantity": 0 }, "S3OriginConfig": { "OriginAccessIdentity": "" } } ] }, "OriginGroups": { "Quantity": 0 }, "DefaultCacheBehavior": { "TargetOriginId": "amzn-s3-demo-bucket.s3.amazonaws.com-cli-example", "ForwardedValues": { "QueryString": false, "Cookies": { "Forward": "none" }, "Headers": { "Quantity": 0 }, "QueryStringCacheKeys": { "Quantity": 0 } }, "TrustedSigners": { "Enabled": false, "Quantity": 0 }, "ViewerProtocolPolicy": "allow-all", "MinTTL": 0, "AllowedMethods": { "Quantity": 2, "Items": [ "HEAD", "GET" ], "CachedMethods": { "Quantity": 2, "Items": [ "HEAD", "GET" ] } }, "SmoothStreaming": false, "DefaultTTL": 86400, "MaxTTL": 31536000, "Compress": false, "LambdaFunctionAssociations": { "Quantity": 0 }, "FieldLevelEncryptionId": "" }, "CacheBehaviors": { "Quantity": 0 }, "CustomErrorResponses": { "Quantity": 0 }, "Comment": "", "Logging": { "Enabled": false, "IncludeCookies": false, "Bucket": "", "Prefix": "" }, "PriceClass": "PriceClass_All", "Enabled": true, "ViewerCertificate": { "CloudFrontDefaultCertificate": true, "MinimumProtocolVersion": "TLSv1", "CertificateSource": "cloudfront" }, "Restrictions": { "GeoRestriction": { "RestrictionType": "none", "Quantity": 0 } }, "WebACLId": "", "HttpVersion": "http2", "IsIPV6Enabled": true } } }分发级字段（Distribution）逐一解读
Distribution结构在 service-2.json 中被标记为必填的成员包括：Id、ARN、Status、LastModifiedTime、InProgressInvalidationBatches、DomainName、DistributionConfig，即每次查询都保证返回这些字段。
| 字段 | 含义 |
|---|---|
Id | 分发的唯一标识符，如EDFVBD6EXAMPLE；也是get-distribution的--id输入值。 |
ARN | 分发的 Amazon 资源名称，形如arn:aws:cloudfront::123456789012:distribution/EDFVBD6EXAMPLE，用于 IAM 策略授权与资源引用。 |
Status | 分发状态。当为Deployed时，表示分发信息已完全传播到所有 CloudFront 边缘节点（edge locations）；刚创建时为InProgress。 |
LastModifiedTime | 分发的最后修改时间（ISO 8601 时间戳）。 |
InProgressInvalidationBatches | 当前正在进行中的失效（invalidation）批次数量。 |
DomainName | CloudFront 分配的加速域名，形如d111111abcdef8.cloudfront.net，这是面向终端用户的访问入口。 |
ActiveTrustedSigners | 可用于签名 URL / 签名 Cookie 校验的 AWS 账户与 CloudFront 密钥对列表（服务模型提示：官方推荐使用TrustedKeyGroups取代TrustedSigners）。 |
DistributionConfig | 分发的完整配置对象，见下一节。 |
核心配置对象 DistributionConfig 深度解析
DistributionConfig是查询结果中最有分析价值的部分，它完整记录了该分发"是怎么配置的"。服务模型将其CallerReference、Origins、DefaultCacheBehavior、Comment、Enabled标记为必填。结合官方示例输出，各字段要点如下：
基础标识
CallerReference（cli-example）：创建分发时提供的唯一字符串，用于防止请求重放；若重复使用相同值创建，CloudFront 会返回DistributionAlreadyExists错误。Aliases：CNAME 别名（自定义域名）列表，示例中数量为 0，表示未绑定自定义域名，直接使用 CloudFront 默认域名。DefaultRootObject（index.html）：访问根路径https://<domain>/时，CloudFront 从源站请求的默认对象，可避免直接暴露源站目录结构。
源站（Origins）
Quantity/Items：源站数量与列表。示例为一个 S3 源站，Id与DomainName为amzn-s3-demo-bucket.s3.amazonaws.com。OriginPath：空字符串表示未设置源路径前缀。S3OriginConfig.OriginAccessIdentity：空字符串表示未配置源访问身份（OAI）；在较新的 API 版本中，还可能出现OriginAccessControlId（OAC）字段，见 list-distributions.rst 示例输出。OriginGroups：源站组（用于故障转移），示例为 0。
默认缓存行为（DefaultCacheBehavior）
TargetOriginId：指向Origins.Items中某个源站的 Id。ForwardedValues：转发给源站的查询字符串（QueryString: false）、Cookie（Forward: "none"）、请求头（Headers.Quantity: 0）与缓存键查询参数（QueryStringCacheKeys.Quantity: 0）。ViewerProtocolPolicy：allow-all表示允许 HTTP 与 HTTPS 访问；可选值还有redirect-to-https与https-only。MinTTL（0 秒）、DefaultTTL（86400 秒）、MaxTTL（31536000 秒）：对象在边缘节点的缓存时长范围。AllowedMethods：允许的请求方法，示例为HEAD、GET，其中CachedMethods同样为HEAD、GET（表示这两个方法的结果会被缓存）。SmoothStreaming、Compress：是否启用平滑流式处理与自动压缩，示例均为false。LambdaFunctionAssociations、FieldLevelEncryptionId：边缘函数（Lambda@Edge）关联与字段级加密 ID，示例为空/0。
安全与合规
ViewerCertificate：示例使用CloudFrontDefaultCertificate: true（默认证书），MinimumProtocolVersion为TLSv1，CertificateSource为cloudfront；若绑定了 ACM 证书，该结构会变为ACMCertificateArn、SSLSupportMethod、CertificateSource: "acm"等形式（参见 create-distribution.rst 示例 3）。Restrictions.GeoRestriction：地理限制，示例RestrictionType: "none"、数量 0，表示不限制访问地区。WebACLId：关联的 AWS WAF Web ACL ID，空字符串表示未关联。HttpVersion（http2）、IsIPV6Enabled（true）：协议版本与 IPv6 支持。PriceClass（PriceClass_All）：价格分级，决定使用全部还是部分边缘节点，影响成本。Logging：访问日志配置，示例为关闭状态。Enabled（true）：分发是否启用；设为false即停用分发（参考 update-distribution.rst 中的禁用示例）。
分发 ID 从哪来：与 create-distribution、list-distributions 的协作
原文档明确指出：分发 ID 由create-distribution和list-distributions命令返回。在实战中：
- 新创建分发后，从
create-distribution的返回结果中取Distribution.Id（如 create-distribution.rst 示例 1 中的EMLARXS9EXAMPLE）； - 管理存量分发时，直接执行
aws cloudfront list-distributions，从DistributionList.Items[].Id中筛选目标 ID，再将该 ID 传给get-distribution。
两命令示例均收录于仓库 awscli/examples/cloudfront 目录下，可对照阅读完整输出。
ETag 的实战价值：并发控制与安全更新
响应中的ETag（示例为E2QWRUHEXAMPLE）是该分发配置当前版本的标识，来自 HTTP 响应头（服务模型中标注"location": "header"）。它的核心用途是乐观并发控制（optimistic concurrency）：
- 更新分发前，先用
get-distribution（或get-distribution-config）拿到最新 ETag； - 在
update-distribution时通过--if-match传入该 ETag； - CloudFront 会比较传入值与服务端当前版本，若不一致则拒绝更新，避免多人操作时"后写覆盖先写"。
update-distribution.rst 第 141–142 行的说明与之一致："To update a distribution, you must use the--if-matchoption to provide the distribution'sETag. To get theETag, use theget-distributionorget-distribution-configcommand."（更新分发必须使用--if-match提供 ETag，而获取 ETag 正是get-distribution或get-distribution-config的职责。）
同样地，执行delete-distribution时通常也需要携带 ETag 以确认删除的是预期版本。因此可以说：每次安全的配置变更，都始于一次get-distribution。
源码级支撑：服务模型与 Waiter 机制
从当前仓库的服务定义文件 awscli/botocore/data/cloudfront/2020-05-31/service-2.json 可以确认：
GetDistribution操作（内部名称GetDistribution2020_05_31）文档描述为 "Get the information about a distribution"，输入 shapeGetDistributionRequest（必填Id），输出 shapeGetDistributionResult（Distribution+ETag），可能抛出的错误为NoSuchDistribution与AccessDenied；- 该操作不参与分页（无
paginated标记），因为它面向单个分发的完整读取。
更有意思的是，get-distribution还是 CloudFrontWaiter 机制的底层轮询操作。仓库 waiters-2.json 中定义的DistributionDeployedwaiter 配置为：
{ "description": "Wait until a distribution is deployed.", "delay": 60, "maxAttempts": 35, "operation": "GetDistribution", "acceptors": [ { "matcher": "path", "argument": "Distribution.Status", "state": "success", "expected": "Deployed" } ] }即在 CLI 中使用aws cloudfront wait distribution-deployed --id <ID>时，SDK 会每 60 秒调用一次GetDistribution，最多尝试 35 次，直到返回结果中Distribution.Status变为Deployed。这印证了get-distribution不仅是查询工具，也是自动化部署流程中的"就绪探测"原语——创建或更新分发后，可以用它驱动轮询等待部署完成。
常见错误与排查建议
NoSuchDistribution：--id指定的分发不存在（ID 拼写错误，或属于其他 AWS 账户/区域），请用list-distributions核对 ID；AccessDenied：当前凭证没有cloudfront:GetDistribution权限，需要在 IAM 策略中授予该操作（可结合返回的ARN字段对单个分发做资源级授权）；- 输出中没有
ETag：ETag来自响应头，使用--output json时会显示为顶层字段；若自定义了--query提取表达式，请勿遗漏该字段名。
延伸阅读
- 查询仅配置对象（不含分发级元数据）：get-distribution-config.rst
- 创建分发（命令行参数 / JSON 文件两种方式）：create-distribution.rst
- 列出账号下全部分发：
aws cloudfront list-distributions（示例见 list-distributions.rst） - 使用 ETag 安全更新分发：
aws cloudfront update-distribution --if-match <ETag> ...（示例见 update-distribution.rst） - 等待分发部署完成：
aws cloudfront wait distribution-deployed --id <ID> - 服务与 Waiter 模型定义：service-2.json、waiters-2.json
【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cli
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
