Utiliser le SDK Admin avec Data Connect

Firebase Admin SDK est un ensemble de bibliothèques de serveurs qui vous permet d'interagir avec Firebase à partir d'environnements privilégiés pour effectuer des actions telles que des requêtes et des mutations sur un service Firebase Data Connect pour la gestion des données groupées et d'autres opérations avec des droits élevés et des identifiants usurpés.

Admin SDK vous fournit une API pour appeler des opérations en mode lecture/écriture et en mode lecture seule. Avec les opérations en lecture seule, vous pouvez implémenter des fonctions administratives qui ne peuvent pas modifier les données de vos bases de données en toute tranquillité.

Configuration du SDK Admin

Pour commencer à utiliser Firebase Data Connect sur votre serveur, vous devez d'abord installer et configurer Admin SDK pour Node.js.

Initialiser le SDK Admin dans vos scripts

Pour initialiser le SDK, importez les extensions Data Connect et déclarez l'ID et l'emplacement de votre service de projet.


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

Concevoir des requêtes et des mutations à utiliser avec Admin SDK

Admin SDK est utile pour tester les opérations Data Connect, compte tenu des considérations suivantes.

Comprendre le SDK et la directive d'opération @auth(level: NO_ACCESS)

Étant donné que Admin SDK fonctionne avec des privilèges, il peut exécuter toutes vos requêtes et mutations, quel que soit le niveau d'accès défini à l'aide de directives @auth, y compris le niveau NO_ACCESS.

Si, en plus de vos opérations client, vous organisez vos requêtes et mutations administratives dans des fichiers sources .gql à importer dans des scripts d'administration, Firebase vous recommande de marquer les opérations administratives sans niveau d'accès d'autorisation, ou d'être plus explicite et de les définir comme NO_ACCESS. Dans tous les cas, cela empêche l'exécution de ces opérations à partir de clients ou dans d'autres contextes non privilégiés.

Utiliser le SDK avec l'émulateur Data Connect

Dans les environnements de prototypage et de test, il peut être utile d'effectuer un ensemencement de données et d'autres opérations sur les données locales. Admin SDK vous permet de simplifier vos workflows, car il ignore l'authentification et l'autorisation pour les flux locaux.

Les SDK Admin Firebase se connectent automatiquement à l'émulateur Data Connect lorsque la variable d'environnement DATA_CONNECT_EMULATOR_HOST est définie:

export DATA_CONNECT_EMULATOR_HOST="127.0.0.1:9399"

Pour en savoir plus, consultez les pages suivantes :

Mettre en œuvre des cas d'utilisation courants

Admin SDK est fourni pour les opérations privilégiées sur vos données critiques.

Le SDK Admin fournit deux interfaces:

  • Interface générale pour la plupart des opérations en lecture/écriture ou en lecture seule, dans laquelle votre code implémente des requêtes et des mutations, puis les transmet à la méthode executeGraphql en lecture/écriture ou à la méthode executeGraphqlRead en lecture seule.
  • Interface spécialisée pour les opérations de données groupées, qui, au lieu de méthodes executeGraphql génériques, expose des méthodes dédiées aux opérations de mutation: insert, insertMany, upsert et upsertMany.

Gérer les données utilisateur avec les méthodes executeGraphql

La gestion des données utilisateur est un cas d'utilisation courant de Admin SDK.

Utiliser des identifiants d'administrateur

La méthode la plus simple consiste à accéder aux données utilisateur à l'aide d'identifiants d'administrateur.

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

Incarner les identifiants utilisateur

Il existe également des cas d'utilisation où vous souhaitez que vos scripts modifient les données utilisateur en fonction d'identifiants limités, au nom d'un utilisateur spécifique. Cette approche respecte le principe du moindre privilège.

Pour utiliser cette interface, collectez des informations à partir d'un jeton d'authentification JWT personnalisé qui suit le format de jeton Authentication. Consultez également le guide des jetons personnalisés.

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

Gérer les données publiques avec les méthodes executeGraphql

Vous pouvez travailler avec des données accessibles au public à l'aide du SDK, en usurpant l'identité d'un utilisateur non authentifié.

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

Effectuer des opérations de données groupées

Firebase vous recommande d'utiliser Admin SDK pour les opérations de données groupées sur les bases de données de production.

Le SDK fournit les méthodes suivantes pour travailler avec des données groupées. À partir des arguments fournis, chaque méthode construit et exécute une mutation 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);

Remarques sur les performances des opérations groupées

Chaque requête envoyée au backend implique un aller-retour vers Cloud SQL. Plus vous effectuez de traitement par lot, plus le débit est élevé.

Toutefois, plus la taille de lot est importante, plus l'instruction SQL générée est longue. Lorsque la limite de longueur de l'instruction SQL PostgreSQL est atteinte, une erreur s'affiche.

En pratique, effectuez des tests pour trouver la taille de lot appropriée à votre charge de travail.

Étape suivante