Configurar a localidade dos dados com endpoints regionais

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

Ao usar as bibliotecas de cliente do Firestore, é possível usar qualquer 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 servidor em um local diferente daquele do seu banco de dados.

  • Endpoint regional: um endpoint regional impõe restrições que garantem que os dados sejam transmitidos, armazenados e tratados em uma Google Cloud região específica. 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 regional na biblioteca de cliente.

  • Endpoint multirregional: um endpoint multirregional impõe restrições que garantem que os dados sejam transmitidos, armazenados e processados em uma Google Cloud multirregião especificada. Para garantir que o endpoint de serviço processe as solicitações do Firestore do seu app na mesma multirregião que o banco de dados, especifique um endpoint multirregional na biblioteca de cliente.

Definir um endpoint regional ou multirregional

O método para configurar um endpoint regional ou multirregional é o mesmo: você fornece a string do endpoint ao inicializar a biblioteca de cliente. Os exemplos a seguir mostram como definir a string de endpoint usando um endpoint regional (firestore.us-central1.rep.googleapis.com). Para usar um endpoint multirregional, forneça uma string de endpoint multirregional correspondente ao local do banco de dados (por exemplo, firestore.us.rep.googleapis.com para nam5).

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 firestore.us-central1.rep.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 = "firestore.africa-south1.rep.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 regional e multirregional

Endpoints regionais (REP):

O Firestore é compatível com endpoints regionais para os locais regionais listados aqui Locais do Firestore.

Use o seguinte formato para definir endpoints regionais:

Java

    firestore.REGION_NAME.rep.googleapis.com:443

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

Python

    firestore.REGION_NAME.rep.googleapis.com

Go

    firestore.REGION_NAME.rep.googleapis.com:443

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

Substitua REGION_NAME pelo nome de um hostname regional.

Alguns exemplos de nomes de host:

  • firestore.us-central1.rep.googleapis.com
  • firestore.europe-west1.rep.googleapis.com

Endpoints multirregionais (MREP)

Para endpoints multirregionais, use us nos locais nam5 e nam7, e eu no local eur3. Consulte Locais multirregionais.

Java

    firestore.us.rep.googleapis.com:443
    firestore.eu.rep.googleapis.com:443

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

Python

    firestore.us.rep.googleapis.com
    firestore.eu.rep.googleapis.com

Go

    firestore.us.rep.googleapis.com:443
    firestore.eu.rep.googleapis.com:443

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

Limitações

Endpoints de local (descontinuados)

Os endpoints de local foram descontinuados. Em vez disso, use endpoints regionais ou multirregionais.

Antes, o Firestore era compatível com endpoints locais no seguinte formato:

Java

  REGION_NAME-firestore.googleapis.com:443

Verifique se o número da porta está definido 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 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 de API globais

Para ajudar na aplicação do uso de endpoints regionais e multirregionais, utilize a restrição de políticas 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