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 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.

gRPC

É possível usar o gRPC, um framework RPC universal de alto desempenho e código aberto desenvolvido pelo Google, para interagir com o Cloud Storage. Os clientes gRPC se conectam a um endpoint de serviço. Para serviçosGoogle Cloud , como o Cloud Storage, geralmente é um endereço DNS no domínio googleapis.com (por exemplo, storage.googleapis.com) e usa portas seguras padrão, como 443. O uso do gRPC pode melhorar o desempenho e oferecer recursos de streaming eficientes.

Para usar o gRPC e interagir com o Cloud Storage, é necessário ativá-lo nas bibliotecas de cliente do Cloud.

Ative o gRPC em uma biblioteca de cliente usando uma das seguintes linguagens compatíveis:

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 consoleGoogle Cloud

Ao usar o console do Google Cloud , 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 se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em 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#

Saiba mais na documentação de referência C# da API Cloud Storage.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em 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

Saiba mais na documentação de referência Go da API Cloud Storage.

Para se autenticar no Cloud Storage, configure o Application Default Credentials. Saiba mais em 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"