Pontos finais de localização

Esta página descreve como usar pontos finais de localização para aceder ao Cloud Storage. Quando usa pontos finais de localização, pode garantir que os seus dados em repouso permanecem dentro da jurisdição para cumprir os requisitos de residência de dados.

Nota: para executar as suas cargas de trabalho de uma forma compatível com os regulamentos internacionais de tráfego de armas (ITAR), use endpoints regionais. Para ver informações sobre restrições quando usa o Cloud Storage de uma forma em conformidade com o ITAR, consulte o artigo Restrições e limitações para o ITAR.

Vista geral

Os pontos finais de localização são pontos finais de pedidos que só permitem que os pedidos prossigam se o recurso afetado existir na localização especificada pelo ponto final. Por exemplo, quando usa o ponto final https://us-central1-storage.googleapis.com num pedido de eliminação de contentor, o pedido só prossegue se o contentor estiver localizado em US-CENTRAL1.

Ao contrário dos pontos finais globais, em que os pedidos podem ser processados numa localização diferente da localização do recurso, os pontos finais de localização garantem que os pedidos são processados apenas na localização especificada pelo ponto final, onde o recurso reside.

Nota: o Cloud Load Balancing usa endpoints de pedidos globais quando encaminha pedidos para contentores do Cloud Storage. Não pode configurar o Cloud Load Balancing para usar pontos finais de localização.

A utilização de pontos finais de localização garante que:

• Os seus dados armazenados no Cloud Storage não saem da localização especificada.

• Os seus dados são terminados por TLS na região especificada pelo ponto final quando transitam de local para Google Cloud.

Quando usa pontos finais de localização, assume as seguintes responsabilidades:

• Para receber garantias de residência de dados, os pedidos feitos a um ponto final de localização têm de ter origem na mesma localização especificada pelo ponto final. Por exemplo, se estiver a usar uma máquina virtual do Compute Engine para fazer um pedido a um contentor residente em US-CENTRAL1 através do ponto final us-central1-storage.googleapis.com, a máquina virtual também tem de residir em US-CENTRAL1.

• Os pontos finais de localização só podem ser usados quando realizar operações suportadas. A execução de operações não suportadas resulta num erro.

Os pontos finais de localização suportam o tráfego entre as instalações e o Google Cloud através da interligação ou da VPN, e o tráfego entre os Google Cloud serviços (por exemplo, do BigQuery para o Cloud Storage). O tráfego da Internet não é suportado.

Operações compatíveis

A tabela seguinte resume as operações que podem e não podem ser realizadas com pontos finais de localização. Em geral, as operações na mesma localização podem ser realizadas com pontos finais de localização, enquanto as operações em várias localizações não podem.

Se tentar realizar uma operação não suportada através de um ponto final de localização, o Cloud Storage devolve um código de erro HTTP 400 com a mensagem: "Este ponto final não implementa esta operação. Use o ponto final global."

Operação	Altera os dados do objeto	Suportado para utilização com pontos finais de localização
objetos compõem	Sim	Sim^1
objetos eliminados	Não	Sim^1
objetos são	Sim	Sim^1
inserção de objetos	Sim	Sim^1
lista de objetos	Não	Sim^1
patch de objetos	Não	Sim^1
objetos copiados	Sim	Sim^4
reescrita de objetos	Sim	Sim^4
inserção de baldes	Não	Sim^2
buckets delete	Não	Sim^3
buckets get	Não	Sim^2
patch de contentores	Não	Sim^2
Atualização de contentores	Não	Sim^2
buckets getIamPolicy	Não	Sim^2
buckets setIamPolicy	Não	Sim^2
buckets testIamPermissions	Não	Sim^2
buckets lockRetentionPolicy	Não	Sim^2
buckets BucketAccessControls	Não	Sim^2
buckets DefaultObjectAccessControls	Não	Sim^2
buckets ObjectAccessControls	Não	Sim^2
Operações de chaves HMAC	Não	Não
Operações da conta de serviço	Não	Não
Operações de notificação do Pub/Sub	Varia consoante a operação	Não
Operações de notificação de alterações de objetos	Varia consoante a operação	Não
Operações em lote	Varia consoante a operação	Não

¹ Para realizar esta operação através de pontos finais de localização, o contentor que contém o objeto afetado tem de existir na localização especificada pelo ponto final. Por exemplo, um pedido de eliminação de objetos para us-central1-storage.googleapis.com só pode ser usado para eliminar objetos em contentores que residam na região US-CENTRAL1. Se tentar eliminar um objeto numa localização que não seja US-CENTRAL1, a operação devolve um erro NOT_FOUND.

² Para realizar esta operação através de pontos finais de localização, o contentor tem de existir na localização especificada pelo ponto final. Por exemplo: um pedido de criação de um contentor para us-central1-storage.googleapis.com só pode ser usado para criar um contentor na região US-CENTRAL1. Se tentar criar o contentor numa localização que não seja US-CENTRAL1, a operação devolve um erro INVALID_ARGUMENT.

