Pontos finais de pedidos

Esta página explica os diferentes pontos finais de pedidos que pode usar para aceder ao Cloud Storage. O Cloud Storage suporta os protocolos HTTP/1.1, HTTP/2 e HTTP/3. Um ponto final é a localização onde o Cloud Storage pode ser acedido, escrito como um URL.

Nota: os URLs do Cloud Storage descritos nesta página estão sujeitos a alterações.

Pedidos de API típicos

API JSON

Quando fizer pedidos da API JSON diretamente para o Cloud Storage, use os seguintes pontos finais:

• Para pedidos gerais da API JSON, excluindo carregamentos de objetos, use o seguinte ponto final, substituindo PATH_TO_RESOURCE pelo valor adequado:

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

• Para carregamentos de objetos da API JSON, use o seguinte ponto final, substituindo BUCKET_NAME pelo valor adequado:

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

• Para pedidos em lote, use o seguinte ponto final, substituindo PATH_TO_RESOURCE pelo valor adequado:

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

• Opcionalmente, para transferências de objetos da API JSON, pode usar o seguinte endpoint, substituindo BUCKET_NAME e OBJECT_NAME pelos valores adequados:

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

Os pontos finais da API JSON só aceitam pedidos HTTPS.

Nota: também é suportado um ponto final https://www.googleapis.com para a API JSON e é devolvido no campo de metadados selfLink de um objeto, mas https://storage.googleapis.com é o ponto final preferencial para um melhor desempenho e disponibilidade. Da mesma forma, um ponto final https://content-storage.googleapis.com é suportado para transferências e é devolvido no campo de metadados mediaLink para um objeto, mas também não é recomendado para utilização.

API XML

Importante: se pretender publicar conteúdo através de um navegador, tenha em atenção que a API XML publica conteúdo a partir da mesma origem que o ponto final do pedido. Se precisar de publicar conteúdo a partir de uma origem exclusiva, considere usar a API JSON ou as transferências autenticadas do navegador.

Quando fizer pedidos de API XML diretamente para o Cloud Storage, use o ponto final de estilo alojado virtual ou estilo de caminho, substituindo BUCKET_NAME e OBJECT_NAME pelos valores adequados:

• Ponto final de estilo alojado virtualmente:

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

• Ponto final de estilo de caminho:

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

Nota: não é possível usar pontos finais de estilo alojado virtual para aceder a contentores com nomes de domínio. Em alternativa, use pontos finais de estilo de caminho ou um redirecionamento.

Os pontos finais da API XML suportam a encriptação da camada de ligação segura (SSL), o que significa que pode usar HTTP ou HTTPS. Recomendamos a utilização de HTTPS, especialmente se autenticar no Cloud Storage através do OAuth 2.0.

Para ligações através de um proxy, consulte o tópico de resolução de problemas para ver as práticas recomendadas.

Codificar partes do caminho do URL

Além das considerações gerais para a nomenclatura de contentores e a nomenclatura de objetos, para garantir a compatibilidade entre as ferramentas do Cloud Storage, deve codificar os seguintes carateres quando aparecem no nome do objeto ou na string de consulta de um URL de pedido:

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

Por exemplo, se enviar um pedido da API JSONGET para o objeto denominado foo??bar no contentor example-bucket, o URL do pedido deve ser:

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

Tenha em atenção que nem todos os carateres indicados têm de ser codificados em todos os cenários. Além disso, a codificação é normalmente processada pelas bibliotecas cliente, como as bibliotecas cliente do Cloud Storage, para que possa transmitir o nome do objeto não processado quando usar essas ferramentas.

Para mais informações sobre a utilização da codificação em percentagem, consulte a secção 3.3 Path na RFC 3986.

Google Cloud endpoints da consola

Quando usa a Google Cloud consola, acede a diferentes recursos através dos seguintes URLs:

Recurso	URL
Lista de segmentos para um projeto	https://console.cloud.google.com/storage/browser?project=PROJECT_ID
Lista de objetos de um contentor	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 o artigo Transferências de navegadores autenticadas

gcloud endpoints

Os comandos gcloud storage usam pontos finais da API JSON. A utilização do ponto final é gerida em seu nome pela CLI gcloud.

Pontos finais da biblioteca cliente

As bibliotecas cliente do Cloud Storage gerem automaticamente os pontos finais dos pedidos. Opcionalmente, pode definir o ponto final do pedido manualmente. Isto pode ser útil quando quiser usar um ponto final específico ou para testes, como quando quiser usar um emulador local:

C++

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

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 C# do Cloud Storage.

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 Go do Cloud Storage.

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 Java do Cloud Storage.

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 Node.js do Cloud Storage.

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 PHP do Cloud Storage.

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 Python do Cloud Storage.

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 Ruby do Cloud Storage.

