请求端点

本页面介绍了可用于访问 Cloud Storage 的不同请求端点 (URI)。 Cloud Storage 支持 HTTP/1.1、HTTP/2 和 HTTP/3 协议。

典型的 API 请求

直接向其中一个 Cloud Storage API 发出请求时,请使用以下 URI:

JSON API

  • 对于一般 JSON API 请求(不包括对象上传),请使用以下端点,并将 PLACEHOLDER 替换为适当的值:

    https://storage.googleapis.com/storage/v1/PATH_TO_RESOURCE
  • 对于 JSON API 对象上传请求,请使用以下端点(将 PLACEHOLDER 替换为适当的值):

    https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o
  • 对于批量请求,请使用以下端点,并将 PLACEHOLDER 替换为适当的值:

    https://storage.googleapis.com/batch/storage/v1/PATH_TO_RESOURCE
  • (可选)对于 JSON API 对象下载,您可以使用以下端点并将 PLACEHOLDER 替换为适当的值:

    https://storage.googleapis.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media

JSON API 端点仅接受 HTTPS 请求。

XML API

  • 对于 XML API 请求,您可以使用“虚拟托管样式”或“路径样式”端点,将 PLACEHOLDER 替换为适当的值:

    虚拟托管样式:

    https://BUCKET_NAME.storage.googleapis.com/OBJECT_NAME
    路径样式:
    https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME

XML API 端点支持安全套接字层 (SSL) 加密,这意味着您可以使用 HTTP 或 HTTPS。建议使用 HTTPS(尤其是在使用 OAuth 2.0 向 Cloud Storage 进行身份验证时)。

对于通过代理创建的连接,请参阅问题排查主题以查看建议的做法。

对 URI 路径部分编码

除了存储分区命名对象命名的一般注意事项之外,您还应该在请求 URI 的对象名称或查询字符串中出现以下字符时对这些字符进行编码,以确保 Cloud Storage 工具之间的兼容性:

!#$&'()*+,/:;=?@[] 和空格字符。

例如,如果您为存储分区 example-bucket 中名为 foo??bar 的对象发送 JSON APIGET 请求,则您的请求 URI 应为:

GET https://storage.googleapis.com/storage/v1/b/example-bucket/o/foo%3f%3fbar

请注意,并非所有列出的字符在每种情况下都必须编码。此外,编码通常由客户端库(如 Cloud Storage 客户端库)为您处理,因此您可以在使用此类工具时传递原始对象名称。

如需详细了解如何对 URI 采用百分比编码形式,请参阅 RFC 3986 中的第 3.3 节“路径”

Cloud Console 端点

使用 Cloud Console 时,您可以使用以下网址访问不同的资源:

资源 网址
项目的存储分区列表 https://console.cloud.google.com/storage/browser?project=PROJECT_ID
存储分区的对象列表 https://console.cloud.google.com/storage/browser/BUCKET_NAME
对象的详细信息 https://console.cloud.google.com/storage/browser/_details/BUCKET_NAME/OBJECT_NAME

gsutil 端点

默认情况下,gsutil 通过 JSON API 请求端点访问 Cloud Storage。您可以将 .boto 配置文件的“GSUtil”部分中的 prefer_api 变量设置为 xmljson,以控制此默认值:

prefer_api = xml

虽然 gsutil 会尽可能使用首选 API,但如果不可行,gsutil 将以静默方式回退至使用其他 API。例如,XML API 不支持 ubla 命令,因此 gsutil 始终对该命令使用 JSON API。同样,在与不支持 JSON API 的云端存储空间服务进行交互时,gsutil 始终使用 XML API。

性能和费用注意事项

XML API 使用 boto 框架。 该框架会重新读取下载的文件,以计算 MD5 哈希值(如果不存在 MD5 哈希值)。对于元数据中不包含 MD5 哈希值的对象(例如复合对象),这会使下载所需的带宽和所用时间翻倍。如果您使用的是复合对象,应避免将 prefer_api 设置为 xml

