This page explains the different request endpoints (URIs) you can use to access Cloud Storage. Cloud Storage supports HTTP/1.1, HTTP/2, and HTTP/3 protocols.
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
PLACEHOLDER
with the appropriate values:https://storage.googleapis.com/storage/v1/PATH_TO_RESOURCE
For JSON API object uploads, use the following endpoint, replacing
PLACEHOLDER
with the appropriate values:https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o
For batched requests, use the following endpoint, replacing
PLACEHOLDER
with the appropriate values:https://storage.googleapis.com/batch/storage/v1/PATH_TO_RESOURCE
Optionally, for JSON API object downloads, you can use the following endpoint, replacing
PLACEHOLDER
with the appropriate values:https://storage.googleapis.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media
JSON API endpoints only accept HTTPS requests.
XML API
For XML API requests, you can use either the virtual hosted-style or path-style endpoint, replacing
PLACEHOLDER
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
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 considerations for bucket naming and object naming, to ensure compatibility across Cloud Storage tools, you should encode the following characters 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://storage.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. Additionally, encoding is typically handled for you by client libraries, such as the Cloud Storage Client Libraries, so you can pass the raw object name when using such tools.
For more information about using percent-encoded for URIs, see Section 3.3 Path in RFC 3986.
Cloud Console endpoints
When using the Cloud Console, you access different resources using the following URLs:
Resource | URL |
---|---|
Bucket list for a project | https://console.cloud.google.com/storage/browser?project=PROJECT_ID |
Object list for a bucket | https://console.cloud.google.com/storage/browser/BUCKET_NAME |
Details for an object | https://console.cloud.google.com/storage/browser/_details/BUCKET_NAME/OBJECT_NAME |
Custom domains
If you own your own domain, you can map its URIs to one or more
Google Cloud services, including Cloud Storage buckets. The term
bucket-bound hostname is sometimes used to describe this
Cloud Storage request endpoint. To connect a custom domain to a
Cloud Storage bucket, you create either an A
or CNAME
redirect in
your DNS record.
A
records
When connecting a custom domain to a Cloud Storage bucket, you
generally should use an A
record.
A
records supportHTTPS
requests.A
records can be used to send traffic coming from a single hostname to multiple buckets as well as to other Google Cloud services.A
records do not place any restrictions on your bucket name.
The drawback to using A
records is that they require additional setup and
use of additional Google Cloud resources. See
Setting up your load balancer and SSL certificate for a guide to using
custom domains with A
records.
CNAME
records
When connecting a custom domain to a Cloud Storage bucket, you can
use a CNAME
record, but note that doing so has certain limitations:
CNAME
records only supportHTTP
requests.CNAME
records can only direct traffic from a given hostname to a single bucket.CNAME
records require the hostname and the associated bucket name to match, and you must validate your bucket name.CNAME
records can only be used for subdomains, such aswww.mydomain.com
, not top-level domains such asmydomain.com
.
When using CNAME
records, 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
download the object. For example, if you are using Identity and Access Management to control
access to your objects, the user's Google account should have
storage.objects.viewer
permission, which is
granted in the Storage Object Viewer role.
To download an object using cookie-based authentication, use the following URL,
replacing PLACEHOLDER
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.
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.
What's next
- Upload a file to Cloud Storage.
- Download a file from Cloud Storage.
- Host a static website.
- Learn about options to control access to your data.