请求端点

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

典型的 API 请求

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

JSON API

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

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

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

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

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

JSON API 端点仅接受 HTTPS 请求。

XML API

  • 对于典型的 XML API 请求,您可以使用虚拟托管样式端点或路径样式端点,并将 [VALUES_IN_BRACKETS] 替换为适当的值:

    虚拟托管样式:

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

(可选)对于上传和下载请求,Cloud Storage 提供了专用 XML API 端点。传输大量数据时,这些上传和下载端点可能会带来细微的性能优势。

  • 对于上传请求,您可以使用虚拟托管样式端点或路径样式端点,并将 [VALUES_IN_BRACKETS] 替换为适当的值:

    虚拟托管样式:

    https://[BUCKET_NAME].storage-upload.googleapis.com/[OBJECT_NAME]
    路径样式:
    https://storage-upload.googleapis.com/[BUCKET_NAME]/[OBJECT_NAME]

  • 对于下载请求,您可以使用虚拟托管样式端点或路径样式端点,并将 [VALUES_IN_BRACKETS] 替换为适当的值:

    虚拟托管样式:

    https://[BUCKET_NAME].storage-download.googleapis.com/[OBJECT_NAME]
    路径样式:
    https://storage-download.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

请注意,并非所有列出的字符在每种情况下都必须编码:例如,/ 字符仅在使用 JSON API 重写或复制时才必须进行编码,并且仅针对此类重写/复制中的源对象进行编码。

如需详细了解如何对 URI 采用百分比编码形式,请参阅 RFC 3986 中的第 3.3 节“路径”。请注意,编码通常由客户端库(例如 Cloud Storage 客户端库)为您处理,因此您可以将原始对象名称传递给客户端库。

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 帐号必须具有用于访问资源的相应权限(通过 IAM 政策或访问控制列表授予这些权限)才能执行浏览器下载。

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

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。要详细了解基于身份验证的浏览器下载,请参阅基于 Cookie 的身份验证

访问公开对象

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

后续步骤