Utilizzare l'SDK Admin con Data Connect

L'Firebase Admin SDK è un insieme di librerie server che ti consente di interagire con Firebase da ambienti privilegiati per eseguire azioni come query e mutazioni su un servizio Firebase Data Connect per la gestione collettiva dei dati e altre operazioni con privilegi elevati e credenziali impersonate.

Admin SDK fornisce un'API per chiamare operazioni in modalità di lettura/scrittura e di sola lettura. Con le operazioni di sola lettura, puoi implementare funzioni amministrative che non possono modificare i dati nei tuoi database.

Configurazione dell'SDK Admin

Per iniziare a utilizzare Firebase Data Connect sul tuo server, devi prima installare e configurare Admin SDK per Node.js.

Inizializza l'SDK Admin negli script

Per inizializzare l'SDK, importa le estensioni Data Connect e dichiara l'ID e la posizione del servizio del tuo progetto.


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'
});

Progetta query e mutazioni da utilizzare con Admin SDK

Admin SDK è utile per testare le operazioni Data Connect, tenendo conto delle seguenti considerazioni.

Comprendere l'SDK e la direttiva operativa @auth(level: NO_ACCESS)

Poiché Admin SDK opera con privilegi, può eseguire qualsiasi query e mutazione indipendentemente dai livelli di accesso impostati utilizzando le direttive @auth, incluso il livello NO_ACCESS.

Se, oltre alle operazioni del cliente, organizzi le query amministrative e le mutazioni nei file di origine .gql per l'importazione negli script amministrativi, Firebase ti consiglia di contrassegnare le operazioni amministrative senza alcun livello di accesso con autorizzazione o, in alternativa, di impostarle in modo più esplicito come NO_ACCESS. In entrambi i casi, ciò impedisce l'esecuzione di queste operazioni da client o in altri contesti non privilegiati.

Utilizzare l'SDK con l'emulatore Data Connect

Negli ambienti di prototipazione e test, può essere utile eseguire il seeding dei dati e altre operazioni sui dati locali. Admin SDK consente di semplificare i flussi di lavoro in quanto ignora l'autenticazione e l'autorizzazione per i flussi locali.

Gli SDK Firebase Admin si connettono automaticamente all'emulatore Data Connect quando è impostata la variabile di ambiente DATA_CONNECT_EMULATOR_HOST:

export DATA_CONNECT_EMULATOR_HOST="127.0.0.1:9399"

Per ulteriori informazioni, vedi:

Implementare i casi d'uso comuni

Admin SDK viene fornito per le operazioni privilegiate sui tuoi dati critici.

L'SDK Admin fornisce due interfacce:

  • Un'interfaccia generale per la maggior parte delle operazioni di lettura-scrittura o di sola lettura, in cui il codice implementa query e mutazioni e le passa al metodo di lettura-scrittura executeGraphql o al metodo di sola lettura executeGraphqlRead.
  • Un'interfaccia specializzata per le operazioni sui dati collettivi che, anziché metodi executeGraphql generici, espone metodi dedicati per le operazioni di mutazione: insert, insertMany, upsert e upsertMany.

Gestire i dati utente con i metodi executeGraphql

Un caso d'uso tipico per Admin SDK è la gestione dei dati utente.

Utilizzare le credenziali amministrative

L'approccio più semplice consiste nell'accedere ai dati utente utilizzando le credenziali amministrative.

// 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" } } }

Impersonare le credenziali utente

Esistono anche casi d'uso in cui vuoi che i tuoi script modifichino i dati utente in base a credenziali limitate, per conto di un utente specifico. Questo approccio rispetta il principio del privilegio minimo.

Per utilizzare questa interfaccia, raccogli informazioni da un token di autenticazione JWT personalizzato che segue il formato del token Authentication. Consulta anche la guida ai token personalizzati.

// 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" } } }

Gestire i dati pubblici con i metodi executeGraphql

Puoi lavorare con dati accessibili pubblicamente utilizzando l'SDK, rappresentando un utente non autenticato.

// 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);

Eseguire operazioni collettive sui dati

Firebase consiglia di utilizzare Admin SDK per le operazioni sui dati collettivi nei database di produzione.

L'SDK fornisce i seguenti metodi per lavorare con i dati collettivi. A partire dagli argomenti forniti, ogni metodo crea ed esegue una mutazione 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);

Note sul rendimento per le operazioni collettive

Ogni richiesta al backend comporta un round trip a Cloud SQL, quindi più richieste batch vengono inviate, maggiore è la velocità effettiva.

Tuttavia, maggiore è la dimensione del batch, più lunga è l'istruzione SQL generata. Quando viene raggiunto il limite di lunghezza dell'istruzione SQL PostgreSQL, si verifica un errore.

In pratica, sperimenta per trovare le dimensioni del batch appropriate per il tuo carico di lavoro.

Passaggi successivi