Configura la località dei dati con gli endpoint basati sulla posizione

Questa pagina descrive come configurare le librerie client di Firestore per utilizzare un endpoint geografico.

Quando utilizzi le librerie client di Firestore, puoi utilizzare uno dei seguenti endpoint:

  • Endpoint globale: per impostazione predefinita, le librerie client di Firestore inviano richieste API a un endpoint di servizio globale denominato firestore.googleapis.com. L'endpoint di servizio globale instrada la richiesta al tuo database. Durante il routing, una richiesta potrebbe passare attraverso un endpoint del servizio di localizzazione in una località diversa da quella del tuo database.

  • Endpoint basato sulla località: un endpoint basato sulla località applica restrizioni regionali, garantendo che i dati vengano archiviati ed elaborati in una regione specificata. Per garantire che l'endpoint di servizio elabori le richieste Firestore della tua app nella stessa regione del database, specifica un endpoint di localizzazione nella libreria client.

Impostare un endpoint basato sulla posizione

Gli esempi riportati di seguito mostrano come impostare un endpoint geografico quando inizializzi un client Firestore. L'impostazione di un endpoint di localizzazione diverso da quello in cui risiedono i tuoi dati potrebbe generare un errore PermissionDeniedError.

Java

Per eseguire l'autenticazione in Firestore, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.


import com.google.auth.oauth2.GoogleCredentials;
import com.google.cloud.firestore.Firestore;
import com.google.cloud.firestore.FirestoreOptions;


/**
 * Demonstrate how to set a regional endpoint.
 */
public class RegionalEndpointSnippets {

  /**
   * Create a client with a regional endpoint.
   **/
  public Firestore regionalEndpoint(String projectId, String endpoint) throws Exception {
    FirestoreOptions firestoreOptions =
        FirestoreOptions.newBuilder()
            .setProjectId(projectId)
            .setCredentials(GoogleCredentials.getApplicationDefault())
            // set endpoint like nam5-firestore.googleapis.com:443
            .setHost(endpoint)
            .build();
    Firestore dbWithEndpoint = firestoreOptions.getService();

    return dbWithEndpoint;
  }

}

Python

Per eseguire l'autenticazione in Firestore, configura le Credenziali predefinite dell'applicazione. Per ulteriori informazioni, consulta Configura l'autenticazione per un ambiente di sviluppo locale.

ENDPOINT = "nam5-firestore.googleapis.com"
client_options = ClientOptions(api_endpoint=ENDPOINT)
db = firestore.Client(client_options=client_options)

cities_query = db.collection("cities").limit(2).get()
for r in cities_query:
    print(r)

Semantica degli endpoint basati sulla posizione

Firestore supporta endpoint di localizzazione per le località a livello di regione e di più regioni.

Utilizza il seguente formato per definire gli endpoint di localizzazione:

Java

  REGION_NAME-firestore.googleapis.com:443

Assicurati che il numero di porta sia definito insieme all'endpoint.

Python

  REGION_NAME-firestore.googleapis.com

Vai

  REGION_NAME-firestore.googleapis.com:443

Assicurati che il numero di porta sia definito insieme all'endpoint.

Sostituisci REGION_NAME con il nome di un nome host regionale o multiregionale.

Ecco alcuni esempi di nomi host:

  • eur3-firestore.googleapis.com
  • nam5-firestore.googleapis.com
  • europe-west6-firestore.googleapis.com
  • asia-northeast2-firestore.googleapis.com

Per un elenco completo dei nomi host multiregionali e regionali, consulta Località Firestore.

Limita l'utilizzo degli endpoint API globali

Per contribuire a imporre l'utilizzo di endpoint regionali, utilizza il vincolo del criterio dell'organizzazione constraints/gcp.restrictEndpointUsage per bloccare le richieste all'endpoint API globale. Per ulteriori informazioni, vedi Limitare l'utilizzo degli endpoint.

Passaggi successivi