Request endpoints (original) (raw)

This page explains the different request endpoints you can use to access Cloud Storage. Cloud Storage supports HTTP/1.1, HTTP/2, and HTTP/3 protocols. An endpoint is the location where Cloud Storage can be accessed, written as a URL.

Typical API requests

JSON API

When making JSON API requests directly to Cloud Storage, use the following endpoints:

JSON API endpoints only accept HTTPS requests.

XML API

When making XML API requests directly to Cloud Storage, use the virtual hosted-style or path-style endpoint, replacingBUCKET_NAME and OBJECT_NAMEwith the appropriate values:

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.

gRPC

You can use gRPC, a high performance, open source universal RPC framework developed by Google, to interact with Cloud Storage. gRPC clients connect to a service endpoint. For Google Cloud services like Cloud Storage, this is typically a DNS address on the googleapis.com domain (for example, storage.googleapis.com) and uses standard secure ports such as 443. Using gRPC can provide improved performance and efficient streaming capabilities.

To use gRPC to interact with Cloud Storage, you need to enable it on Cloud Client Libraries.

Enable gRPC on a client library using one of the following supported languages:

For connections through a proxy, see the Troubleshooting topic for recommended practices.

Encoding URL path parts

In addition to general considerations for bucket naming andobject 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 URL:

!, #, $, &, ', (, ), *, +, ,, /, :, ;, =, ?,@, [, ], and space characters.

For example, if you send a JSON API GET request for the object namedfoo??bar in the bucket example-bucket, then your request URL 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-encoding, seeSection 3.3 Path in RFC 3986.

Google Cloud console endpoints

When using the Google 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
Data for an object See Authenticated browser downloads

gcloud endpoints

gcloud storage commands use JSON API endpoints. Endpoint usage is managed on your behalf by the gcloud CLI.

Client library endpoints

Cloud Storage client libraries manage request endpoints automatically. Optionally, you can set the request endpoint manually. This can be useful when you want to use a specific endpoint, or for testing, such as when you want to use a local emulator:

C++

For more information, see theCloud Storage C++ API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

C#

For more information, see theCloud Storage C# API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Go

For more information, see theCloud Storage Go API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Java

For more information, see theCloud Storage Java API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Node.js

For more information, see theCloud Storage Node.js API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

PHP

For more information, see theCloud Storage PHP API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Python

For more information, see theCloud Storage Python API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

Ruby

For more information, see theCloud Storage Ruby API reference documentation.

To authenticate to Cloud Storage, set up Application Default Credentials. For more information, seeSet up authentication for client libraries.

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.

The drawback to using A records is that they require additional setup and use of additional Google Cloud resources. SeeSetting 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:

When using CNAME records, the hostname portion of your CNAME record must be set to the following:

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 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 Cloud DNS, instructions for adding resource records can be found on the Add, modify, and delete records page.

Authenticated browser downloads

Authenticated browser downloads use cookie-based authentication. Cookie-based authentication asks users to sign in to their user account to establish their identity. The specified 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 account should have the 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 BUCKET_NAME andOBJECT_NAME with the appropriate values:

https://storage.cloud.google.com/BUCKET_NAME/OBJECT_NAME

For example, if you shared an image london.jpg from your bucketexample-maps, the URL would be:

https://storage.cloud.google.com/example-maps/london.jpg

After successfully signing in, you are redirected to the requested content. The URL for this content has the formathttps://ALPHANUMERIC_SEQUENCE-apidata.googleusercontent.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME.

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 XML API path-style endpoint:

https://storage.googleapis.com/BUCKET_NAME/OBJECT_NAME

For details and examples, see Accessing Public Data.

Mutual TLS support

Mutual TLS (mTLS) is an industry standard protocol for mutual authentication between a client and a server. Cloud Storage supports the following mTLS endpoints:

What's next