AWS CLI 实战：使用 `aws cloudfront get-distribution` 查询 CloudFront 分发配置与 ETag

AWS CLI 实战使用aws cloudfront get-distribution查询 CloudFront 分发配置与 ETag【免费下载链接】aws-cliUniversal Command Line Interface for Amazon Web Services项目地址: https://gitcode.com/GitHub_Trending/aw/aws-cliget-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 与 ETaglist-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批次数量。DomainNameCloudFront 分配的加速域名形如d111111abcdef8.cloudfront.net这是面向终端用户的访问入口。ActiveTrustedSigners可用于签名 URL / 签名 Cookie 校验的 AWS 账户与 CloudFront 密钥对列表服务模型提示官方推荐使用TrustedKeyGroups取代TrustedSigners。DistributionConfig分发的完整配置对象见下一节。核心配置对象 DistributionConfig 深度解析DistributionConfig是查询结果中最有分析价值的部分它完整记录了该分发是怎么配置的。服务模型将其CallerReference、Origins、DefaultCacheBehavior、Comment、Enabled标记为必填。结合官方示例输出各字段要点如下基础标识CallerReferencecli-example创建分发时提供的唯一字符串用于防止请求重放若重复使用相同值创建CloudFront 会返回DistributionAlreadyExists错误。AliasesCNAME 别名自定义域名列表示例中数量为 0表示未绑定自定义域名直接使用 CloudFront 默认域名。DefaultRootObjectindex.html访问根路径https://domain/时CloudFront 从源站请求的默认对象可避免直接暴露源站目录结构。源站OriginsQuantity/Items源站数量与列表。示例为一个 S3 源站Id与DomainName为amzn-s3-demo-bucket.s3.amazonaws.com。OriginPath空字符串表示未设置源路径前缀。S3OriginConfig.OriginAccessIdentity空字符串表示未配置源访问身份OAI在较新的 API 版本中还可能出现OriginAccessControlIdOAC字段见 list-distributions.rst 示例输出。OriginGroups源站组用于故障转移示例为 0。默认缓存行为DefaultCacheBehaviorTargetOriginId指向Origins.Items中某个源站的 Id。ForwardedValues转发给源站的查询字符串QueryString: false、CookieForward: none、请求头Headers.Quantity: 0与缓存键查询参数QueryStringCacheKeys.Quantity: 0。ViewerProtocolPolicyallow-all表示允许 HTTP 与 HTTPS 访问可选值还有redirect-to-https与https-only。MinTTL0 秒、DefaultTTL86400 秒、MaxTTL31536000 秒对象在边缘节点的缓存时长范围。AllowedMethods允许的请求方法示例为HEAD、GET其中CachedMethods同样为HEAD、GET表示这两个方法的结果会被缓存。SmoothStreaming、Compress是否启用平滑流式处理与自动压缩示例均为false。LambdaFunctionAssociations、FieldLevelEncryptionId边缘函数LambdaEdge关联与字段级加密 ID示例为空/0。安全与合规ViewerCertificate示例使用CloudFrontDefaultCertificate: true默认证书MinimumProtocolVersion为TLSv1CertificateSource为cloudfront若绑定了 ACM 证书该结构会变为ACMCertificateArn、SSLSupportMethod、CertificateSource: acm等形式参见 create-distribution.rst 示例 3。Restrictions.GeoRestriction地理限制示例RestrictionType: none、数量 0表示不限制访问地区。WebACLId关联的 AWS WAF Web ACL ID空字符串表示未关联。HttpVersionhttp2、IsIPV6Enabledtrue协议版本与 IPv6 支持。PriceClassPriceClass_All价格分级决定使用全部还是部分边缘节点影响成本。Logging访问日志配置示例为关闭状态。Enabledtrue分发是否启用设为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传入该 ETagCloudFront 会比较传入值与服务端当前版本若不一致则拒绝更新避免多人操作时后写覆盖先写。update-distribution.rst 第 141–142 行的说明与之一致To update a distribution, you must use the--if-matchoption to provide the distributionsETag. 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输出 shapeGetDistributionResultDistributionETag可能抛出的错误为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核对 IDAccessDenied当前凭证没有cloudfront:GetDistribution权限需要在 IAM 策略中授予该操作可结合返回的ARN字段对单个分发做资源级授权输出中没有ETagETag来自响应头使用--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），仅供参考