Para se autenticar no Cloud Storage, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 for proprietário do seu próprio domínio, pode mapear os respetivos URIs para um ou mais Google Cloud serviços, incluindo contentores do Cloud Storage. O termo nome de anfitrião associado ao contentor é, por vezes, usado para descrever este ponto final de pedido do Cloud Storage. Para associar um domínio personalizado a um contentor do Cloud Storage, cria um redirecionamento A ou CNAME no registo DNS.

A registos

Quando associa um domínio personalizado a um contentor do Cloud Storage, deve, geralmente, usar um registo A.

• A registos de pedidos de apoio técnico HTTPS.
• Os registos A podem ser usados para enviar tráfego proveniente de um único nome de anfitrião para vários contentores, bem como para outros serviços Google Cloud .
• Os registos A não impõem restrições ao nome do seu contentor.

A desvantagem da utilização de registos A é que requerem configuração adicional e a utilização de recursos Google Cloud adicionais. Consulte o artigo Configurar o equilibrador de carga e o certificado SSL para ver um guia de utilização de domínios personalizados com registos A.

CNAME registos

Quando associa um domínio personalizado a um contentor do Cloud Storage, pode usar um registo CNAME, mas tenha em atenção que esta ação tem determinadas limitações:

• Os registos CNAME só suportam pedidos HTTP.
• Os registos CNAME só podem direcionar o tráfego de um determinado nome de anfitrião para um único contentor.
• Os registos CNAME requerem que o nome de anfitrião e o nome do contentor associado correspondam e tem de validar o nome do contentor.
• Os registos CNAME só podem ser usados para subdomínios, como www.mydomain.com, e não para domínios de nível superior, como mydomain.com.

Quando usar registos CNAME, a parte do nome de anfitrião do seu registo CNAME tem de ser definida como o seguinte:

c.storage.googleapis.com.

Por exemplo, suponhamos que o seu domínio é example.com e quer disponibilizar mapas de viagens aos seus clientes. Pode criar um contentor no Cloud Storage denominado travel-maps.example.com e, em seguida, criar um registo CNAME no DNS que redireciona os pedidos de travel-maps.example.com para o URI do Cloud Storage. Para o fazer, publique o seguinte registo CNAME no DNS:

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

Desta forma, os seus clientes podem usar o seguinte URL para aceder a um mapa de Paris:

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

O serviço de registo de domínios deve ter uma forma de administrar o seu domínio, incluindo a adição de um registo de recursos CNAME. Por exemplo, se usar o Cloud DNS, pode encontrar instruções para adicionar registos de recursos na página Adicionar, modificar e eliminar registos.

Transferências de navegadores autenticadas

As transferências de navegador autenticadas usam a autenticação baseada em cookies. A autenticação baseada em cookies pede aos utilizadores para iniciarem sessão na respetiva conta de utilizador para estabelecerem a respetiva identidade. A conta especificada tem de ter a autorização adequada para transferir o objeto. Por exemplo, se estiver a usar a gestão de identidades e acessos para controlar o acesso aos seus objetos, a conta do utilizador deve ter a permissão storage.objects.viewer, que é concedida na função de leitor de objetos do armazenamento.

Para transferir um objeto através da 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 partilhou uma imagem london.jpg do seu contentor example-maps, o URL seria:

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

Depois de iniciar sessão com êxito, é feito o redirecionamento para o conteúdo pedido. O URL deste conteúdo começa com uma sequência alfanumérica e contém a string /download/storage/v1/b/BUCKET_NAME/o/OBJECT_NAME

A utilização de HTTPS é obrigatória quando efetua transferências autenticadas do navegador; as tentativas de utilização de HTTP são redirecionadas para HTTPS.

Acesso a objetos públicos

Todos os pedidos ao URI storage.cloud.google.com requerem autenticação. Isto aplica-se mesmo quando allUsers tem autorização para aceder a um objeto. Se quiser que os utilizadores transfiram objetos acessíveis anonimamente sem autenticação, use o ponto final de estilo de caminho da API XML:

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

Para ver detalhes e exemplos, consulte o artigo Aceder a dados públicos.

Suporte de TLS mútuo

O TLS mútuo (mTLS) é um protocolo da norma da indústria para a autenticação mútua entre um cliente e um servidor. O Cloud Storage suporta os seguintes pontos finais mTLS:

• Pedidos de API JSON: storage.mtls.googleapis.com

• Transferências de navegador autenticadas: storage.mtls.cloud.google.com

O que se segue?

• Carregue um ficheiro para o Cloud Storage.
• Transfira um ficheiro do Cloud Storage.
• Alojamento de um Website estático.
• Saiba mais sobre as opções para controlar o acesso aos seus dados.