Utilizzare l'SDK Admin con Data Connect

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 le operazioni sia in modalità di lettura/scrittura sia in modalità 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.

Inizializzare l'SDK Admin negli script

Per inizializzare l'SDK, importa le estensioni Data Connect e dichiara l'ID servizio e la posizione del 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.

Informazioni sull'SDK e sulla direttiva di operazione @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 client, organizzi le query amministrative e le mutazioni nei file di origine .gql per l'importazione negli script amministrativi, Firebase consiglia di contrassegnare le operazioni amministrative senza alcun livello di accesso all'autorizzazione o di essere più esplicito e impostarle come NO_ACCESS. In entrambi i casi, si impedisce l'esecuzione di queste operazioni dai client o in altri contesti non privilegiati.

Utilizzare l'SDK con l'emulatore Data Connect

Negli ambienti di prototipo e di 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 casi d'uso comuni

L'Admin SDK viene fornito per le operazioni con privilegi sui 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 executeGraphql di lettura-scrittura o al metodo executeGraphqlRead di sola lettura.
  • Un'interfaccia specializzata per le operazioni collettive sui dati, che invece di 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 di amministrazione

L'approccio più semplice è 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 le informazioni da un token JWT di autenticazione 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 i dati accessibili pubblicamente utilizzando l'SDK, rubando l'identità di 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 collettive sui dati nei database di produzione.

L'SDK fornisce i seguenti metodi per lavorare con i dati collettivi. Dagli argomenti forniti, ogni metodo costruisce 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 viaggio di andata e ritorno a Cloud SQL, pertanto più richieste vengono raggruppate in batch, maggiore è la velocità effettiva.

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

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

Quali sono i passaggi successivi?