Usa el SDK de Admin con Data Connect

El Firebase Admin SDK es un conjunto de bibliotecas de servidor que te permite interactuar con Firebase desde entornos privilegiados para realizar acciones como consultas y mutaciones en un servicio Firebase Data Connect para la administración masiva de datos y otras operaciones con privilegios elevados y credenciales suplantadas.

El Admin SDK te proporciona una API para llamar a operaciones en modos de lectura/escritura y de solo lectura. Con las operaciones de solo lectura, puedes implementar funciones administrativas que no pueden modificar los datos de tus bases de datos con la tranquilidad de que no se producirán cambios.

Configuración del SDK de Admin

Para comenzar a usar Firebase Data Connect en tu servidor, primero deberás instalar y configurar Admin SDK para Node.js.

Inicializa el SDK de Admin en tus secuencias de comandos

Para inicializar el SDK, importa las extensiones Data Connect y declara el ID y la ubicación del servicio de tu proyecto.


import { initializeApp } from 'firebase-admin/app';
import { getDataConnect } from 'firebase-admin/data-connect';

// If you'd like to use OAuth2 flows and other credentials to log in,
// visit https://firebase.google.com/docs/admin/setup#initialize-sdk
// for alternative ways to initialize the SDK.

const app = initializeApp();

const dataConnect = getDataConnect({
    serviceId: 'serviceId',
    location: 'us-west2'
});

Diseña consultas y mutaciones para usar con Admin SDK

El Admin SDK es útil para probar las operaciones de Data Connect, teniendo en cuenta las siguientes consideraciones.

Comprende el SDK y la directiva de operación @auth(level: NO_ACCESS)

Dado que Admin SDK opera con privilegios, puede ejecutar cualquiera de tus consultas y mutaciones, independientemente de los niveles de acceso establecidos con las directivas @auth, incluido el nivel NO_ACCESS.

Si, junto con tus operaciones del cliente, organizas tus consultas y mutaciones administrativas en archivos fuente .gql para importarlas en secuencias de comandos administrativas, Firebase te recomienda que marques las operaciones administrativas sin ningún nivel de acceso de autorización o, tal vez, que seas más explícito y las establezcas como NO_ACCESS. De cualquier manera, esto evita que dichas operaciones se ejecuten desde clientes o en otros contextos no privilegiados.

Usa el SDK con el emulador de Data Connect

En los entornos de prototipos y pruebas, puede ser útil realizar la creación de datos iniciales y otras operaciones en los datos locales. La marca Admin SDK te permite simplificar tus flujos de trabajo, ya que ignora la autenticación y la autorización para los flujos locales.

Los SDKs de Firebase Admin se conectan automáticamente al emulador de Data Connect cuando se establece la variable de entorno DATA_CONNECT_EMULATOR_HOST:

export DATA_CONNECT_EMULATOR_HOST="127.0.0.1:9399"

Para obtener más información, consulte:

Implementa casos de uso comunes

El Admin SDK se proporciona para operaciones privilegiadas en tus datos críticos.

El SDK de Admin proporciona dos interfaces:

  • Una interfaz general para la mayoría de las operaciones de lectura y escritura o de solo lectura, en la que tu código implementa consultas y mutaciones, y las pasa al método executeGraphql de lectura y escritura o al método executeGraphqlRead de solo lectura.
  • Es una interfaz especializada para operaciones de datos masivas que, en lugar de métodos executeGraphql genéricos, expone métodos específicos para operaciones de mutación: insert, insertMany, upsert y upsertMany.

Administra los datos del usuario con métodos executeGraphql

Un caso de uso típico de Admin SDK es la administración de datos del usuario.

Usa credenciales administrativas

El enfoque más directo es acceder a los datos del usuario con credenciales administrativas.

// User can be publicly accessible, or restricted to admins
const query = "query getProfile(id: AuthID) { user(id: $id) { id name } }";

interface UserData {
  user: {
    id: string;
    name: string;
  };
}

export interface UserVariables {
  id: string;
}

const options:GraphqlOptions<UserVariables> = { variables: { id: "QVBJcy5ndXJ1" } };

// executeGraphql
const gqlResponse = await dataConnect.executeGraphql<UserData, UserVariables>(query, options);

// executeGraphqlRead (similar to previous sample but only for read operations)
const gqlResponse = await dataConnect.executeGraphqlRead<UserData, UserVariables>(query, options);

// gqlResponse -> { "data": { "user": { "id": "QVBJcy5ndXJ1", "name": "Fred" } } }

Suplantar las credenciales del usuario

También hay casos de uso en los que deseas que tus secuencias de comandos modifiquen los datos del usuario en función de credenciales limitadas, en nombre de un usuario específico. Este enfoque respeta el principio de privilegio mínimo.

Para usar esta interfaz, recopila información de un token de autorización JWT personalizado que siga el formato de token Authentication. Consulta también la guía de tokens personalizados.

// Get the current user's data
const queryGetUserImpersonation = `
    query getUser @auth(level: USER) {
        user(key: {uid_expr: "auth.uid"}) {
            id,
            name
        }
    }`;

// Impersonate a user with the specified auth claims
const optionsAuthenticated: GraphqlOptions<undefined> = {
    impersonate: {
        authClaims: {
            sub: 'QVBJcy5ndXJ1'
        }
    }
};

// executeGraphql with impersonated authenticated user scope
const gqlResponse = await dataConnect.executeGraphql<UserData, undefined>(queryGetUserImpersonation, optionsAuthenticated);

// gqlResponse -> { "data": { "user": { "id": "QVBJcy5ndXJ1", "name": "Fred" } } }

Administra datos públicos con métodos de executeGraphql

Puedes trabajar con datos de acceso público con el SDK, suplantando la identidad de un usuario no autenticado.

// Query to get posts, with authentication level PUBLIC
const queryGetPostsImpersonation = `
    query getPosts @auth(level: PUBLIC) {
        posts {
          description
        }
    }`;

// Attempt to access data as an unauthenticated user
const optionsUnauthenticated: GraphqlOptions<undefined> = {
    impersonate: {
        unauthenticated: true
    }
};

// executeGraphql with impersonated unauthenticated user scope
const gqlResponse = await dataConnect.executeGraphql<UserData, undefined>(queryGetPostsImpersonation, optionsUnauthenticated);

Realizar operaciones de datos masivas

Firebase recomienda que uses Admin SDK para las operaciones de datos masivas en bases de datos de producción.

El SDK proporciona los siguientes métodos para trabajar con datos masivos. A partir de los argumentos proporcionados, cada método construye y ejecuta una mutación de GraphQL.


// Methods of the bulk operations API
// dc is a Data Connect admin instance from getDataConnect

const resp = await dc.insert("movie" /*table name*/, data[0]);
const resp = await dc.insertMany("movie" /*table name*/, data);
const resp = await dc.upsert("movie" /*table name*/, data[0]);
const resp = await dc.upsertMany("movie" /*table name*/, data);

Notas de rendimiento para operaciones masivas

Cada solicitud al backend generará un viaje de ida y vuelta a Cloud SQL, por lo que cuanto más agrupes, mayor será la capacidad de procesamiento.

Sin embargo, cuanto mayor sea el tamaño del lote, más larga será la instrucción SQL generada. Cuando se alcance el límite de longitud de la instrucción SQL de PostgreSQL, se producirá un error.

En la práctica, experimenta para encontrar el tamaño de lote adecuado para tu carga de trabajo.

Próximos pasos