Endpoints de solicitação

Nesta página, explicamos os diferentes endpoints de solicitação que podem ser usados para acessar o Cloud Storage. O Cloud Storage é compatível com os protocolos HTTP/1.1, HTTP/2 e HTTP/3. Um endpoint é o local em que o Cloud Storage pode ser acessado, escrito como um URL.

Solicitações comuns de API

API JSON

Ao fazer solicitações de API em JSON diretamente para o Cloud Storage, use os seguintes endpoints:

  • Para solicitações de API JSON gerais, exceto uploads de objetos, use o seguinte endpoint, substituindo PATH_TO_RESOURCE pelo valor adequado:

    https://storage.googleapis.com/storage/v1/PATH_TO_RESOURCE

  • Use o endpoint a seguir para uploads de objeto da API JSON, substituindo BUCKET_NAME pelo valor adequado:

    https://storage.googleapis.com/upload/storage/v1/b/BUCKET_NAME/o

  • Use o seguinte endpoint para solicitações em lote, substituindo PATH_TO_RESOURCE pelo valor adequado:

    https://storage.googleapis.com/batch/storage/v1/PATH_TO_RESOURCE

  • Como opção, é possível usar o seguinte endpoint para downloads de objetos da API JSON, substituindo BUCKET_NAME e OBJECT_NAME pelos valores apropriados:

    https://storage.googleapis.com/download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME?alt=media

Os endpoints da API JSON só aceitam solicitações HTTPS.

API XML

Ao fazersolicitações da API XML diretamente para o Cloud Storage, use o endpoint com estilo virtual hospedado ou estilo de caminho, substituindo BUCKET_NAME e OBJECT_NAME pelos valores apropriados:

  • Endpoint com estilo de hospedagem virtual: 

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

  • Endpoint no estilo de caminho: 

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

Os endpoints da API XML são compatíveis com a criptografia secure sockets layer (SSL), isso significa que você pode usar HTTP ou HTTPS. Recomendamos o uso de HTTPS, especialmente se você faz autenticação no Cloud Storage usando o OAuth 2.0.

Para conexões por proxy, consulte o tópico Solução de problemas para conhecer as práticas recomendadas.

Como codificar partes do caminho do URL

Além de seguir as considerações gerais de nomeação de buckets e de objetos, é necessário codificar os seguintes caracteres quando aparecerem no nome do objeto ou na string de consulta de um URI de solicitação para garantir a compatibilidade entre as ferramentas do Cloud Storage:

!, #, $, &, ', (, ), *, +, ,, /, :, ;, =, ?, @, [, ] e caracteres de espaço.

Por exemplo, se você enviar uma solicitação GET à API JSON referente ao objeto denominado foo??bar no bucket example-bucket, seu URL de solicitação deverá ser:

GET https://storage.googleapis.com/storage/v1/b/example-bucket/o/foo%3f%3fbar

Nem todos os caracteres listados precisam ser codificados em todos os cenários. Além disso, a codificação é normalmente gerenciada para você pelas bibliotecas de cliente, como as bibliotecas de cliente do Cloud Storage. Portanto, é possível transmitir o nome bruto do objeto ao usar essas ferramentas.

Para mais informações sobre como usar a codificação por porcentagem, consulte a Seção 3.3 Caminho na RFC 3986.

Endpoints do console do Google Cloud

Ao usar o console do GoogleCloud, você acessa recursos diferentes usando os seguintes URLs:

Recurso URL
Lista de buckets de um projeto https://console.cloud.google.com/storage/browser?project=PROJECT_ID
Lista de objetos de um bucket https://console.cloud.google.com/storage/browser/BUCKET_NAME
Detalhes de um objeto https://console.cloud.google.com/storage/browser/_details/BUCKET_NAME/OBJECT_NAME
Dados de um objeto Consulte Downloads em navegadores autenticados.

gcloud endpoints

Os comandos gcloud storage usam endpoints da API JSON. O uso de endpoints é gerenciado em seu nome pela CLI gcloud.

Endpoints de biblioteca de cliente

As bibliotecas de cliente do Cloud Storage gerenciam os endpoints de solicitação automaticamente. Também é possível definir o endpoint da solicitação manualmente. Isso pode ser útil quando você quer usar um endpoint específico, ou para testes, por exemplo, quando você quer usar um emulador local:

C++

Para mais informações, consulte a documentação de referência da API Cloud Storage C++.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

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#

Para mais informações, consulte a documentação de referência da API Cloud Storage C#.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 


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

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

Go

Para mais informações, consulte a documentação de referência da API Cloud Storage Go.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

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

Para mais informações, consulte a documentação de referência da API Cloud Storage Java.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 


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

Para mais informações, consulte a documentação de referência da API Cloud Storage Node.js.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

