Endpoint di localizzazione

In questa pagina viene descritto come utilizzare gli endpoint locali per accedere a Cloud Storage. Quando utilizzi gli endpoint locali, puoi assicurarti che i dati inattivi rimangano all'interno della giurisdizione per soddisfare i requisiti di residenza dei dati.

Panoramica

Gli endpoint locali sono endpoint di richiesta che consentono l'elaborazione delle richieste solo se la risorsa interessata esiste nella località specificata dall'endpoint. Ad esempio, quando utilizzi l'endpoint https://us-central1-storage.googleapis.com in una richiesta di eliminazione del bucket, la richiesta viene elaborata 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 risiede la risorsa, gli endpoint locali garantiscono che le richieste vengano elaborate solo all'interno della località specificata dall'endpoint, in cui risiede la risorsa.

L'utilizzo di endpoint locali garantisce che:

I dati archiviati in Cloud Storage non lasciano la località specificata.
I dati vengono terminati con TLS nella regione specificata dall'endpoint durante il transito da on-premise a. Google Cloud

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

Per ottenere garanzie di residenza dei dati, le richieste effettuate a un endpoint locale devono provenire dalla stessa località specificata dall'endpoint. Ad esempio, se utilizzi una macchina virtuale Compute Engine per eseguire una richiesta a un bucket residente in US-CENTRAL1 tramite l'endpoint us-central1-storage.googleapis.com, anche la macchina virtuale deve risiedere in US-CENTRAL1.
Gli endpoint locali devono essere utilizzati solo quando si eseguono operazioni supportate. L'esecuzione di operazioni non supportate genera un errore.

Gli endpoint locali supportano il traffico da on-premise a Google Cloud tramite Interconnect o VPN e il traffico tra i Google Cloud servizi (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 locali. In generale, le operazioni intra-località possono essere eseguite con gli endpoint locali, mentre le operazioni tra località non possono essere eseguite.

Se tenti di eseguire un'operazione non supportata utilizzando un endpoint locale, Cloud Storage restituisce un codice di errore HTTP 400 con il messaggio: "This endpoint does not implement this operation. Please use the global endpoint."

Operazione	Modifica i dati degli oggetti	Supportata per l'utilizzo con endpoint locali
objects compose	Sì	Sì¹
objects delete	No	Sì¹
objects get	Sì	Sì¹
objects insert	Sì	Sì¹
objects list	No	Sì¹
objects patch	No	Sì¹
objects copy	Sì	Sì⁴
objects rewrite	Sì	Sì⁴
buckets insert	No	Sì²
buckets delete	No	Sì³
buckets get	No	Sì²
buckets patch	No	Sì²
buckets update	No	Sì²
buckets getIamPolicy	No	Sì²
buckets setIamPolicy	No	Sì²
buckets testIamPermissions	No	Sì²
buckets lockRetentionPolicy	No	Sì²
buckets BucketAccessControls	No	Sì²
buckets DefaultObjectAccessControls	No	Sì²
buckets ObjectAccessControls	No	Sì²
Operazioni con le chiavi HMAC	No	No
Operazioni con gli account di servizio	No	No
Operazioni con le notifiche Pub/Sub	Varia in base all'operazione	No
Operazioni in batch	Varia in base all'operazione	No

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

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

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

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

Aree geografiche supportate

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

Effettuare richieste

Console

Per informazioni su come eseguire le operazioni utilizzando la Google Cloud console in modo conforme alle norme ITAR , consulta Limitazioni e restrizioni per le norme ITAR.

Riga di comando

Per configurare Google Cloud CLI per l'utilizzo con gli endpoint locali:

Imposta la proprietà api_endpoint_overrides/storage sull'endpoint locale 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 gli endpoint locali 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 di richiesta, ma puoi impostare manualmente gli endpoint locali. Per scoprire come impostare gli endpoint locali, consulta gli esempi di codice della libreria client che utilizzano gli endpoint di richiesta.

API REST

API JSON

Quando effettui richieste agli endpoint locali, 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 località 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 dell'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 locali, puoi utilizzare un endpoint di stile con hosting virtuale o un endpoint di stile con percorso:

Endpoint di stile con hosting virtuale:

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

Endpoint di stile con 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. È consigliabile utilizzare HTTPS, soprattutto se esegui l'autenticazione a Cloud Storage utilizzando OAuth 2.0.

Formattare correttamente le richieste

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

Assicurati di codificare correttamente i caratteri speciali che appaiono 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

Non è previsto il supporto per gli endpoint mTLS.

Limitazione dell'utilizzo degli endpoint API globali

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 saperne di più, consulta la documentazione relativa alla limitazione dell'utilizzo degli endpoint.