请求端点

本页面介绍了可用于访问 Cloud Storage 的不同请求端点 (URI)。

典型的 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

CNAME 重定向

CNAME 重定向是一种特殊的 DNS 记录,它允许您使用您自己的网域的 URI,通过 XML API 访问 Cloud Storage 中的资源,此方法不会泄露实际的 XML API URI。要执行此操作,您必须将以下 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.example.com   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。如需了解详情和示例,请参阅访问公开数据

后续步骤