Configurar a localidade dos dados com endpoints locais

Nesta página, descrevemos como configurar as bibliotecas de cliente do Firestore para usar um endpoint regional.

Ao usar as bibliotecas de cliente do Firestore, você pode usar um dos seguintes endpoints:

  • Endpoint global: por padrão, as bibliotecas de cliente do Firestore enviam solicitações de API para um endpoint de serviço global chamado firestore.googleapis.com. O endpoint de serviço global roteia a solicitação para seu banco de dados. Durante o roteamento, uma solicitação pode passar por um endpoint de serviço de localização em um local diferente do local do banco de dados.

  • Endpoint de local: um endpoint de local impõe restrições regionais, garantindo que os dados sejam armazenados e tratados em uma região especificada. Para garantir que o endpoint de serviço processe as solicitações do Firestore do seu app na mesma região do banco de dados, especifique um endpoint de localização na biblioteca de cliente.

Definir um endpoint de local

Os exemplos a seguir mostram como definir um endpoint regional ao inicializar um cliente do Firestore. Definir um endpoint de local diferente de onde seus dados residem pode resultar em um erro PermissionDeniedError.

Java

Para autenticar no Firestore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.


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

Para autenticar no Firestore, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

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)

Semântica do endpoint de local

O Firestore é compatível com endpoints de local para locais regionais e multirregionais.

Use o seguinte formato para definir endpoints de local:

Java

  REGION_NAME-firestore.googleapis.com:443

Verifique se o número da porta está definido junto com o endpoint.

Python

  REGION_NAME-firestore.googleapis.com

Go

  REGION_NAME-firestore.googleapis.com:443

Verifique se o número da porta está definido junto com o endpoint.

Substitua REGION_NAME pelo nome de um nome do host regional ou multirregional.

Alguns exemplos de nomes de host:

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

Para uma lista completa de nomes de host multirregionais e regionais, consulte Locais do Firestore.

Restringir o uso de endpoints globais da API

Para ajudar a aplicar o uso de endpoints regionais, use a restrição de política da organização constraints/gcp.restrictEndpointUsage para bloquear solicitações ao endpoint de API global. Para mais informações, consulte Restringir o uso de endpoints.

A seguir