XML API 还需要通过单独调用来获取不同的对象和存储分区元数据字段,例如存储分区配置。尽量使用 JSON API 会减少操作次数,从而降低费用。

自定义网域

如果您拥有自己的网域,则可以将其 URI 映射到一项或多项 Google Cloud 服务(包括 Cloud Storage 存储桶)。术语“存储桶绑定主机名”有时用于描述此 Cloud Storage 请求端点。如需将自定义网域连接到 Cloud Storage 存储桶,您可以在 DNS 记录中创建 ACNAME 重定向。

A 记录

将自定义网域连接到 Cloud Storage 存储分区时,通常应使用 A 记录。

  • A 记录支持 HTTPS 请求。
  • A 记录可用于将来自单个主机名的流量发送到多个存储桶以及其他 Google Cloud 服务。
  • A 记录对您的存储分区名称不设任何限制。

使用 A 记录的缺点是它们需要额外设置和使用其他 Google Cloud 资源。如需查看如何将自定义网域和 A 记录结合使用的指南,请参阅设置负载平衡器和 SSL 证书

CNAME 记录

将自定义网域连接到 Cloud Storage 存储分区时,您可以使用 CNAME 记录,但请注意,这样做存在一定限制:

  • CNAME 记录仅支持 HTTP 请求。
  • CNAME 记录只能将来自指定主机名的流量定向到单个存储桶。
  • CNAME 记录要求主机名和关联的存储分区名称匹配,并且您必须验证存储分区名称
  • CNAME 记录只能用于子网域(例如 www.mydomain.com),但不能用于顶级网域(例如 mydomain.com)。

使用 CNAME 记录时,必须将以下 URI 添加到 CNAME 记录的主机名部分:

c.storage.googleapis.com.

例如,假设您的网域是 example.com,并且您希望为您的客户提供旅行地图。您可以在 Cloud Storage 中创建一个名为 travel-maps.example.com 的存储分区,然后在 DNS 中创建 CNAME 记录,将请求从 travel-maps.example.com 重定向到 Cloud Storage URI。为此,您在 DNS 中发布以下 CNAME 记录:

NAME                      TYPE     DATA
travel-maps               CNAME    c.storage.googleapis.com.

如此操作之后,您的客户便可以使用以下网址访问巴黎的地图:

http://travel-maps.example.com/paris.jpg

您使用的域名注册服务应具备适当的方法,便于您管理域名(包括添加 CNAME 资源记录)。例如,如果您使用 Google Domains,则可以在“Google Domains 帮助”页面资源记录下拉列表部分中找到有关添加资源记录的说明。

经过身份验证的浏览器下载

基于身份验证的浏览器下载使用基于 Cookie 的身份验证。基于 Cookie 的身份验证要求用户登录他们的 Google 帐号以确定他们的身份。指定的 Google 帐号必须具有适当的权限才能下载对象。例如,如果您使用 Identity and Access Management 控制对象的访问权限,则用户的 Google 帐号应具有 storage.objects.viewer 权限,该权限是 Storage Object Viewer 角色授予的

要使用基于 Cookie 的身份验证下载对象,请使用以下网址(将 PLACEHOLDER 替换为适当的值):

https://storage.cloud.google.com/BUCKET_NAME/OBJECT_NAME

例如,如果您共享来自存储分区 example-maps 的图片 london.jpg,网址将如下所示:

https://storage.cloud.google.com/example-maps/london.jpg

在执行基于身份验证的浏览器下载时,必须使用 HTTPS;尝试使用 HTTP 会重定向至 HTTPS。

访问公开对象

storage.cloud.google.com URI 发出的所有请求都需要进行身份验证。即使 allUsers 有权访问对象,也需遵守这一要求。如果您希望用户在未经过身份验证的情况下下载可匿名访问的对象,请使用直接 API 请求中介绍的 storage.googleapis.com URI。如需了解详情和示例,请参阅访问公开数据

后续步骤