跨源资源共享 (CORS)

转到示例

同源政策是在客户端网络应用(比如网络浏览器)上实施的安全策略,用于防止来自不同来源的资源之间发生交互。虽然这种安全措施可用于防止恶意行为,但也可能会阻止已知来源之间开展的合法交互。例如,App Engine 上托管的页面(网址为 example.appspot.com)中的脚本可能需要使用存储在 Cloud Storage 存储分区(网址为 example.storage.googleapis.com)中的资源。但是,由于浏览器会将它们视为两个不同的来源,因此不允许来自 example.appspot.com 的脚本从 example.storage.googleapis.com 提取资源。

跨域资源共享 (CORS) 规范是由万维网联盟 (W3C) 制定的,该规范旨在克服这一限制。 Cloud Storage 支持此规范,这意味着,它允许您将存储分区配置为支持 CORS。在上述示例中,您可以配置 example.storage.googleapis.com 存储分区,以便浏览器与来自 example.appspot.com 的脚本共享该存储分区的资源。

如需详细了解 CORS 配置元素,请参阅设置存储分区 CORS

CORS 的工作原理

CORS 请求分为两种类型:简单请求和预检请求。简单请求可以直接发出。预检请求必须先向服务器发送初步“预检”请求以获得许可,然后才可以继续发出主请求。如果满足以下任何一种情况,系统将对请求执行预检:

  • 请求使用的是 GETHEADPOST 以外的方法。
  • 请求使用 POST 方法且 Content-Type 不是 text/plainapplication/x-www-form-urlencodedmultipart/form-data
  • 请求设置了自定义标头,例如 X-PINGOTHER

当浏览器向 Cloud Storage 发出简单请求时,会发生以下过程:

  1. 浏览器将 Origin 标头添加到请求中。Origin 标头包含相应资源(该资源在寻求共享 Cloud Storage 存储分区的资源)的来源,例如 Origin:https://www.example.appspot.com

  2. Cloud Storage 将请求的 HTTP 方法以及 Origin 标头的值与目标存储分区的 CORS 配置中的方法来源信息进行比较,以查看是否存在匹配项。如果存在匹配项,Cloud Storage 将在响应中包含 Access-Control-Allow-Origin 标头。Access-Control-Allow-Origin 标头包含初始请求的 Origin 标头的值。

  3. 浏览器接收响应并检查 Access-Control-Allow-Origin 值是否与原始请求中指定的网域匹配。如果它们匹配,则请求成功。如果它们不匹配,或者响应中不存在 Access-Control-Allow-Origin 标头,则请求失败。

预检请求首先执行以下步骤。如果成功,则它将执行与简单请求相同的过程:

  1. 浏览器发送一个 OPTIONS 请求(包含主请求的 Requested MethodRequested Headers)。

  2. Cloud Storage 使用目标资源允许的 HTTP 方法和标头的值进行响应。如果预检请求中的任何方法或标头值未包含在目标资源允许的方法和标头集合中,请求将失败,并且不会发送主请求。

上文是对 CORS 进行的精简介绍。如需查看更完整的说明,请参阅提取规范。

Cloud Storage CORS 支持

Cloud Storage 仅允许您在存储分区级层设置 CORS 配置。 您可以使用 gsutil 命令行工具、XML APIJSON API 为存储分区设置 CORS 配置。但是,CORS 配置仅适用于 XML API 请求。

不同的 Cloud Storage 端点会通过以下方式处理 CORS 请求:

  • 无论目标存储分区上采用何种 CORS 配置,JSON API 端点都允许执行 CORS 请求。
  • XML API 端点基于目标存储分区上的 CORS 配置接受 CORS 请求。
  • 向基于身份验证的浏览器下载端点 storage.cloud.google.com 发出的请求不允许 CORS 请求。请注意,Cloud Console 会为每个对象的公开网址链接提供此端点。

您可以使用以下任一 XML API 请求网址,从 Cloud Storage 获取包含 CORS 标头的响应:

storage.googleapis.com/[BUCKET_NAME]
[BUCKET_NAME].storage.googleapis.com

