Utiliser le SDK Admin avec Data Connect

Firebase Admin SDK est un ensemble de bibliothèques de serveur 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 d'accès é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. Les opérations en lecture seule vous permettent d'implémenter des fonctions administratives qui ne peuvent pas modifier les données de vos bases de données.

Configuration du SDK Admin

Pour commencer à utiliser Firebase Data Connect sur votre serveur, vous devez d'abord installer et configurer la 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 du service de votre 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'
});

Concevez des requêtes et des mutations à utiliser avec Admin SDK.

Admin SDK est utile pour tester les opérations Data Connect, en tenant compte 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 droits d'accès, il peut exécuter n'importe laquelle de vos requêtes et mutations, quels que soient les niveaux d'accès définis à l'aide des 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 administratifs, Firebase vous recommande de marquer les opérations administratives sans aucun niveau d'accès à l'autorisation, ou peut-être d'être plus explicite et de les définir sur NO_ACCESS. Dans les deux cas, cela empêche l'exécution de telles 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 l'amorçage des données et d'autres opérations sur les données locales. L'option Admin SDK vous permet de simplifier vos workflows, car elle 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, et 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 sur les données groupées, qui, au lieu des 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

Un cas d'utilisation typique de Admin SDK est la gestion des données utilisateur.

Utiliser des identifiants d'administrateur

L'approche la plus simple consiste à accéder aux données utilisateur à l'aide d'identifiants administratifs.

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

Emprunter l'identité d'un utilisateur

Dans certains cas d'utilisation, 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 sur les 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 utiliser le SDK pour travailler avec des données accessibles publiquement en empruntant 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 groupées sur les données

Firebase vous recommande d'utiliser Admin SDK pour les opérations sur les données groupées dans 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 pour les opérations groupées

Chaque requête envoyée au backend entraînera un aller-retour vers Cloud SQL. Par conséquent, plus vous regroupez les requêtes, plus le débit sera élevé.

Toutefois, plus la taille du 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 se produit.

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

Étape suivante