Questa pagina descrive come utilizzare gli endpoint basati sulla località per accedere a Cloud Storage. Quando utilizzi endpoint basati sulla posizione, puoi assicurarti che i dati at-rest rimangano all'interno della giurisdizione per soddisfare i requisiti di residenza dei dati.
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 del 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 posizione diversa da quella in cui si trova la risorsa, gli endpoint di località garantiscono che le richieste vengano elaborate solo all'interno della località specificata dall'endpoint, in cui si trova la risorsa.
L'utilizzo di endpoint basati sulla posizione garantisce che:
I dati archiviati in Cloud Storage non escono dalla posizione specificata.
I tuoi dati vengono terminati con TLS nella regione specificata dall'endpoint durante il transito da on-premise a Google Cloud.
Quando utilizzi endpoint localizzati, ti assumi le seguenti responsabilità:
Per ottenere garanzie di residenza dei dati, le richieste effettuate a un endpoint basato sulla località devono provenire dalla stessa località specificata dall'endpoint. Ad esempio, se utilizzi una macchina virtuale Compute Engine per eseguire una richiesta a un bucket che si trova in
US-CENTRAL1tramite l'endpointus-central1-storage.googleapis.com, anche la macchina virtuale deve trovarsi inUS-CENTRAL1.Gli endpoint di localizzazione devono essere utilizzati solo durante l'esecuzione di operazioni supportate. L'esecuzione di operazioni non supportate genera un errore.
Gli endpoint localizzati supportano il traffico tra on-premise e Google Cloud tramite Interconnect o VPN e il traffico tra servizi Google Cloud (ad esempio, da BigQuery a Cloud Storage). Il traffico internet non è supportato.
Operazioni supportate
La seguente tabella riassume le operazioni che possono e non possono essere eseguite con gli endpoint regionali. In generale, le operazioni all'interno della stessa località possono essere eseguite con endpoint basati sulla posizione, mentre quelle tra località diverse non possono.
Se tenti di eseguire un'operazione non supportata utilizzando un endpoint geografico, 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 basati sulla posizione |
|---|---|---|
| gli oggetti compongono | Sì | Sì1 |
| eliminazione di oggetti | No | Sì1 |
| objects get | Sì | Sì1 |
| inserimento di oggetti | Sì | Sì1 |
| elenco degli oggetti | No | Sì1 |
| patch degli oggetti | No | Sì1 |
| copia degli oggetti | Sì | Sì4 |
| riscrittura degli oggetti | Sì | Sì4 |
| inserto per secchi | 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 |
| bucket BucketAccessControls | No | Sì2 |
| buckets DefaultObjectAccessControls | No | Sì2 |
| buckets ObjectAccessControls | No | Sì2 |
| Operazioni con le chiavi HMAC | No | No |
| Operazioni dell'account di servizio | No | No |
| Operazioni di notifica Pub/Sub | Varia in base all'operazione | No |
| Operazioni di notifica di modifica degli oggetti | Varia in base all'operazione | No |
| Operazioni batch | Varia in base all'operazione | No |
1 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 oggetti a us-central1-storage.googleapis.com può essere utilizzata solo per eliminare oggetti nei bucket che si trovano nella regione US-CENTRAL1. Se provi a eliminare un oggetto
in una posizione diversa da US-CENTRAL1, l'operazione restituisce un errore NOT_FOUND.
2 Per eseguire questa operazione utilizzando gli endpoint di località, il bucket
deve esistere nella località specificata dall'endpoint. Ad esempio, una richiesta di creazione di un bucket
a 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.
3 Per eseguire questa operazione utilizzando gli endpoint di localizzazione, il bucket
deve esistere nella posizione 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à
che non è US-CENTRAL1, l'operazione restituisce un errore NOT_FOUND.
4 Per eseguire questa operazione utilizzando endpoint basati sulla posizione, i bucket di origine e di destinazione devono esistere nella posizione specificata dall'endpoint. Ad esempio, puoi utilizzare gli endpoint basati sulla località per copiare un oggetto da
un bucket a un altro se entrambi i bucket si trovano nella stessa località. Tuttavia, non puoi utilizzare endpoint basati sulla località per copiare un oggetto da un bucket a un altro se i bucket si trovano in posizioni diverse. Se il bucket di origine o di destinazione
si trova in una posizione diversa da quella specificata dall'endpoint, l'operazione restituisce un errore NOT_FOUND.
Aree geografiche supportate
Gli endpoint basati sulla località sono supportati per tutte le regioni degli Stati Uniti, per la multiregione US e per la doppia regione predefinita NAM4. Per saperne di più sulle regioni
che possono essere specificate, consulta Località dei bucket.
Effettuare richieste
Console
Consulta Restrizioni e limitazioni per l'ITAR per informazioni su come eseguire operazioni utilizzando la console Google Cloud in modo conforme all'ITAR.
Riga di comando
Per configurare Google Cloud CLI per l'utilizzo con endpoint localizzati:
Imposta la proprietà
api_endpoint_overrides/storagesull'endpoint di localizzazione 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 di consueto.
In alternativa, puoi utilizzare gli endpoint di localizzazione per i 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 localizzazione, 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 generali dell'API JSON, esclusi i caricamenti di oggetti, utilizza il seguente endpoint:
https://LOCATION-storage.googleapis.com
Sostituisci LOCATION con una posizione 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 località 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 che vuoi 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 basati sulla località, 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.
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 garantire che le richieste siano compatibili con gli strumenti Cloud Storage:
Assicurati di codificare correttamente i caratteri speciali che compaiono nel nome dell'oggetto o nella stringa di query di un URI di richiesta.
Acquisisci familiarità con la denominazione dei bucket e con le considerazioni sulla denominazione degli oggetti.
Vincoli noti
Non è disponibile il supporto per gli endpoint mTLS.
Limitazione dell'utilizzo dell'endpoint API globale
Per contribuire a imporre l'utilizzo di endpoint locali, puoi utilizzare il vincolo delle policy dell'organizzazione constraints/gcp.restrictEndpointUsage per bloccare le richieste all'endpoint API globale. Per ulteriori informazioni, consulta la documentazione
Limitare l'utilizzo degli endpoint.