如需了解 XML API 请求网址,请参阅请求端点

CORS 配置的元素

您为存储分区的 CORS 配置设置的值决定了 Cloud Storage 在 HTTP 响应中返回的 CORS 标头:

字段 说明 XML API 响应行为 JSON API 响应行为
来源 指定您要允许与此 Cloud Storage 存储分区进行跨域资源共享的来源。 例如,https://origin1.example.com 如果浏览器请求中的来源与 CORS 配置中的来源匹配,则 Cloud Storage 会向浏览器返回 Access-Control-Allow-Origin。如果没有匹配项,则 Cloud Storage 不会在响应中包含 Access-Control-Allow-Origin。您可以提供一个通配符值,以向所有来源授予访问权限:<Origin>*</Origin> Cloud Storage 会返回 Access-Control-Allow-Origin 标头并将其设置为请求的来源。
方法

指定要允许与此 Cloud Storage 存储分区进行跨域资源共享的 HTTP 方法。该值会在 Access-Control-Allow-Methods 标头中返回,以响应成功的预检请求。

由于 OPTIONS 是浏览器用于发出预检请求的标准方法,因此您不应在 CORS 配置中指定 OPTIONS

Cloud Storage 支持以下方法:DELETEGETHEADPOSTPUT

Cloud Storage 会根据存储分区的 CORS 配置检查 Access-Control-Request-Methods 标头中从浏览器发送的方法。如果没有匹配项,Cloud Storage 将返回一个 200 响应代码,但不包含 CORS 响应标头。

Cloud Storage 会返回 Access-Control-Allow-Methods 标头并将其设置为以下方法:DELETEGETHEADPATCHPOSTPUT
响应标头 响应标头字段指定您要允许与此 Cloud Storage 存储分区进行跨域资源共享的标头。该值会在 Access-Control-Allow-Headers 标头中返回,以响应成功的预检请求。 对于预检请求,Cloud Storage 会根据存储分区的 CORS 配置检查 Access-Control-Request-Headers 标头中从浏览器发送的标头。如果没有匹配项,Cloud Storage 不会返回 CORS 响应标头。 Cloud Storage 会返回 Access-Control-Allow-Headers 标头并将其设置为与 Access-Control-Request-Headers 标头指定的值相同。
最长存在时间(秒)(可选) MaxAgeSec 字段指定浏览器在发出请求多少秒后必须重复预检请求。这也称为缓存过期时间。该值会在 Access-Control-Max-Age 标头中返回,以响应预检请求。例如,3600 将缓存过期时间设置为 1 小时。 Cloud Storage 会返回 Access-Control-Max-Age 标头并将其设置为指定的缓存过期时间。如果省略此字段,Cloud Storage 将返回默认值 3600 Cloud Storage 会返回 Access-Control-Max-Age 标头,其默认值为 3600
其他注意事项
凭据 Cloud Storage 目前不支持 CORS 凭据。 Cloud Storage 始终返回 Access-Control-Allow-Credentials 标头并将其设置为 true。

对于简单请求,如果 CORS 请求获得批准并有效,则 Access-Control-Allow-Credentials 标头将设置为 true。

对于预检请求,如果 Access-Control-Request-Method 为空,则 Cloud Storage 会将 Access-Control-Allow-Credentials 设置为 true,同时拒绝请求并显示 404 - Not Found

公开的标头 Access-Control-Expose-Headers 响应标头会列出响应中公开的标头名称。 对于简单请求,Access-Control-Expose-Headers 会列出 CORS 配置中的响应标头值。 对于简单请求,如果常见 HTTP 标头列表中包含 Access-Control-Request-Headers 中指定的值,则 Access-Control-Expose-Headers 会返回这些值。

客户端 CORS 支持

大多数浏览器都使用 XMLHttpRequest 对象来发出跨域请求。 XMLHttpRequest 负责插入正确的标头以及处理与服务器进行的 CORS 交互。您不必添加任何新代码即可在 Cloud Storage 存储分区上支持配置 CORS。

后续步骤