Endpoint di localizzazione

Questa pagina descrive come utilizzare gli endpoint di località per accedere a Cloud Storage. L'utilizzo di endpoint di località ti aiuta a garantire che i tuoi dati at-rest rimangano all'interno della giurisdizione per soddisfare i requisiti di residenza dei dati.

Nota: gli endpoint basati sulla località possono essere utilizzati per accedere a Cloud Storage in modo conforme all'International Traffic in Arms Regulations (ITAR) in base a un modello di responsabilità condivisa. Per mantenere la conformità, devi comprendere e operare all'interno delle limitazioni e delle responsabilità elencate in questa pagina. Gli endpoint a livello di regione sono progettati per impedire il routing accidentale al di fuori della regione e sono il metodo preferito per soddisfare la conformità ITAR. Ti consigliamo di utilizzare gli endpoint regionali, se possibile.

Panoramica

Gli endpoint basati sulla località sono endpoint di richiesta che consentono di procedere con le richieste solo se la risorsa interessata esiste nella posizione specificata dall'endpoint. Ad esempio, quando utilizzi l'endpoint https://us-central1-storage.googleapis.com in una richiesta di eliminazione di un bucket, la richiesta procede solo se il bucket si trova in US-CENTRAL1.

A differenza degli endpoint globali, in cui le richieste possono essere elaborate in una località diversa da quella in cui si trova la risorsa, gli endpoint basati sulla località garantiscono che le richieste vengano elaborate solo all'interno della località specificata dall'endpoint, in cui si trova la risorsa.

Nota: Cloud Load Balancing utilizza endpoint di richiesta globali durante il routing delle richieste ai bucket Cloud Storage. Non puoi configurare Cloud Load Balancing per utilizzare endpoint localizzati.

L'utilizzo di endpoint di località garantisce che:

• I dati archiviati in Cloud Storage non lasciano la località specificata.

• La terminazione TLS dei dati viene eseguita nella regione specificata dall'endpoint durante il transito da on-premise a Google Cloud.

Quando utilizzi gli endpoint di località, ti assumi le seguenti responsabilità:

• Per ottenere le garanzie di residenza dei dati, le richieste effettuate a un endpoint di località devono provenire dalla stessa località specificata dall'endpoint. Ad esempio, se utilizzi una macchina virtuale Compute Engine per inviare una richiesta a un bucket che si trova in US-CENTRAL1 tramite l'endpoint us-central1-storage.googleapis.com, anche la macchina virtuale deve trovarsi in US-CENTRAL1.

• Gli endpoint basati sulla località devono essere utilizzati solo durante l'esecuzione di operazioni supportate. L'esecuzione di operazioni non supportate genera un errore.

Gli endpoint di località supportano il traffico tra on-premise e Google Cloud tramite Interconnect o VPN e il traffico tra i servizi Google Cloud (ad esempio, da BigQuery a Cloud Storage). Il traffico internet non è supportato.

Operazioni supportate

La tabella seguente riassume le operazioni che possono e non possono essere eseguite con gli endpoint regionali. In generale, le operazioni all'interno di una località possono essere eseguite con endpoint di località, mentre le operazioni tra località non possono essere eseguite.

Se tenti di eseguire un'operazione non supportata utilizzando un endpoint di località, Cloud Storage restituisce un codice di errore HTTP 400 con il messaggio: "Questo endpoint non implementa questa operazione. Utilizza l'endpoint globale."

Operazione	Modifica i dati degli oggetti	Supportato per l'utilizzo con endpoint di località
composizione degli oggetti	Sì	Sì^1
objects delete	No	Sì^1
objects get	Sì	Sì^1
inserimento di oggetti	Sì	Sì^1
elenco degli oggetti	No	Sì^1
patch objects	No	Sì^1
copia degli oggetti	Sì	Sì^4
riscrittura degli oggetti	Sì	Sì^4
buckets insert	No	Sì^2
buckets delete	No	Sì^3
buckets get	No	Sì^2
patch dei bucket	No	Sì^2
Aggiornamento dei bucket	No	Sì^2
buckets getIamPolicy	No	Sì^2
buckets setIamPolicy	No	Sì^2
buckets testIamPermissions	No	Sì^2
buckets lockRetentionPolicy	No	Sì^2
BucketAccessControls dei bucket	No	Sì^2
bucket DefaultObjectAccessControls	No	Sì^2
buckets ObjectAccessControls	No	Sì^2
Operazioni con chiavi HMAC	No	No
Operazioni dei service account	No	No
Operazioni di notifica Pub/Sub	Varia in base all'operazione	No
Operazioni batch	Varia in base all'operazione	No

¹ Per eseguire questa operazione utilizzando gli endpoint di località, il bucket contenente l'oggetto interessato deve esistere nella località specificata dall'endpoint. Ad esempio, una richiesta di eliminazione di un oggetto a us-central1-storage.googleapis.com può essere utilizzata solo per eliminare oggetti in bucket che si trovano nella regione US-CENTRAL1. Se provi a eliminare un oggetto in una località diversa da US-CENTRAL1, l'operazione restituisce un errore NOT_FOUND.

² Per eseguire questa operazione utilizzando gli endpoint di localizzazione, il bucket deve esistere nella posizione specificata dall'endpoint. Ad esempio, una richiesta di creazione di un bucket per us-central1-storage.googleapis.com può essere utilizzata solo per creare un bucket nella regione US-CENTRAL1. Se provi a creare il bucket in una località diversa da US-CENTRAL1, l'operazione restituisce un errore INVALID_ARGUMENT.

