Endpoints de solicitação

Mantenha tudo organizado com as coleções Salve e categorize o conteúdo com base nas suas preferências.

Nesta página, explicamos os diferentes endpoints de solicitação (URIs) 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.

Solicitações comuns de API

Use os seguintes URIs para fazer solicitações diretamente a uma das APIs do Cloud Storage:

API JSON

  • Para solicitações gerais da API JSON, exceto uploads de objetos, use o endpoint a seguir, substituindo PLACEHOLDER pelos valores adequados:

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

  • Use o endpoint a seguir para uploads de objeto da API JSON, substituindo PLACEHOLDER pelos valores adequados:

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

  • Use o endpoint a seguir para solicitações em lote, substituindo PLACEHOLDER pelos valores adequados:

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

  • Como opção, é possível usar o endpoint a seguir para downloads de objeto da API JSON, substituindo PLACEHOLDER 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

  • Para solicitações da API XML, use o endpoint com estilo de hospedagem virtual ou estilo de caminho e substitua PLACEHOLDER pelos valores apropriados:

    Estilo de hospedagem virtual:

    https://BUCKET_NAME.storage.googleapis.com/OBJECT_NAME
    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 de URI

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 URI 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 o uso de códigos percentuais para URIs, consulte a Seção 3.3 Path (em inglês) 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

gcloud endpoints

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

Endpoints de gsutil

O gsutil gerencia endpoints de solicitação em seu nome, mas é possível controlar a API que a gsutil prefere usar. Por padrão, o gsutil acessa o Cloud Storage por meio da API JSON e dos endpoints associados. É possível esse padrão configurando a variável prefer_api na seção "GSUtil" do arquivo de configuração .boto como xml ou json da seguinte maneira:

prefer_api = xml

A gsutil usa a API preferida sempre que possível, mas, se não for possível, a gsutil volta a usar a outra API silenciosamente. Por exemplo, o comando ubla não é compatível com a API XML. Por isso, a gsutil sempre usa a API JSON para esse comando. Da mesma forma, a gsutil sempre usa a API XML ao interagir com provedores de armazenamento em nuvem que não são compatíveis com a API JSON.

Considerações do gsutil ao usar a API XML

  • É possível controlar se a gsutil usa endpoints da API XML no estilo de caminho ou virtualmente hospedados no estilo de edição editando oscalling_format na seção "s3" daArquivo de configuração .boto Por padrão, a gsutil usa endpoints da API XML no estilo de caminho do Cloud Storage.

    • Use calling_format = boto.s3.connection.OrdinaryCallingFormat para endpoints no estilo do caminho.

    • Use calling_format = boto.s3.connection.SubdomainCallingFormat para endpoints no estilo de hospedagem virtual.

  • A API XML usa a estrutura boto. Ela relê os arquivos baixados para calcular um hash MD5 se não houver um. Para objetos que não incluem hashes MD5 nos metadados, como objetos compostos, isso dobra a largura de banda consumida e o tempo decorrido necessário para o download. Se você estiver trabalhando com objetos compostos, evite definir prefer_api como xml.

  • A API XML exige chamadas separadas para receber cada campo de metadados de objeto e bucket disponíveis, como cada configuração definida em um bucket. Usar a API JSON, quando possível, usa menos operações e, portanto, um custo menor.

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

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


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. 

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) error {
	// customEndpoint := "https://my-custom-endpoint.example.com/storage/v1"
	ctx := context.Background()

	// Set a custom request endpoint for this client.
	client, err := storage.NewClient(ctx, option.WithEndpoint(customEndpoint))
	if err != nil {
		return fmt.Errorf("storage.NewClient: %v", err)
	}
	defer client.Close()

	fmt.Fprintf(w, "The request endpoint set for the client is: %v\n", customEndpoint)
	return nil
}

Java

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


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. 

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

use Google\Cloud\Storage\StorageClient;

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

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


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. 

# 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, no Google Domains, as instruções para adicionar um registro de recurso estão na página de Ajuda do Google Domains, na seção suspensa Registros de recurso.

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 Google para definir a identidade. A conta do Google especificada precisa ter a permissão apropriada para fazer o download do objeto. Por exemplo, se você estiver usando o Gerenciamento de identidade e acesso para controlar o acesso aos objetos, a Conta do Google 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 URL a seguir substituindo PLACEHOLDER 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

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. Caso queira que os usuários façam o download de objetos acessíveis anonimamente sem autenticação, use o URI storage.googleapis.com documentado nas solicitações de API diretas. Para detalhes e exemplos, consulte Como acessar dados públicos.

A seguir