³ Para realizar esta operação através de pontos finais de localização, o contentor tem de existir na localização especificada pelo ponto final. Por exemplo: um pedido de eliminação de um contentor para us-central1-storage.googleapis.com só pode ser usado para eliminar um contentor na região US-CENTRAL1. Se tentar eliminar um contentor numa localização que não seja US-CENTRAL1, a operação devolve um erro NOT_FOUND.

⁴ Para realizar esta operação através de pontos finais de localização, os contentores de origem e de destino têm de existir na localização especificada pelo ponto final. Por exemplo, pode usar pontos finais de localização para copiar um objeto de um contentor para outro se ambos os contentores existirem na mesma localização. No entanto, não pode usar pontos finais de localização para copiar um objeto de um contentor para outro se os contentores existirem em localizações diferentes. Se o contentor de origem ou de destino existir numa localização diferente da localização especificada pelo ponto final, a operação devolve um erro NOT_FOUND.

Regiões suportadas

Os pontos finais de localização são suportados para todas as regiões dos EUA, a US multirregião e a NAM4 região dupla predefinida. Para mais informações sobre as regiões que podem ser especificadas, consulte o artigo Localizações dos contentores.

Fazer pedidos

Consola

Consulte as Restrições e limitações para a ITAR para obter informações sobre como realizar operações através da Google Cloud consola de forma compatível com a ITAR.

Linha de comandos

Para configurar a Google Cloud CLI para utilização com pontos finais de localização:

1. Defina a propriedade api_endpoint_overrides/storage para o ponto final de localização que quer usar:

   gcloud config set api_endpoint_overrides/storage https://LOCATION-storage.googleapis.com/

Depois de definir esta propriedade, pode usar os comandos da CLI gcloud como normalmente.

Em alternativa, pode usar pontos finais de localização para comandos individuais definindo a CLOUDSDK_API_ENDPOINT_OVERRIDES_STORAGEvariável de ambiente em cada comando. Por exemplo:

CLOUDSDK_API_ENDPOINT_OVERRIDES_STORAGE=https://LOCATION-storage.googleapis.com/ gcloud ls gs://my-bucket

Bibliotecas cliente

As bibliotecas cliente do Cloud Storage gerem automaticamente os pontos finais de pedidos, mas pode definir manualmente os pontos finais de localização. Para saber como definir pontos finais de localização, consulte os exemplos de código da biblioteca cliente que usam pontos finais de pedidos.

APIs REST

API JSON

Ao fazer pedidos a pontos finais de localização, use os seguintes URIs:

• Para pedidos gerais da API JSON, excluindo carregamentos de objetos, use o seguinte ponto final:

  https://LOCATION-storage.googleapis.com

  Substitua LOCATION por uma localização de contentor suportada. Por exemplo, us-central1.

• Para carregamentos de objetos da API JSON, use o seguinte ponto final:

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

  Substituição:

  • LOCATION com uma localização do contentor suportada. Por exemplo, us-central1.

  • BUCKET_NAME com o nome do contentor para o qual quer carregar um objeto. Por exemplo, my-example-bucket.

• Para transferências de objetos da API JSON, use o seguinte ponto final:

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

  Substituição:

  • LOCATION com uma localização do contentor suportada. Por exemplo, us-central1.

  • BUCKET_NAME com o nome do contentor que contém o objeto que quer transferir. Por exemplo, my-example-bucket.

  • OBJECT_NAME com o nome do objeto que quer transferir. Por exemplo, waterfall.png.

Tenha em atenção que os pontos finais da API JSON só suportam pedidos HTTPS.

API XML

Quando usa a API XML para fazer pedidos a pontos finais de localização, pode usar um ponto final de estilo alojado virtualmente ou um ponto final de estilo de caminho:

• Ponto final de estilo alojado virtualmente:

  https://BUCKET_NAME.LOCATION-storage.googleapis.com

• Ponto final de estilo de caminho:

  https://LOCATION-storage.googleapis.com/BUCKET_NAME

Para ambos os tipos de pontos finais, substitua:

• LOCATION com uma localização do contentor suportada. Por exemplo, us-central1.

• BUCKET_NAME com um nome de contentor válido. Por exemplo, my-example-bucket.

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 fizer a autenticação no Cloud Storage através do OAuth 2.0.

Formate corretamente os pedidos

Para garantir que os seus pedidos são compatíveis com as ferramentas do Cloud Storage:

• Certifique-se de que codifica corretamente os carateres especiais que aparecem no nome do objeto ou na string de consulta de um URI de pedido.

• Familiarize-se com a atribuição de nomes aos contentores e as considerações sobre a atribuição de nomes aos objetos.

Restrições conhecidas

Não existe suporte para pontos finais mTLS.

Restringir a utilização do ponto final da API global

Para ajudar a aplicar a utilização de pontos finais de localização, pode usar a restrição da política da organização constraints/gcp.restrictEndpointUsage para bloquear pedidos ao ponto final da API global. Para mais informações, consulte a documentação Restrinja a utilização de pontos finais.