Ya está disponible la edición Enterprise de Cloud Firestore con compatibilidad con MongoDB. Obtén más información.

Autentícate en una base de datos y conéctate a ella

Solo es pertinente para la edición Enterprise de Cloud Firestore.

Requisitos de conexión

Se requieren los siguientes elementos para los clientes de Cloud Firestore con compatibilidad con MongoDB:

Los controladores deben conectarse en modo load balanced. Esto evita que estos intenten comprender la topología exacta del servidor al que se conectan.
Los controladores deben conectarse con SSL habilitado.
Los controladores deben inhabilitar las escrituras que se pueden reintentar. Actualmente, Cloud Firestore con compatibilidad con MongoDB no admite escrituras que se pueden reintentar. No es necesario que inhabilites las lecturas reintentables, ya que son compatibles.

Recupera la cadena de conexión

La cadena de conexión de la base de datos depende del UID de la base de datos, la ubicación de la base de datos y el mecanismo de autenticación. En las siguientes instrucciones, se describe cómo se forma la cadena de conexión.

La cadena de conexión exacta depende del mecanismo de autenticación, pero la cadena de conexión base usa el siguiente formato:

mongodb://UID.LOCATION.firestore.goog:443/DATABASE_ID?loadBalanced=true&tls=true&retryWrites=false

Puedes obtener la cadena de conexión base de una de las siguientes maneras:

Consola de Firebase

En la consola Firebase, ve a la página Base de datos de Firestore:

Ir a la base de datos de Firestore
Haz clic en la base de datos que deseas autenticar.
En el panel Explorador, haz clic en Ver más.
Selecciona Conectarse con las herramientas de MongoDB.
Copia la cadena de conexión.

gcloud

Usa gcloud firestore database describe para recuperar el UID y la información de ubicación:

gcloud firestore databases describe \
--database=DATABASE_ID \
--format='yaml(locationId, uid)'

Reemplaza DATABASE_ID por el ID de la base de datos.

El resultado incluye la ubicación y el UID de la base de datos. Usa esta información para construir la cadena de conexión base.

Usa la cadena de conexión base y uno de los siguientes métodos para autenticarte en tu base de datos y conectarte a ella:

Nombre de usuario y contraseña (SCRAM)
Cuenta de servicio de Compute Engine
Cuenta de servicio de Cloud Run
Biblioteca de Google Auth

Conéctate con nombre de usuario y contraseña (SCRAM)

Sigue estos pasos para crear una credencial de usuario para tu base de datos y conectarte a ella.

Antes de comenzar

Para obtener los permisos que necesitas para crear un usuario, pídele a tu administrador que te otorgue el rol de IAM userCredsAdmin (roles/datastore.userCredsAdmin) en tu base de datos. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios a través de roles personalizados o cualquier otro rol predefinido.

Crea un usuario y conéctate a una base de datos

Para crear un usuario para tu base de datos de Cloud Firestore con compatibilidad con MongoDB, usa uno de los siguientes métodos:

Consola de Google Cloud

En la consola de Google Cloud, ve a la página Bases de datos.

Ir a Bases de datos
Selecciona una base de datos de la lista.
En el menú de navegación, haz clic en Auth.
Haz clic en Agregar usuario.
Ingresa un Nombre de usuario.
Selecciona un rol para el usuario nuevo.
Haz clic en Agregar.
La contraseña del usuario nuevo se mostrará en el diálogo de confirmación.

Precaución: La contraseña se muestra una sola vez y no se puede recuperar. Almacena esta contraseña para usarla más adelante.

gcloud CLI

Para autenticarte con SCRAM, primero debes crear una credencial de usuario. Usa el comando gcloud alpha firestore user-creds:
```
gcloud alpha firestore user-creds create USERNAME --database=DATABASE_ID
```
Reemplaza lo siguiente:
- USERNAME: Es el nombre de usuario que se creará.
- DATABASE_ID: Es el ID de la base de datos.
El resultado de este comando incluye la contraseña del usuario.

Precaución: La contraseña se muestra una sola vez y no se puede recuperar. Almacena esta contraseña para usarla más adelante.

