配置跨域资源共享 (CORS)

跨域资源共享 (CORS) 是一种可让不同网域中的资源之间实现交互的机制，但通常情况下，为了防止恶意行为，并不允许这种交互。在本主题中，您将了解如何为 Cloud Storage 存储分区配置 CORS。

如需详细了解 Cloud Storage CORS 支持，请参阅跨域资源共享 (CORS)。

为存储分区配置 CORS

要为某个存储分区配置 CORS，需指定 HTTP 方法和源网域等信息，以便确定该存储分区接受的请求类型。您可以使用 gsutil 命令行工具、XML API、JSON API 或适用于 Cloud Storage 的客户端库来为存储分区配置 CORS。

以下示例说明了如何为名为 example-bucket 的存储分区配置 CORS。该示例按如下所示设置 CORS 配置：

• 允许来自 example.appspot.com 的请求。
• 允许使用 GET、HEAD 或 DELETE HTTP 方法的请求。
• 允许在源之间共享 Content-Type 响应标头。

• 对于预检请求，浏览器需在 3600 秒（即 1 小时）之后重复预检请求，期间可自由发送请求。

gsutil

使用 gsutil cors 命令为存储分区配置 CORS：

gsutil cors set cors-json-file.json gs://example-bucket

其中 cors-json-file.json 是包含以下内容的本地文件：

[
    {
      "origin": ["http://example.appspot.com"],
      "responseHeader": ["Content-Type"],
      "method": ["GET", "HEAD", "DELETE"],
      "maxAgeSeconds": 3600
    }
]

您还可以使用 gsutil cors 命令获取存储分区的 CORS 配置：

gsutil cors get gs://example-bucket

客户端库

要以编程方式设置或获取存储分区的 CORS 配置，请使用一个适用于 Cloud Storage 的客户端库。如需开始此操作，请先了解以下参考内容：

• Go 参考：BucketHandle 类型
• Java 参考：Cors 类
• Node.js：Bucket
• PHP 参考：Google\Cloud\Storage\StorageClient
• Python 参考：cors
• Ruby 参考：Google::Cloud::Storage

REST API

JSON API

使用 JSON API 的 Buckets: insert 方法为新存储分区配置 CORS，或使用 Buckets: patch 方法为现有存储分区配置 CORS。以下示例展示了如何使用 Buckets: patch 方法。

PATCH /storage/v1/b/example-bucket?fields=cors HTTP/1.1
Host: storage.googleapis.com
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg
content-length: 132
accept: application/json
accept-encoding: gzip, deflate
content-type: application/json

{
  "location": "us-east-1",
  "storageClass": "standard",
  "cors": [
      {
          "maxAgeSeconds": "3600",
          "method": [
             "GET",
             "HEAD",
             "DELETE"
          ],
          "origin": [
             "http://example.appspot.com"
          ],
          "responseHeader":[
            "Content-Type"
         ]
      }
  ]
}

注意：使用 OAuth 2.0 获取可用于调用 JSON API 的授权令牌。要手动获取可立即使用的令牌，请使用 OAuth 2.0 Playground。如需详细了解如何为您的应用配置 OAuth，请参阅使用 OAuth 2.0 访问 Google API。

您可以使用 Buckets: get 方法来获取存储分区的 CORS 配置：

GET https://storage.googleapis.com/storage/v1/b/example-bucket
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

XML API

使用 XML API 的 Set Bucket CORS 方法为存储分区配置 CORS。

PUT http://storage.googleapis.com/example-bucket?cors HTTP/1.1
Host: storage.googleapis.com
Content-Length: 412
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

<?xml version="1.0" encoding="UTF-8"?>
<CorsConfig>
  <Cors>
    <Origins>
      <Origin>http://example.appspot.com</Origin>
    </Origins>
    <Methods>
      <Method>GET</Method>
      <Method>HEAD</Method>
      <Method>DELETE</Method>
    </Methods>
    <ResponseHeaders>
      <ResponseHeader>Content-Type</ResponseHeader>
    </ResponseHeaders>
    <MaxAgeSec>3600</MaxAgeSec>
  </Cors>
</CorsConfig>

注意：使用 OAuth 2.0 获取可用于调用 XML API 的授权令牌。要手动获取可立即使用的令牌，请使用 OAuth 2.0 Playground。如需详细了解如何为您的应用配置 OAuth，请参阅使用 OAuth 2.0 访问 Google API。

您可以使用 Get Bucket CORS 方法获取存储分区的 CORS 配置：

GET http://storage.googleapis.com/example-bucket?cors HTTP/1.1
Host: storage.googleapis.com
Authorization: Bearer ya29.AHES6ZRVmB7fkLtd1XTmq6mo0S1wqZZi3-Lh_s-6Uw7p8vtgSwg

CORS 请求问题排查

如果您在从其他网域访问 Cloud Storage 存储分区时遇到意外行为，请尝试按照以下步骤操作：

1. 对目标存储分区使用 gsutil cors get 以获取其 CORS 配置。如果存在多个 CORS 配置条目，则在执行以下步骤时，请确保请求值映射到同一个 CORS 配置条目中的值。

2. 使用您自己选择的工具查看请求和响应。在 Chrome 浏览器中，您可以使用标准开发者工具来查看此信息：

   1. 点击浏览器工具栏上的 Chrome 菜单 。
   2. 选择更多工具 > 开发者工具。
   3. 点击网络标签页。
   4. 通过您的应用或命令行发送请求。
   5. 在显示网络活动的窗格中，找到相应请求。
   6. 在名称列中，点击与相应请求对应的名称。
   7. 点击标头标签以查看响应标头，或点击响应标签以查看响应内容。

   如果您没有看到请求和响应，可能是由于您的浏览器缓存了先前尝试失败的预检请求。清除浏览器的缓存应该也会清除预检缓存。如果预检缓存未被清除，请将您的 CORS 配置中的 MaxAgeSec 值设置为较低值（如果未指定，默认值为 1800（即 30 分钟）），按照旧 MaxAgeSec 值所指定的时长耐心等待，然后重新尝试该请求。此时将执行新的预检请求，以提取新的 CORS 配置并完全清除缓存条目。调试完您的问题后，请将 MaxAgeSec 重新提升至较高值，以减少发往您的存储分区的预检流量。

3. 确保请求包含 Origin 标头，且该标头的值至少与存储分区 CORS 配置中的一个 Origins 值相匹配。请注意，这些值的架构、主机和端口必须完全匹配。下面提供了一些可以接受的匹配项示例：

   • http://origin.example.com 匹配 http://origin.example.com:80（因为 80 是默认的 HTTP 端口），但不匹配 https://origin.example.com、http://origin.example.com:8080、http://origin.example.com:5151 或 http://sub.origin.example.com。

   • https://example.com:443 匹配 https://example.com，但不匹配 http://example.com 或 http://example.com:443。

   • http://localhost:8080 仅与 http://localhost:8080 完全匹配，但不匹配 http://localhost:5555 或 http://localhost.example.com:8080。

4. 确保请求的 HTTP 方法（对于简单请求）或在 Access-Control-Request-Method 中指定的方法（对于预检请求）与存储分区 CORS 配置中的至少一个 Methods 值匹配。

5. 对于预检请求，请查看它是否包含一个或多个 Access-Control-Request-Header 标头。如果是这样，请确保每个 Access-Control-Request-Header 值与存储分区 CORS 配置中的一个 ResponseHeader 值匹配。Access-Control-Request-Header 中指定的所有标头必须包含在 CORS 配置中，才能使预检请求成功并使 CORS 标头包含在响应中。