/**
 * 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

Para mais informações, consulte a documentação de referência da API Cloud Storage PHP.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

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

Para mais informações, consulte a documentação de referência da API Cloud Storage Python.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 


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

Para mais informações, consulte a documentação de referência da API Cloud Storage Ruby.

Para autenticar no Cloud Storage, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente. 

# 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}"

Domínios personalizados

Se você tiver um domínio próprio, mapeie os URIs para um ou mais serviços do Google Cloud, incluindo os buckets do Cloud Storage. Às vezes, o termo nome do host vinculado ao bucket é usado para descrever esse endpoint de solicitação do Cloud Storage. Para conectar um domínio personalizado a um bucket do Cloud Storage, crie um redirecionamento A ou CNAME no seu registro DNS.

A registros

Ao conectar um domínio personalizado a um bucket do Cloud Storage, geralmente é necessário usar um registro A.

  • Os registros A são compatíveis com solicitações HTTPS.
  • Registros A podem ser usados para enviar tráfego proveniente de um único nome de host para vários buckets, bem como para outros serviços do Google Cloud.
  • Os registros A não impõem restrições ao nome do seu bucket.

A desvantagem de usar registros A é que eles exigem configuração e uso adicionais de recursos adicionais do Google Cloud. Consulte Como configurar o balanceador de carga e o certificado SSL para um guia sobre como usar domínios personalizados com registros A.

CNAME registros

Ao conectar um domínio personalizado a um bucket do Cloud Storage, é possível usar um registro CNAME, mas isso tem algumas limitações:

  • Os registros CNAME são compatíveis apenas com solicitações HTTP.
  • Os registros CNAME só podem direcionar o tráfego de um determinado nome do host para um único bucket.
  • Os registros CNAME exigem o nome do host e o nome do bucket associado para corresponder e é necessário validar o nome do bucket.
  • Registros CNAME só podem ser usados para subdomínios, como www.mydomain.com, não domínios de nível superior, como mydomain.com.

Ao usar registros CNAME, a parte do nome do host de registro CNAME precisa ser definida da seguinte maneira:

c.storage.googleapis.com.

Por exemplo, se o domínio for example.com e você quiser disponibilizar mapas de viagem para seus clientes: Crie um bucket no Cloud Storage denominado travel-maps.example.com e depois crie um registro CNAME no DNS que redirecione as solicitações de travel-maps.example.com para o URI do Cloud Storage. Para fazer isso, publique o seguinte registro CNAME no DNS:

NAME                      TYPE     DATA
travel-maps               CNAME    c.storage.googleapis.com.

Com isso, seus clientes podem usar este URL para acessar um mapa de Paris:

http://travel-maps.example.com/paris.jpg

O serviço de registro de domínio precisa ter como administrar seu domínio, incluindo adicionar um registro de recurso CNAME. Por exemplo, se você usa o Cloud DNS, as instruções para adicionar registros de recurso podem ser encontradas na página Adicionar, modificar e excluir registros.

Downloads em navegadores autenticados

Os downloads por navegador autenticado usam autenticação baseada em cookies. A autenticação baseada em cookies solicita que os usuários façam login nas respectivas contas do usuário para definir a identidade. A conta especificada precisa ter a permissão apropriada para Baixar o objeto. Por exemplo, se você estiver usando o Gerenciamento de identidade e acesso para controlar o acesso aos objetos, a conta do usuário deverá ter a permissão storage.objects.viewer, que é concedida no papel de Visualizador de objetos no Storage.

Para fazer o download de um objeto usando a autenticação baseada em cookies, use o seguinte URL, substituindo BUCKET_NAME e OBJECT_NAME pelos valores adequados:

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

Por exemplo, se você compartilhou uma imagem london.jpg do bucket example-maps, o URL será:

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

Após fazer login, você será redirecionado para o conteúdo solicitado. O URL desse conteúdo começa com uma sequência alfanumérica e contém a string /download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME

O uso de HTTPS é necessário ao realizar downloads do navegador autenticado, as tentativas de usar o HTTP fazem o redirecionamento para HTTPS.

Acesso a objetos públicos

Todas as solicitações para o URI storage.cloud.google.com exigem autenticação. Isso se aplica até mesmo quando allUsers tem permissão para acessar um objeto. Se você quiser que os usuários façam o download de objetos acessados de maneira anônima sem autenticação, use o endpoint em estilo de caminho da API XML:

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

Para detalhes e exemplos, consulte Como acessar dados públicos.

Suporte a TLS mútuo

O TLS mútuo (mTLS) é um protocolo padrão do setor para autenticação mútua entre um cliente e um servidor. O Cloud Storage oferece suporte a estes endpoints mTLS:

A seguir