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.
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.
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 finalus-central1-storage.googleapis.com
, a máquina virtual também tem de residir emUS-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 | Sim1 |
objetos eliminados | Não | Sim1 |
objetos são | Sim | Sim1 |
inserção de objetos | Sim | Sim1 |
lista de objetos | Não | Sim1 |
patch de objetos | Não | Sim1 |
objetos copiados | Sim | Sim4 |
reescrita de objetos | Sim | Sim4 |
inserção de baldes | Não | Sim2 |
buckets delete | Não | Sim3 |
buckets get | Não | Sim2 |
patch de contentores | Não | Sim2 |
Atualização de contentores | Não | Sim2 |
buckets getIamPolicy | Não | Sim2 |
buckets setIamPolicy | Não | Sim2 |
buckets testIamPermissions | Não | Sim2 |
buckets lockRetentionPolicy | Não | Sim2 |
buckets BucketAccessControls | Não | Sim2 |
buckets DefaultObjectAccessControls | Não | Sim2 |
buckets ObjectAccessControls | Não | Sim2 |
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 |
1 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
.
2 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
.
3 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
.
4 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:
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_STORAGE
variá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
.
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.