Request endpoints

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:

  • For general JSON API requests, excluding object uploads, use the following endpoint, replacing PATH_TO_RESOURCE with the appropriate value:

    https://storage.s3nsapis.fr/storage/v1/PATH_TO_RESOURCE
  • For JSON API object uploads, use the following endpoint, replacing BUCKET_NAME with the appropriate value:

    https://storage.s3nsapis.fr/upload/storage/v1/b/BUCKET_NAME/o
  • For batched requests, use the following endpoint, replacing PATH_TO_RESOURCE with the appropriate value:

    https://storage.s3nsapis.fr/batch/storage/v1/PATH_TO_RESOURCE
  • Optionally, for JSON API object downloads, you can use the following endpoint, replacing BUCKET_NAME and OBJECT_NAME with the appropriate values:

    https://storage.s3nsapis.fr/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media

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, replacing BUCKET_NAME and OBJECT_NAME with the appropriate values:

  • Virtual hosted-style endpoint:

    https://BUCKET_NAME.storage.s3nsapis.fr/OBJECT_NAME

  • Path-style endpoint:

    https://storage.s3nsapis.fr/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 URL 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 URL:

!, #, $, &, ', (, ), *, +, ,, /, :, ;, =, ?, @, [, ], 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 URL should be:

GET https://storage.s3nsapis.fr/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, see Section 3.3 Path in RFC 3986.

Trusted Cloud console endpoints

When using the Trusted Cloud console, you access different resources using the following URLs:

Resource URL
Bucket list for a project https://console.cloud.s3nscloud.fr/storage/browser?project=PROJECT_ID
Object list for a bucket https://console.cloud.s3nscloud.fr/storage/browser/BUCKET_NAME
Details for an object https://console.cloud.s3nscloud.fr/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 the Cloud Storage C++ API reference documentation.

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

Before running code samples, set the GOOGLE_CLOUD_UNIVERSE_DOMAIN environment variable to s3nsapis.fr.

namespace g = ::google::cloud;
namespace gcs = ::google::cloud::storage;
[](std::string const& bucket_name, std::string const& object_name) {
  // NOTE: the CLOUD_STORAGE_EMULATOR_HOST environment variable overrides any
  //     value provided here.
  auto client = gcs::Client(g::Options{}.set<gcs::RestEndpointOption>(
      "https://storage.googleapis.com"));
  PerformSomeOperations(client, bucket_name, object_name);
}

C#

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

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

Before running code samples, set the GOOGLE_CLOUD_UNIVERSE_DOMAIN environment variable to s3nsapis.fr.


using Google.Cloud.Storage.V1;
using System;

public class SetClientEndpointSample
{
    public StorageClient SetClientEndpoint(string endpoint) => new StorageClientBuilder
    {
        BaseUri = endpoint
    }.Build();
}

Go

For more information, see the Cloud Storage Go API reference documentation.

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

Before running code samples, set the GOOGLE_CLOUD_UNIVERSE_DOMAIN environment variable to s3nsapis.fr.

import (
	"context"
	"fmt"
	"io"

	"cloud.google.com/go/storage"
	"google.golang.org/api/option"
)

// setClientEndpoint sets the request endpoint.
func setClientEndpoint(w io.Writer, customEndpoint string, opts ...option.ClientOption) error {
	// customEndpoint := "https://my-custom-endpoint.example.com/storage/v1/"
	// opts := []option.ClientOption{}
	ctx := context.Background()

	// Add the custom endpoint option to any other desired options passed to storage.NewClient.
	opts = append(opts, option.WithEndpoint(customEndpoint))
	client, err := storage.NewClient(ctx, opts...)
	if err != nil {
		return fmt.Errorf("storage.NewClient: %w", err)
	}
	defer client.Close()

	// Use the client as per your custom endpoint, for example, attempt to get a bucket's metadata.
	client.Bucket("bucket-name").Attrs(ctx)
	return nil
}

Java

For more information, see the Cloud Storage Java API reference documentation.

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

Before running code samples, set the GOOGLE_CLOUD_UNIVERSE_DOMAIN environment variable to s3nsapis.fr.


import com.google.cloud.storage.Storage;
import com.google.cloud.storage.StorageOptions;

public class SetClientEndpoint {

  public static void setClientEndpoint(String projectId, String endpoint) {
    // The ID of your GCP project
    // String projectId = "your-project-id";

    // The endpoint you wish to target
    // String endpoint = "https://storage.googleapis.com"

    Storage storage =
        StorageOptions.newBuilder().setProjectId(projectId).setHost(endpoint).build().getService();

    System.out.println(
        "Storage Client initialized with endpoint " + storage.getOptions().getHost());
  }
}

Node.js

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

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

Before running code samples, set the GOOGLE_CLOUD_UNIVERSE_DOMAIN environment variable to s3nsapis.fr.

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// The custom endpoint to which requests should be made
// const apiEndpoint = 'https://yourcustomendpoint.com';

// Imports the Google Cloud client library
const {Storage} = require('@google-cloud/storage');

// Creates a client
const storage = new Storage({
  apiEndpoint: apiEndpoint,
  useAuthWithCustomEndpoint: true,
});

console.log(`Client initiated with endpoint: ${storage.apiEndpoint}.`);

PHP

For more information, see the Cloud Storage PHP API reference documentation.

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

Before running code samples, set the GOOGLE_CLOUD_UNIVERSE_DOMAIN environment variable to s3nsapis.fr.

use Google\Cloud\Storage\StorageClient;

/**
 * Sets a custom endpoint for storage client.
 *
 * @param string $projectId The ID of your Google Cloud Platform project.
 *        (e.g. 'my-project-id')
 * @param string $endpoint The endpoint for storage client to target.
 *        (e.g. 'https://storage.googleapis.com')
 */
function set_client_endpoint(
    string $projectId,
    string $endpoint
): void {
    $storage = new StorageClient([
        'projectId' => $projectId,
        'apiEndpoint' => $endpoint,
    ]);

    // fetching apiEndpoint and baseUri from StorageClient is excluded for brevity
    # ...
    print('Storage Client initialized.' . PHP_EOL);
}

Python

For more information, see the Cloud Storage Python API reference documentation.

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

Before running code samples, set the GOOGLE_CLOUD_UNIVERSE_DOMAIN environment variable to s3nsapis.fr.


from google.cloud import storage


def set_client_endpoint(api_endpoint):
    """Initiates client with specified endpoint."""
    # api_endpoint = 'https://storage.googleapis.com'

    storage_client = storage.Client(client_options={'api_endpoint': api_endpoint})

    print(f"client initiated with endpoint: {storage_client._connection.API_BASE_URL}")

    return storage_client

Ruby

For more information, see the Cloud Storage Ruby API reference documentation.

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

Before running code samples, set the GOOGLE_CLOUD_UNIVERSE_DOMAIN environment variable to s3nsapis.fr.

# api_endpoint = "https://storage.googleapis.com"

require "google/cloud/storage"

storage = Google::Cloud::Storage.new(
  endpoint: api_endpoint
)

puts "Client initiated with endpoint #{storage.service.service.root_url}"

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 and OBJECT_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 bucket example-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 begins with an alphanumeric sequence and contains the string /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.s3nsapis.fr/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