El resultado se ve de la manera siguiente:
```
name: projects/PROJECT_NAME/databases/DATABASE_ID/userCreds/USERNAME
resourceIdentity:
  principal: principal://firestore.googleapis.com/projects/PROJECT_NUMBER/name/databases/DATABASE_ID/userCreds/USERNAME
securePassword: PASSWORD
```
De forma predeterminada, esta nueva credencial de usuario no tiene permisos. Para obtener acceso de lectura y escritura a la base de datos, agrega el rol roles/datastore.user para esta base de datos específica:
```
gcloud projects add-iam-policy-binding PROJECT_NAME \
--member='principal://firestore.googleapis.com/projects/PROJECT_NUMBER/name/databases/DATABASE_ID/userCreds/USERNAME' \
--role=roles/datastore.user \
--condition='expression=resource.name == "projects/PROJECT_NAME/databases/DATABASE_ID",title="CONDITION_TITLE"'
```
Reemplaza lo siguiente:
- PROJECT_NAME: nombre del proyecto.
- PROJECT_NUMBER: Es el número del proyecto.
- DATABASE_ID: Es el ID de la base de datos.
- USERNAME: Es el nombre de usuario que creaste anteriormente.
- CONDITION_TITLE: Es un título para esta condición. Esta condición restringe el acceso solo a esta base de datos.

Java

En esta sección, se proporciona un ejemplo de código para crear credenciales de usuario y configurar la política de IAM con las bibliotecas cliente administrativas de Java. En el ejemplo, se usa la biblioteca Cliente de administrador de Firestore para crear un nombre de usuario y una contraseña, y la biblioteca Google Cloud Resource Manager para configurar IAM.

Para las compilaciones de Maven, puedes usar las siguientes coordenadas:

com.google.cloud:google-cloud-firestore-admin:3.33.1
com.google.cloud:google-cloud-resourcemanager:1.76.0

Aprovisiona credenciales de usuario y una política de IAM:

import com.google.cloud.firestore.v1.FirestoreAdminClient;
import com.google.cloud.resourcemanager.v3.ProjectName;
import com.google.cloud.resourcemanager.v3.ProjectsClient;
import com.google.firestore.admin.v1.CreateUserCredsRequest;
import com.google.firestore.admin.v1.GetUserCredsRequest;
import com.google.firestore.admin.v1.UserCreds;
import com.google.iam.v1.Binding;
import com.google.iam.v1.GetIamPolicyRequest;
import com.google.iam.v1.GetPolicyOptions;
import com.google.iam.v1.Policy;
import com.google.iam.v1.SetIamPolicyRequest;
import com.google.protobuf.FieldMask;
import com.google.type.Expr;

public class FirestoreUserCredsExample {
  /**
   * Provision user credentials and configure an IAM policy to allow SCRAM authentication into the
   * specified Firestore with Mongo Compatibility database.
   */
  private static void provisionFirestoreUserCredsAndIAM(
      String projectId, String databaseId, String userName) throws Exception {
    UserCreds userCreds = createUserCreds(projectId, databaseId, userName);

    // Note the password returned in the UserCreds proto - it cannot be retrieved again
    // after the initial call to the createUserCreds API.
    System.out.printf(
        "Created credentials for username: %s:\nIAM principal: %s\nPassword: [%s]\n",
        userName, userCreds.getResourceIdentity().getPrincipal(), userCreds.getSecurePassword());

    // Provision an IAM binding for the principal associated with these user credentials.
    updateIamPolicyForUserCreds(projectId, databaseId, userName, userCreds);

    // Emit the password again.
    System.out.printf(
        "Successfully configured IAM policy for database: %s, username: %s\n",
        databaseId, userName);
    System.out.printf("Please make a note of the password: [%s]\n", userCreds.getSecurePassword());
  }

  /** Provision new user credentials using the FirestoreAdminClient. */
  private static UserCreds createUserCreds(String projectId, String databaseId, String userName)
      throws Exception {
    FirestoreAdminClient firestoreAdminClient = FirestoreAdminClient.create();
    return firestoreAdminClient.createUserCreds(
        CreateUserCredsRequest.newBuilder()
            .setParent(String.format("projects/%s/databases/%s", projectId, databaseId))
            .setUserCredsId(userName)
            .build());
  }