³ Per eseguire questa operazione utilizzando gli endpoint di localizzazione, il bucket deve esistere nella località specificata dall'endpoint. Ad esempio, una richiesta di eliminazione di un bucket a us-central1-storage.googleapis.com può essere utilizzata solo per eliminare un bucket nella regione US-CENTRAL1. Se provi a eliminare un bucket in una località diversa da US-CENTRAL1, l'operazione restituisce un errore NOT_FOUND.

⁴ Per eseguire questa operazione utilizzando gli endpoint di località, i bucket di origine e di destinazione devono esistere entrambi nella località specificata dall'endpoint. Ad esempio, puoi utilizzare gli endpoint di località per copiare un oggetto da un bucket a un altro se entrambi i bucket si trovano nella stessa località. Tuttavia, non puoi utilizzare gli endpoint di località per copiare un oggetto da un bucket a un altro se i bucket si trovano in località diverse. Se il bucket di origine o di destinazione si trova in una località diversa da quella specificata dall'endpoint, l'operazione restituisce un errore NOT_FOUND.

Aree geografiche supportate

Gli endpoint di località sono supportati per tutte le regioni degli Stati Uniti, la multi-regione US e la regione a due regioni predefinita NAM4. Per saperne di più sulle regioni che possono essere specificate, consulta Località dei bucket.

Effettuare richieste

Console

Per mantenere la conformità alle ITAR, è tua responsabilità utilizzare la console Google Cloud per le giurisdizioni. Per saperne di più, consulta il pacchetto di controllo ITAR per Cloud Storage.

Riga di comando

Per configurare Google Cloud CLI per l'utilizzo con gli endpoint di località:

1. Imposta la proprietà api_endpoint_overrides/storage sull'endpoint di località che vuoi utilizzare:

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

Una volta impostata questa proprietà, puoi utilizzare i comandi gcloud CLI come faresti normalmente.

In alternativa, puoi utilizzare endpoint basati sulla posizione per singoli comandi impostando la variabile di ambiente CLOUDSDK_API_ENDPOINT_OVERRIDES_STORAGE in ogni comando. Ad esempio:

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

Librerie client

Le librerie client di Cloud Storage gestiscono automaticamente gli endpoint delle richieste, ma puoi impostare manualmente gli endpoint di località. Per scoprire come impostare gli endpoint di località, consulta gli esempi di codice della libreria client che utilizzano gli endpoint di richiesta.

API REST

API JSON

Quando effettui richieste agli endpoint di localizzazione, utilizza i seguenti URI:

• Per le richieste API JSON generali, esclusi i caricamenti di oggetti, utilizza il seguente endpoint:

  https://LOCATION-storage.googleapis.com

  Sostituisci LOCATION con una località del bucket supportata. Ad esempio, us-central1.

• Per i caricamenti di oggetti API JSON, utilizza il seguente endpoint:

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

  Sostituisci:

  • LOCATION con una posizione del bucket supportata. Ad esempio, us-central1.

  • BUCKET_NAME con il nome del bucket in cui vuoi caricare un oggetto. Ad esempio, my-example-bucket.

• Per i download di oggetti API JSON, utilizza il seguente endpoint:

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

  Sostituisci:

  • LOCATION con una località del bucket supportata. Ad esempio, us-central1.

  • BUCKET_NAME con il nome del bucket che contiene l'oggetto da scaricare. Ad esempio, my-example-bucket.

  • OBJECT_NAME con il nome dell'oggetto che vuoi scaricare. Ad esempio, waterfall.png.

Tieni presente che gli endpoint dell'API JSON supportano solo le richieste HTTPS.

API XML

Quando utilizzi l'API XML per effettuare richieste agli endpoint locali, puoi utilizzare un endpoint in stile host virtuale o un endpoint in stile percorso:

• Endpoint di stile con hosting virtuale:

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

• Endpoint in stile percorso:

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

Per entrambi i tipi di endpoint, sostituisci:

• LOCATION con una località del bucket supportata. Ad esempio, us-central1.

• BUCKET_NAME con un nome bucket valido. Ad esempio, my-example-bucket.

Nota: gli endpoint in stile host virtuale non possono essere utilizzati per accedere ai bucket con nome di dominio. Utilizza invece endpoint in stile percorso o un reindirizzamento.

Gli endpoint dell'API XML supportano la crittografia SSL (Secure Sockets Layer), il che significa che puoi utilizzare HTTP o HTTPS. L'utilizzo di HTTPS è consigliato, soprattutto se esegui l'autenticazione in Cloud Storage utilizzando OAuth 2.0.

Formattare correttamente le richieste

Per assicurarti che le tue richieste siano compatibili con gli strumenti di Cloud Storage:

• Assicurati di codificare correttamente i caratteri speciali che compaiono nel nome dell'oggetto o nella stringa di query di un URI della richiesta.

• Acquisisci familiarità con le considerazioni sulla denominazione dei bucket e sulla denominazione degli oggetti.

Vincoli noti

Gli endpoint mTLS non sono supportati.

Limitazione dell'utilizzo degli endpoint API globali

Per contribuire a imporre l'utilizzo di endpoint di località, puoi utilizzare il vincolo delle policy dell'organizzazione constraints/gcp.restrictEndpointUsage per bloccare le richieste all'endpoint API globale. Per saperne di più, consulta la documentazione relativa alla limitazione dell'utilizzo degli endpoint.