Amazon CloudFront
开发人员指南 (API 版本 2016-09-29)
AWS 文档中描述的 AWS 服务或功能可能因区域而异。要查看适用于中国区域的差异,请参阅中国的 AWS 服务入门

使文件失效

如果您需要在文件过期前从 CloudFront 边缘缓存中删除文件,可以执行下列操作之一:

  • 通过边缘缓存使文件失效。查看器下次请求文件时,CloudFront 将返回源以获取文件的最新版本。

  • 使用文件版本控制以提供具有不同名称的文件的不同版本。有关更多信息,请参阅使用版本控制的文件名更新现有文件

重要

您不能使 RTMP 分配提供的对象失效。

要使文件失效,您可以指定单独文件的路径或以 * 通配符结尾的路径,后者可能会应用到一个或多个文件,如以下示例中所示:

  • /images/image1.jpg

  • /images/image*

  • /images/*

注意

如果您使用 AWS 命令行界面 (CLI) 使文件失效,并且您指定一个包含 * 通配符的路径,则必须使用引号 (") 将路径引起来。

例如:aws cloudfront create-invalidation --distribution-id $CDN_DISTRIBUTION_ID --paths "/*"

您每月可免费提交指定数量的失效路径。如果您提交的数量超过了该月中分配的失效路径数,则需要为提交的每个失效路径支付费用。有关使用失效费用的更多信息,请参阅 支付文件失效费用

在使文件失效和使用版本控制的文件名之间进行选择

要控制从分配提供的文件版本,您可使文件失效或使用版本控制文件名为其命名。如果您希望频繁地更新文件,出于以下原因,我们建议您主要使用文件版本控制:

  • 即使用户在本地或企业缓存代理中缓存了文件的版本,版本控制也使您能够控制为请求返回哪个文件。如果您使文件失效,用户看到的可能继续是旧版本直至它从这些缓存中过期。

  • CloudFront 访问日志包括文件的名称,因此,版本控制使分析文件更改的结果变得更加轻松。

  • 版本控制提供一种将不同版本的文件提供给不同用户的方式。

  • 版本控制简化了文件修订之间的向前和向后滚动。

  • 版本控制更便宜。您仍需为 CloudFront 支付费用以将文件的新版本传输到边缘站点,但您不必为使文件失效支付费用。

有关文件版本控制的更多信息,请参阅使用版本控制的文件名更新现有文件

确定使哪个文件失效

如果您要使多个文件失效,例如某个目录中的所有文件或者名称以相同字符开头的所有文件,您可以在失效路径的结尾包含 * 通配符。有关使用 * 通配符的更多信息,请参阅 失效路径

如果您想使选定文件失效但用户不必访问源上的每个文件,您可确定查看器从 CloudFront 请求了哪些文件并只使这些文件失效。要决定查看器已经请求的文件,启用 CloudFront 访问日志记录。有关访问日志的更多信息,请参阅 配置和使用访问日志

指定要失效的文件

无论您使用 CloudFront 控制台还是 CloudFront API 以使文件失效,用于指定文件的要求和限制是相同的。请注意以下有关指定要失效文件的信息。

区分大小写

失效路径区分大小写,因此,/images/image.jpg/images/Image.jpg 指定了两个不同的文件。

使用 Lambda 函数更改 URI

如果您的 CloudFront 分配在发生查看器请求事件时触发 Lambda 函数,并且该函数更改请求的文件的 URI,您必须使这两个 URI 失效才能从 CloudFront 边缘缓存中删除该文件:

  • 查看器请求中的 URI

  • 函数进行更改后的 URI

例如,假设您的 Lambda 函数将文件的 URI 从以下 URI:

http://d111111abcdef8.cloudfront.net/index.html

更改为包含语言目录的 URI:

http://d111111abcdef8.cloudfront.net/en/index.html

要使文件失效,您必须指定以下路径:

  • index.html

  • en/index.html

有关更多信息,请参阅失效路径

默认根对象

要使默认根对象(文件)失效,请以您为任何其他文件指定路径相同的方式指定路径。

分配类型

您只能使与 Web 分配相关的文件失效。

转发 Cookie

如果配置 CloudFront 以将 Cookie 转发到源,CloudFront 边缘缓存可能会包含文件的多个版本。当您使文件失效之后,CloudFront 会使文件的所有缓存版本失效,不论其关联的 Cookie 如何。您无法根据关联的 Cookie 选择性地使一些版本失效,而使另一些版本不失效。有关更多信息,请参阅根据 Cookie 缓存内容

转发标头

如果配置 CloudFront 以将标头白名单转发到源并根据标头值进行缓存,CloudFront 边缘缓存可能会包含文件的多个版本。当您使文件失效之后,CloudFront 会使文件的所有缓存版本失效,而不论标头值如何。您无法根据标头值选择性地使一些版本失效,而使另一些版本不失效。(如果配置 CloudFront 以将所有标头转发到源,CloudFront 不会缓存您的文件。) 有关更多信息,请参阅根据请求标头缓存内容

转发查询字符串

如果您将 CloudFront 配置为将查询字符串转发到源,在使文件失效时,您必须包括查询字符串,如下例中所示:

  • images/image.jpg?parameter1=a

  • images/image.jpg?parameter1=b

如果客户端请求包括针对同一个文件的五个不同查询字符串,您可以使文件失效五次(每个查询字符串一次),或者您可以在失效路径中使用 * 通配符,如下例中所示:

/images/image.jpg*

有关在失效路径中使用通配符的更多信息,请参阅 失效路径。有关查询字符串的更多信息,请参阅 根据查询字符串参数缓存内容。要确定哪个查询字符串正在使用中,您可启用 CloudFront 日志记录。有关更多信息,请参阅配置和使用访问日志

限制

有关失效的限制信息,请参阅 并发失效请求限制

Microsoft 平滑流文件

为对应的缓存行为启用了平滑流时,您不能使 Microsoft 平滑流格式的媒体文件失效。

路径中的非 ASCII 或不安全字符

如果路径包括非 ASCII 字符或 RFC 1783 (http://www.ietf.org/rfc/rfc1738.txt) 中定义的不安全字符,则对这些字符进行 URL 编码。切勿对路径中的任何其他字符进行 URL 编码,否则,CloudFront 将不会使已更新文件的旧版本失效。

失效路径

路径是相对于分配的。前倒斜杠是可选的。例如,要使 http://d111111abcdef8.cloudfront.net/images/image2.jpg 处的文件失效,您可指定以下内容:

/images/image2.jpg

images/image2.jpg

您还可以使用 * 通配符使多个文件同时失效。* 将替换 0 个或多个字符,必须是失效路径中最后的字符。如果您使用 AWS 命令行界面 (CLI) 使文本失效,并且您指定一个包含 * 通配符的路径,则必须使用引号 (") 将路径引起来(如 "/*")。

以下是一些示例:

  • 使目录中的所有文件失效:

    /directory-path/*

  • 使目录、其所有子目录以及该目录和子目录中的所有文件失效:

    /directory-path*

  • 使具有相同名称但文件扩展名不同的所有文件失效 (例如 logo.jpg、logo.png 和 logo.gif):

    /directory-path/file-name.*

  • 使目录中文件名以相同字符开头的所有文件失效 (例如 HLS 格式的视频的所有文件) 而不论扩展名如何:

    /directory-path/initial-characters-in-file-name*

  • 当您将 CloudFront 配置为根据查询字符串参数进行缓存并且希望使某个文件的所有版本失效时:

    /directory-path/file-name.file-name-extension*

  • 使分配中的所有文件失效:

    /*

路径的长度上限是 4000 个字符。您不能在路径内使用通配符;只能在路径终点处使用。

有关在使用 Lambda 函数更改 URI 时使文件失效的信息,请参阅使用 Lambda 函数更改 URI

不论您要使之失效的文件的数量是多少(单个文件 (/images/logo.jpg) 或是与分配关联的所有文件 (/*)),提交失效路径的费用均相同。有关更多信息,请参阅 Amazon CloudFront 定价

如果失效路径为目录,并且未标准化指定目录的方法(带或不带尾随斜杠 /),我们建议您使带和不带尾随斜杠的目录均失效,例如,/images/images/。——

签名 URL

如果您正在使用签名 URL,可以通过在问号 (?) 前仅包括部分 URL 来使文件失效。

使用控制台使文件失效

您可以使用 CloudFront 控制台来创建并运行失效、显示您先前提交的失效列表以及有关单个失效的详细信息。您还可复制现有的失效、编辑文件路径列表并运行已编辑的失效。您无法从列表中删除失效。

使文件失效

要使用 CloudFront 控制台使文件失效,请执行以下操作。

使文件失效

  1. 登录 AWS 管理控制台,通过以下网址打开 CloudFront 控制台:https://console.amazonaws.cn/cloudfront/

  2. 选择您想为其使文件失效的分配。

  3. 选择分配设置

  4. 选择失效选项卡。

  5. 选择创建失效

  6. 对于您希望使其失效的文件,请在每行输入一个失效路径。有关指定失效路径的信息,请参阅 指定要失效的文件

    重要

    请谨慎指定文件路径。在启动之后,您无法取消失效请求。

  7. 选择失效

复制、编辑及重新运行现有失效

您可复制您先前创建的失效、更新失效路径列表以及运行已更新的失效。您不可复制现有失效、更新失效路径,然后在不运行已更新失效的情况下将其保存。

重要

如果您复制仍在进行中的失效、更新失效路径列表,然后运行已更新的失效,则 CloudFront 不会停止或删除您复制的失效。如果任何失效路径出现在原本和副本中,CloudFront 将尝试使文件失效两次,且两次失效均计入到您每月免费失效的最大数目中。如果您已经达到了免费失效的最大数目,将会向您收取每个文件两次失效的费用。有关更多信息,请参阅 并发失效请求限制

复制、编辑及重新运行现有失效

  1. 登录 AWS 管理控制台,通过以下网址打开 CloudFront 控制台:https://console.amazonaws.cn/cloudfront/

  2. 选择分配,该分配包含您想复制的失效。

  3. 选择分配设置

  4. 选择失效选项卡。

  5. 选择您想复制的失效。

    如果您不确定想复制哪个失效,您可选择某个失效,然后选择 Details 以显示该失效的详细信息。

  6. 选择 Copy

  7. 更新失效路径列表 (如适用)。

  8. 选择失效

取消失效

在将失效请求提交到 CloudFront 时,CloudFront 在几秒钟内将该请求转发到所有边缘站点,并且每个边缘站点立即开始处理失效。因此,在提交之后,将无法取消失效。

列出失效

通过使用 CloudFront 控制台,您可显示您已为分配创建和运行的最后 100 个失效列表。如果您想获得超过 100 个失效的列表,使用 失效列表 API 操作。有关更多信息,请参阅 Amazon CloudFront API Reference 中的失效列表

列出失效

  1. 登录 AWS 管理控制台,通过以下网址打开 CloudFront 控制台:https://console.amazonaws.cn/cloudfront/

  2. 选择您想为其显示失效列表的分配。

  3. 选择分配设置

  4. 选择失效选项卡。

注意

您无法从列表中删除失效。

显示有关失效的信息

您可显示失效的详细信息,包括分配 ID、失效 ID、失效状态、创建失效的日期和时间以及完整的失效路径列表。

显示有关失效的信息

  1. 登录 AWS 管理控制台,通过以下网址打开 CloudFront 控制台:https://console.amazonaws.cn/cloudfront/

  2. 选择包含您要为其显示详细信息的失效的分配。

  3. 选择分配设置

  4. 选择失效选项卡。

  5. 选择适用的失效。

  6. 选择详细信息

使用 CloudFront API 使文件失效

有关使用 CloudFront API 使对象失效以及显示失效相关信息的信息,请参阅 Amazon CloudFront API Reference 中的以下主题:

使文件失效的第三方工具

除 CloudFront 提供的失效方法之外,一些第三方工具提供了使文件失效的方式。有关工具列表,请参阅 使对象失效

并发失效请求限制

如果您想逐个让文件失效,则针对每个分配一次可以同时处理 3000 个文件的无效请求。一个无效请求可以支持最多 3000 个文件,或针对一个文件的 3000 个请求,或者合计不超过 3000 个文件的任何组合方式。例如,您可以提交 30 个失效请求,每个请求使 100 个文件失效。只要全部 30 个失效请求仍在进行中,您无法继续提交任何失效请求。如果您超过限制,CloudFront 会返回错误消息。

如果您使用 * 通配符,则一次最多可以提出 15 个无效路径请求。您一次可以为每个分配的最多 3000 个单独文件提出失效请求,而通配符无效请求的限制与个别失效文件限制无关。

支付文件失效费用

您每月提交的前 1000 个失效路径免费;每月超过 1000 个之后,您须为每个失效路径支付费用。一个失效路径可以针对单个文件(如 /images/logo.jpg),也可针对多个文件(如 /images/*)。包含 * 通配符的路径计为一个路径,即使它导致 CloudFront 使数千个文件失效。

每月 1000 个失效路径的限制适用于您用一个 AWS 账户创建的所有分配的失效路径总数。例如,如果您使用 AWS 账户 john@example.com 创建三个分配,并在指定月份里为每个分配提交 600 个失效路径 (总共 1800 个失效路径),则 AWS 在该月将向您收取 800 个失效路径的费用。有关失效定价的特定信息,请参阅 Amazon CloudFront 定价。有关失效路径的更多信息,请参阅 失效路径