  /** Update the IAM policy using the Resource Manager ProjectsClient. */
  private static void updateIamPolicyForUserCreds(
      String projectId, String databaseId, String userName, UserCreds userCreds) throws Exception {
    try (ProjectsClient projectsClient = ProjectsClient.create()) {
      ProjectName projectName = ProjectName.of(projectId);

      // Get the current IAM policy.
      Policy currentPolicy =
          projectsClient.getIamPolicy(
              GetIamPolicyRequest.newBuilder()
                  .setResource(projectName.toString())
                  .setOptions(GetPolicyOptions.newBuilder().setRequestedPolicyVersion(3).build())
                  .build());

      String role = "roles/datastore.user";
      String title = String.format("Conditional IAM binding for %s", userName);
      String expression =
          String.format("resource.name == \"projects/%s/databases/%s\"", projectId, databaseId);

      // Construct an updated IAM policy with an additional binding for the user credentials.
      Policy.Builder policyBuilder = currentPolicy.toBuilder();
      Binding newBinding =
          Binding.newBuilder()
              .setRole(role)
              .setCondition(Expr.newBuilder().setTitle(title).setExpression(expression).build())
              .addMembers(userCreds.getResourceIdentity().getPrincipal())
              .build();
      policyBuilder.addBindings(newBinding);

      // Update the policy
      SetIamPolicyRequest request =
          SetIamPolicyRequest.newBuilder()
              .setResource(projectName.toString())
              .setPolicy(policyBuilder.build())
              .setUpdateMask(FieldMask.newBuilder().addPaths("bindings").addPaths("etag").build())
              .build();
      System.out.println(request);

      Policy updatedPolicy = projectsClient.setIamPolicy(request);
      System.out.println("Policy updated successfully: " + updatedPolicy);
    }
  }
}

Usa la siguiente cadena de conexión para conectarte a tu base de datos con SCRAM:

mongodb://USERNAME:PASSWORD@UID.LOCATION.firestore.goog:443/DATABASE_ID?loadBalanced=true&authMechanism=SCRAM-SHA-256&tls=true&retryWrites=false

Reemplaza lo siguiente:

USERNAME: el nombre de usuario
PASSWORD: Es la contraseña que generaste para este usuario.
UID: Es el UID de la base de datos.
LOCATION: Es la ubicación de la base de datos.
DATABASE_ID: Es el ID de la base de datos.

Conéctate con la biblioteca de Google Auth

En la siguiente muestra de código, se registra un controlador de devolución de llamada de OIDC que usa la biblioteca OAuth estándar de Google Cloud.

Esta biblioteca te permite usar varios tipos diferentes de autenticación (credenciales predeterminadas de la aplicación, Federación de identidades para cargas de trabajo).

Esto requiere agregar la biblioteca de autenticación como una dependencia:

// Maven
<dependency>
  <groupId>com.google.auth</groupId>
  <artifactId>google-auth-library-oauth2-http</artifactId>
  <version>1.19.0</version>
</dependency>

// Gradle
implementation 'com.google.auth:google-auth-library-oauth2-http:1.19.0'

En la siguiente muestra de código, se muestra cómo conectarse:

val db = MongoClients.create(
    clientSettings(
      "DATABASE_UID",
      "LOCATION"
    ).build()
  ).getDatabase("DATABASE_ID")


/**
 * Creates a connection to a Firestore with MongoDB Compatibility database.
 * @param databaseUid The uid of the database to connect to as a string. For example: f116f93a-519c-208a-9a72-3ef6c9a1f081
 * @param locationId The location of the database to connect to, for example: nam5, us-central1, us-east4 etc...
 * @param environment Determines whether to try and fetch an authentication credential from the
 * Compute Engine VM metadata service or whether to call gcloud.
 */
private static MongoClientSettings.Builder clientSettings(
  String databaseUid: String
  String locationId:String
): MongoClientSettings.Builder {
  MongoCredential credential =
    MongoCredential.createOidcCredential(null)
      .withMechanismProperty(
        MongoCredential.OIDC_CALLBACK_KEY,
        new MongoCredential.OidcCallback() {
          @Override
          MongoCredential.OidcCallbackResult onRequest(
MongoCredential.OidcCallbackContext context) {
     // Customize this credential builder for additional credential types.
     GoogleCredentials credentials = GoogleCredentials.getApplicationDefault();
            return new MongoCredential.OidcCallbackResult(
         credentials.getAccessToken().getTokenValue(),
         Duration.between(Instant.now(),
credentials.getAccessToken().getExpirationTime().toInstant()));
          }
        },
      );
  return MongoClientSettings.builder()
    .hosts(listOf(ServerAddress(
        "$databaseUid.$locationId.firestore.goog", 443)))
    .credential(credential)
    .applyToClusterSettings(builder ->
         builder.mode(ClusterConnectionMode.LOAD_BALANCED))
    ).applyToSslSettings(ssl -> ssl.enabled(true)).retryWrites(false);
}

Reemplaza lo siguiente:

DATABASE_UID: nombre del proyecto.
LOCATION: Es la ubicación de tu base de datos.
DATABASE_ID: Es el ID de la base de datos.

Conéctate desde un entorno de procesamiento de Google Cloud

En esta sección, se describe cómo conectarse a Cloud Firestore con compatibilidad con MongoDB desde un entorno de procesamiento de Google Cloud, como Compute Engine o un servicio o trabajo de Cloud Run.

Conéctate desde una VM de Compute Engine

Puedes autenticarte y conectarte a tu base de datos con una cuenta de servicio de Compute Engine. Para ello, crea una política de IAM para el proyecto Google Cloud que contiene tu base de datos.

Antes de comenzar

Configura una cuenta de servicio administrada por el usuario para tu VM:

Para configurar la cuenta de servicio durante la creación de la VM, consulta Crea una VM que use una cuenta de servicio administrada por el usuario.
Para configurar una cuenta de servicio en una VM existente, consulta Cambia la cuenta de servicio conectada.

Consulta las instrucciones en las secciones Configura las credenciales para completar la configuración de la política de IAM de tu cuenta de servicio de Compute Engine.

Conéctate desde Cloud Run

Puedes autenticarte y conectarte a tu base de datos con una cuenta de servicio de Cloud Run. Para ello, crea una política de IAM para el proyecto Google Cloud que contiene tu base de datos.

Antes de comenzar

Para configurar la cuenta de servicio de Cloud Run, consulta Configura la identidad del servicio.
Para determinar la cuenta de servicio que ya está asociada con tu servicio de Cloud Run, consulta gcloud run services describe.

Consulta las instrucciones en las secciones Configura las credenciales para completar la configuración de la política de IAM de tu cuenta de servicio de Cloud Run.

Configura las credenciales

Para otorgar a la cuenta de servicio el rol roles/datastore.user para leer y escribir en Cloud Firestore, ejecuta el siguiente comando:

gcloud projects add-iam-policy-binding PROJECT_NAME --member="SERVICE_ACCOUNT_EMAIL" --role=roles/datastore.user

Reemplaza lo siguiente:

PROJECT_NAME: nombre del proyecto.
SERVICE_ACCOUNT_EMAIL: Es la dirección de correo electrónico de la cuenta de servicio que creaste.

Construye la cadena de conexión

Usa el siguiente formato para crear el cadena de conexión:

mongodb://DATABASE_UID.LOCATION.firestore.goog:443/DATABASE_ID?loadBalanced=true&tls=true&retryWrites=false&authMechanism=MONGODB-OIDC&authMechanismProperties=ENVIRONMENT:gcp,TOKEN_RESOURCE:FIRESTORE

Reemplaza lo siguiente:

DATABASE_UID: nombre del proyecto.
LOCATION: Es la ubicación de tu base de datos.
DATABASE_ID: Es el ID de la base de datos.

Para obtener más información sobre cómo recuperar el UID y la ubicación, consulta Cómo recuperar la cadena de conexión.

Conéctate con un token de acceso temporal

Puedes usar un token de acceso temporal de Google Cloud para ejecutar herramientas de diagnóstico, como mongosh. Puedes usar gcloud auth print-access-token para autenticarte con un token de acceso a corto plazo. Este token es válido durante una hora.

Por ejemplo, usa el siguiente comando para conectarte a tu base de datos con mongosh:

mongosh --tls \
      --username access_token --password $(gcloud auth print-access-token) \
      'mongodb://UID.LOCATION.firestore.goog:443/DATABASE_ID?loadBalanced=true&authMechanism=PLAIN&authSource=$external&retryWrites=false'

Reemplaza lo siguiente:

DATABASE_UID: Es el UID de la base de datos.
LOCATION: Es la ubicación de la base de datos.
DATABASE_ID: Es un ID de base de datos.

Autentícate en una base de datos y conéctate a ella Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.

Requisitos de conexión

Recupera la cadena de conexión

Consola de Firebase

gcloud

Conéctate con nombre de usuario y contraseña (SCRAM)

Antes de comenzar

Crea un usuario y conéctate a una base de datos

Consola de Google Cloud

gcloud CLI

Java

Conéctate con la biblioteca de Google Auth

Conéctate desde un entorno de procesamiento de Google Cloud

Conéctate desde una VM de Compute Engine

Antes de comenzar

Conéctate desde Cloud Run

Antes de comenzar

Configura las credenciales

Construye la cadena de conexión

Conéctate con un token de acceso temporal

Autentícate en una base de datos y conéctate a ella