本页面介绍了可用于访问 Cloud Storage 的不同请求端点。Cloud Storage 支持 HTTP/1.1、HTTP/2 和 HTTP/3 协议。 端点是可访问 Cloud Storage 的位置,写成网址形式。
典型的 API 请求
JSON API
直接向 Cloud Storage 发出 JSON API 请求时,请使用以下端点:
对于一般 JSON API 请求(不包括对象上传),请使用以下端点,并将
PATH_TO_RESOURCE
替换为适当的值:https://storage.googleapis.com/storage/v1/PATH_TO_RESOURCE
对于 JSON API 对象上传请求,请使用以下端点(将
BUCKET_NAME
替换为适当的值):https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o
对于批量请求,请使用以下端点,并将
PATH_TO_RESOURCE
替换为适当的值:https://storage.googleapis.com/batch/storage/v1/PATH_TO_RESOURCE
(可选)对于 JSON API 对象下载,您可以使用以下端点,并将
BUCKET_NAME
和OBJECT_NAME
替换为适当的值:https://storage.googleapis.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media
JSON API 端点仅接受 HTTPS 请求。
XML API
向 Cloud Storage 直接发出 XML API 请求时,请使用虚拟托管样式或路径样式端点,并将 BUCKET_NAME
和 OBJECT_NAME
替换为适当的值:
虚拟托管样式端点:
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 进行身份验证时)。
对于通过代理创建的连接,请参阅问题排查主题以查看建议的做法。
对网址路径部分编码
除了存储桶命名和对象命名的一般注意事项之外,您还应该在请求网址的对象名称或查询字符串中出现以下字符时对这些字符进行编码,以确保 Cloud Storage 工具之间的兼容性:
!
、#
、$
、&
、'
、(
、)
、*
、+
、,
、/
、:
、;
、=
、?
、@
、[
、]
和空格字符。
例如,如果您为存储桶 example-bucket
中名为 foo??bar
的对象发送 JSON APIGET
请求,则您的请求网址应为:
GET https://storage.googleapis.com/storage/v1/b/example-bucket/o/foo%3f%3fbar
请注意,并非所有列出的字符在每种情况下都必须编码。此外,编码通常由客户端库(如 Cloud Storage 客户端库)为您处理,因此您可以在使用此类工具时传递原始对象名称。
如需详细了解如何使用百分比编码,请参阅 RFC 3986 中的第 3.3 节“路径”。
Google Cloud 控制台端点
使用 Google Cloud 控制台时,您可以使用以下网址访问各种资源:
资源 | 网址 |
---|---|
项目的存储桶列表 | 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 |
对象的数据 | 请参阅经过身份验证的浏览器下载 |
gcloud endpoints
gcloud storage
命令使用 JSON API 端点。端点使用情况由 gcloud CLI 代表您管理。
客户端库端点
Cloud Storage 客户端库会自动管理请求端点。或者,您也可以选择手动设置请求端点。如果要使用特定端点或进行测试(例如,在使用本地模拟器时),便需要进行手动设置:
C++
如需了解详情,请参阅 Cloud Storage C++ API 参考文档。
如需向 Cloud Storage 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证。
C#
如需了解详情,请参阅 Cloud Storage C# API 参考文档。
如需向 Cloud Storage 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证。
Go
如需了解详情,请参阅 Cloud Storage Go API 参考文档。
如需向 Cloud Storage 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证。
Java
如需了解详情,请参阅 Cloud Storage Java API 参考文档。
如需向 Cloud Storage 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证。
Node.js
如需了解详情,请参阅 Cloud Storage Node.js API 参考文档。
如需向 Cloud Storage 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证。
PHP
如需了解详情,请参阅 Cloud Storage PHP API 参考文档。
如需向 Cloud Storage 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证。
Python
如需了解详情,请参阅 Cloud Storage Python API 参考文档。
如需向 Cloud Storage 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证。
Ruby
如需了解详情,请参阅 Cloud Storage Ruby API 参考文档。
如需向 Cloud Storage 进行身份验证,请设置应用默认凭据。 如需了解详情,请参阅为客户端库设置身份验证。
自定义网域
如果您拥有自己的网域,则可以将其 URI 映射到一项或多项 Google Cloud 服务(包括 Cloud Storage 存储桶)。术语“存储桶绑定主机名”有时用于描述此 Cloud Storage 请求端点。如需将自定义网域连接到 Cloud Storage 存储桶,您可以在 DNS 记录中创建 A
或 CNAME
重定向。
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
记录时,必须将 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
资源记录)。例如,如果您使用 Cloud DNS,则可以在添加、修改和删除记录页面上找到添加资源记录的说明。
经过身份验证的浏览器下载
基于身份验证的浏览器下载使用基于 Cookie 的身份验证。基于 Cookie 的身份验证要求用户登录其用户账号以确定他们的身份。指定的账号必须拥有适当的权限才能下载对象。例如,如果您使用 Identity and Access Management 控制对象的访问权限,则用户的账号应拥有 storage.objects.viewer
权限,该权限是 Storage Object Viewer 角色授予的。
要使用基于 Cookie 的身份验证下载对象,请使用以下网址,并将 BUCKET_NAME
和 OBJECT_NAME
替换为适当的值:
https://storage.cloud.google.com/BUCKET_NAME/OBJECT_NAME
例如,如果您共享来自存储桶 example-maps
的图片 london.jpg
,网址将如下所示:
https://storage.cloud.google.com/example-maps/london.jpg
成功登录后,您会被重定向到所请求的内容。此内容的网址以字母数字序列开头且包含字符串 /download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME
在执行基于身份验证的浏览器下载时,必须使用 HTTPS;尝试使用 HTTP 会重定向至 HTTPS。
访问公开对象
对 storage.cloud.google.com
URI 发出的所有请求都需要进行身份验证。即使 allUsers
有权访问对象,也需遵守这一要求。如果您希望用户在未经过身份验证的情况下下载可匿名访问的对象,请使用 XML API 路径样式端点:
https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME
如需了解详情和示例,请参阅访问公开数据。
双向 TLS 支持
双向 TLS (mTLS) 是一种用于客户端和服务器之间进行双向身份验证的业界标准协议。Cloud Storage 支持以下 mTLS 端点:JSON API 请求:
storage.mtls.googleapis.com
经过身份验证的浏览器下载:
storage.mtls.cloud.google.com
后续步骤
- 将文件上传到 Cloud Storage。
- 从 Cloud Storage 下载文件。
- 托管静态网站。
- 了解用于控制数据的访问权限的选项。