Questa pagina descrive come utilizzare gli endpoint geografici per accedere a Cloud Storage. Gli endpoint posizione ti consentono di eseguire i tuoi carichi di lavoro in modo conforme alle norme ITAR (International Traffic in Arms Regulations).
Per informazioni sulle limitazioni relative all'utilizzo di Cloud Storage in modo conforme alle ITAR, consulta Restrizioni e limitazioni per le ITAR.
Panoramica
Gli endpoint posizione 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 località diversa da quella in cui si trova la risorsa, gli endpoint basati sulla posizione garantiscono che le richieste vengano elaborate solo all'interno della località specificata dall'endpoint, dove si trova la risorsa. Quando utilizzi gli endpoint geografici, puoi assicurarti che i dati at-rest e in transito rimangano all'interno della giurisdizione per soddisfare i requisiti di residenza dei dati.
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 passaggio da on-premise a Google Cloud.
I tuoi dati rimangono nella giurisdizione durante il transito tra i servizi. Google Cloud
Quando utilizzi gli endpoint posizione, ti assumi le seguenti responsabilità:
Per ottenere garanzie sulla residenza dei dati, le richieste inviate a un endpoint geografico devono provenire dalla stessa località specificata dall'endpoint. Ad esempio, se utilizzi una VM Compute Engine per eseguire una richiesta a un bucket in
US-CENTRAL1tramite l'endpointus-central1-storage.googleapis.com, anche la VM deve trovarsi inUS-CENTRAL1.Gli endpoint posizione devono essere utilizzati solo quando vengono eseguite operazioni supportate. L'esecuzione di operazioni non supportate comporta un errore.
Gli endpoint geografici supportano il traffico in transito tra on-premise eGoogle Cloud tramite Interconnect o VPN, nonché il traffico in transito tra i serviziGoogle 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 posizione. In generale, le operazioni all'interno di una stazione di ricarica possono essere eseguite con endpoint di località, mentre le operazioni tra stazioni di ricarica 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 dell'oggetto | Supportato per l'utilizzo con endpoint posizione |
|---|---|---|
| oggetti componi | Sì | Sì1 |
| oggetti eliminati | No | Sì1 |
| oggetti get | Sì | Sì1 |
| oggetti insert | Sì | Sì1 |
| elenco di oggetti | No | Sì1 |
| patch degli oggetti | No | Sì1 |
| oggetti copia | Sì | Sì4 |
| riscrivi oggetti | Sì | Sì4 |
| insert buckets | 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 |
| buckets BucketAccessControls | No | Sì2 |
| bucket DefaultObjectAccessControls | No | Sì2 |
| buckets ObjectAccessControls | No | Sì2 |
| Operazioni con le chiavi HMAC | No | No |
| Operazioni degli 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 collettive | Varia in base all'operazione | No |
1 Per eseguire questa operazione utilizzando endpoint posizione, il bucket contenente l'oggetto interessato deve esistere nella posizione specificata dall'endpoint. Ad esempio, una richiesta di eliminazione di oggetti in us-central1-storage.googleapis.com può essere utilizzata solo per eliminare gli 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 posizione, 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 posizione diversa da US-CENTRAL1, l'operazione restituisce un errore INVALID_ARGUMENT.
3 Per eseguire questa operazione utilizzando gli endpoint posizione, il bucket deve esistere nella posizione specificata dall'endpoint. Ad esempio, una richiesta di eliminazione di un bucket in 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.
4 Per eseguire questa operazione utilizzando gli endpoint posizione, i bucket di origine e di destinazione devono esistere entrambi nella posizione specificata dall'endpoint. Ad esempio, puoi utilizzare gli endpoint relativi alla posizione per copiare un oggetto da un bucket all'altro se entrambi i bucket si trovano nella stessa posizione. Tuttavia, non puoi utilizzare gli endpoint posizione per copiare un oggetto da un bucket all'altro se i bucket esistono in posizioni diverse. Se il bucket di origine o di destinazione esiste in una posizione diversa da quella specificata dall'endpoint, l'operazione restituisce un errore NOT_FOUND.
Aree geografiche supportate
Gli endpoint posizione sono supportati per tutte le regioni degli Stati Uniti, la regione US multipla
e la regione a due regioni predefinita NAM4. Per ulteriori informazioni sulle regioni che possono essere specificate, consulta Località dei bucket.
Invio di richieste
Console
Consulta la sezione Restrizioni e limitazioni per le ITAR per informazioni su come eseguire operazioni utilizzando la console Google Cloud in modo conforme alle ITAR.
Riga di comando
Per configurare Google Cloud CLI per l'utilizzo con endpoint geografici:
Imposta la proprietà
api_endpoint_overrides/storagesull'endpoint di geolocalizzazione 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 posizione per singoli comandi impostando la CLOUDSDK_API_ENDPOINT_OVERRIDES_STORAGEvariabile di ambiente
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 geografici. Per scoprire come impostare gli endpoint geografici, consulta gli esempi di codice della libreria client che utilizzano gli endpoint di richiesta.
API REST
API JSON
Quando invii richieste agli endpoint relativi alla posizione, 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 dell'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 inviare richieste agli endpoint di località, puoi utilizzare un endpoint in stile virtuale ospitato o un endpoint in stile percorso:
Endpoint dello stile con hosting virtuale:
https://BUCKET_NAME.LOCATION-storage.googleapis.com
Endpoint con 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), pertanto puoi utilizzare HTTP o HTTPS. È consigliabile utilizzare HTTPS, 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 tutti 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
Gli endpoint mTLS non sono supportati.