Utilizzare l'SDK Admin con Data Connect

Firebase Admin SDK è un insieme di librerie di 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 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 casi d'uso comuni

Admin SDK viene fornito per le operazioni con privilegi sui dati critici.

L'API per Data Connect è costituita da un'interfaccia executeGraphql di lettura/scrittura e da un'interfaccia executeGraphqlRead di sola lettura.

Gestire i dati utente

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

Puoi utilizzare l'SDK per lavorare con i dati accessibili pubblicamente, 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);

Quali sono i passaggi successivi?