This page explains the different request endpoints (URIs) you can use to access Cloud Storage.
Typical API requests
When making requests directly to one of the Cloud Storage APIs, use the following URIs:
JSON API
For general JSON API requests, excluding object uploads, use the following endpoint, replacing
[VALUES_IN_BRACKETS]
with the appropriate values:https://storage.googleapis.com/storage/v1/[PATH_TO_RESOURCE]
For JSON API object uploads, use the following endpoint, replacing
[VALUES_IN_BRACKETS]
with the appropriate values:https://storage.googleapis.com/upload/storage/v1/b/[BUCKET_NAME]/o
For batched requests, use the following endpoint, replacing
[VALUES_IN_BRACKETS]
with the appropriate values:https://storage.googleapis.com/batch/storage/v1/[PATH_TO_RESOURCE]
JSON API endpoints only accept HTTPS requests.
XML API
For all XML API requests, you can use either the virtual hosted-style or path-style endpoint, replacing
[VALUES_IN_BRACKETS]
with the appropriate values:Virtual hosted-style:
https://[BUCKET_NAME].storage.googleapis.com/[OBJECT_NAME]
Path-style:https://storage.googleapis.com/[BUCKET_NAME]/[OBJECT_NAME]
Optionally for uploads and downloads, Cloud Storage offers dedicated XML API endpoints. These upload and download endpoints may provide a small performance benefit when transferring large amounts of data.
For uploads, you can use either the virtual hosted-style or path-style endpoint, replacing
[VALUES_IN_BRACKETS]
with the appropriate values:Virtual hosted-style:
https://[BUCKET_NAME].storage-upload.googleapis.com/[OBJECT_NAME]
Path-style:https://storage-upload.googleapis.com/[BUCKET_NAME]/[OBJECT_NAME]
For downloads, you can use either the virtual hosted-style or path-style endpoint, replacing
[VALUES_IN_BRACKETS]
with the appropriate values:Virtual hosted-style:
https://[BUCKET_NAME].storage-download.googleapis.com/[OBJECT_NAME]
Path-style:https://storage-download.googleapis.com/[BUCKET_NAME]/[OBJECT_NAME]
All XML API endpoints support secure sockets layer (SSL) encryption, which means you can use either HTTP or HTTPS. Using HTTPS is recommended, especially if you authenticate to Cloud Storage using OAuth 2.0.
For connections through a proxy, see the Troubleshooting topic for recommended practices.
Encoding URI path parts
In addition to general bucket and object naming considerations, to ensure compatibility across Cloud Storage tools, you should encode the following charaters when they appear in either the object name or query string of a request URI:
!
, #
, $
, &
, '
, (
, )
, *
, +
, ,
, /
, :
, ;
, =
, ?
,
@
, [
, ]
, and space characters.
For example, if you send a JSON API GET
request for the object named
foo??bar
in the bucket example-bucket
, then your request URI should be:
GET https://www.googleapis.com/storage/v1/b/example-bucket/o/foo%3f%3fbar
Note that not all of the listed characters must be encoded in every scenario:
for example, the /
character must be encoded only when
rewriting or copying with the JSON API and only for the source
object in such a rewrite/copy.
For more information about using percent-encoded for URIs, see Section 3.3 Path in RFC 3986. Note that encoding is typically handled for you by client libraries, such as the Cloud Storage Client Libraries, so you can pass the raw object name to them.
CNAME
Redirects
A CNAME
redirect is a special DNS record that lets you use URIs from your own
domain to access resources in Cloud Storage through the XML API without
revealing the actual XML API URIs. To do this, the following URI must be added
to the host name portion of your CNAME
record:
c.storage.googleapis.com.
For example, say your domain is example.com
, and you want to make travel
maps available to your customers. You can create a bucket in Cloud Storage
called travel-maps.example.com
, and then create a CNAME
record in DNS that
redirects requests from travel-maps.example.com
to the Cloud Storage URI.
To do this, you publish the following CNAME
record in DNS:
NAME TYPE DATA travel-maps.example.com CNAME c.storage.googleapis.com.
By doing this, your customers can use the following URL to access a map of Paris:
http://travel-maps.example.com/paris.jpg
Your domain registration service should have a way for you to administer your
domain, including adding a CNAME
resource record. For example, if you use
Google Domains, instructions for adding a resource record can be found on
the Google Domains Help page, in the Resource records drop-down
section.
Authenticated Browser Downloads
Authenticated browser downloads use cookie-based authentication. Cookie-based authentication asks users to sign in to their Google account to establish their identity. The specified Google account must have appropriate permission to access the resource, granted though IAM policies or Access Control Lists, in order to perform the browser download.
To download an object using cookie-based authentication, use the following URL,
replacing [VALUES_IN_BRACKETS]
with the appropriate values:
https://storage.cloud.google.com/[BUCKET_NAME]/[OBJECT_NAME]
For example, if you shared an image london.jpg
from your bucket
example-maps
, the URL would be:
https://storage.cloud.google.com/example-maps/london.jpg
Using HTTPS is required when performing authenticated browser downloads; attempts to use HTTP redirect to HTTPS. For more information about authenticated browser downloads, see Cookie-based Authentication.
Access to public objects
All requests to the storage.cloud.google.com
URI require authentication.
This applies even when allUsers
have permission to access an object. If you
want users to download anonymously accessible objects without authenticating,
use the storage.googleapis.com
URI documented in
Direct API requests. For details and examples, see
Accessing Public Data.