Mise à niveau vers Node.js SDK Admin SDK v10 (SDK modulaire)

La version 10 du SDK Admin Node.js introduit deux changements importants :

  • La prise en charge de Node.js 10 est interrompue (il s'agit d'un changement radical )
  • Le SDK a adopté un modèle d'API modulaire

Ce guide fournit des instructions et des informations pour aider les développeurs à mettre à niveau les applications Node.js existantes des versions antérieures du SDK Admin vers la v10.

Mettez à jour Node.js vers la version 12 ou supérieure

Avec la version Admin Node.js SDK v10, Firebase a interrompu la prise en charge de Node.js 10. Les développeurs doivent utiliser Node.js 12 ou une version ultérieure lorsqu'ils utilisent le SDK Admin. Si vous utilisez le SDK Admin Node.js avec Cloud Functions pour Firebase, assurez-vous d'avoir mis à niveau votre version de Node.js vers la version 12 ou supérieure.

Utiliser des modules au lieu d'espaces de noms

Depuis sa création, le SDK Admin Node.js propose une API stable structurée comme une hiérarchie d'espaces de noms imbriquée. Par conséquent, vous vous êtes peut-être familiarisé avec l’écriture de code ressemblant à ceci :

// Import the global admin namespace
import * as admin from 'firebase-admin';

const app: admin.app.App = admin.initializeApp();

const token: string = await admin.auth().createCustomToken('alice');

const user: admin.auth.UserRecord = await admin.auth().getUser('bob');

À partir de la v10, le SDK Admin Node.js propose plusieurs points d'entrée de module avec des exportations nommées. Nous recommandons aux développeurs d'utiliser ces nouveaux points d'entrée pour accéder aux différentes API du SDK, plutôt que d'utiliser l'espace de noms admin global.

Voici à quoi ressemblerait l'exemple ci-dessus avec les nouveaux points d'entrée du module :

Manuscrit

// Import only what you need
import { initializeApp, App } from 'firebase-admin/app';
import { getAuth, UserRecord } from 'firebase-admin/auth';

const app: App = initializeApp();

const token: string = await getAuth().createCustomToken('alice');

const user: UserRecord = getAuth().getUser('bob');

Noeud.js

// Import only what you need
const { initializeApp } = require('firebase-admin/app');
const { getAuth } = require('firebase-admin/auth');

const app = initializeApp();

const token = await getAuth().createCustomToken('alice');

const user = getAuth().getUser('bob');

Utilisation des points d'entrée modulaires v10

Notez que, dans les exemples ci-dessus, vous n’importez plus un espace de noms admin global. Au lieu de cela, vous importez explicitement uniquement les symboles dont vous avez besoin à partir de plusieurs points d’entrée du module. De plus, les développeurs TypeScript n'ont plus besoin d'utiliser des identifiants de type triples imbriqués comme admin.auth.UserRecord et admin.database.Reference . Étant donné que chaque type appartient à exactement un module, vous pouvez simplement les importer par leurs noms courts comme UserRecord et Reference .

Voici tous les points d'entrée des modules disponibles dans le SDK à partir de la v10 :

  • firebase-admin/app
  • firebase-admin/auth
  • firebase-admin/base de données
  • firebase-admin/firestore
  • firebase-admin/instance-id
  • firebase-admin/apprentissage automatique
  • firebase-admin/messagerie
  • firebase-admin/gestion-de-projet
  • firebase-admin/remote-config
  • firebase-admin/règles de sécurité
  • firebase-admin/stockage

Le tableau suivant montre la syntaxe d'importation de remplacement pour chacune des fonctions d'espace de noms héritées :

v9 v10
admin.initializeApp() import { initializeApp } from 'firebase-admin/app'

initializeApp();

admin.app() import { getApp } from 'firebase-admin/ap'

getApp();

admin.credential.cert() import { cert } from 'firebase-admin/app'

cert();

admin.auth() import { getAuth } from 'firebase-admin/auth'

getAuth();

admin.database() import { getDatabase } from 'firebase-admin/database'

getDatabase();

admin.firestore() import { getFirestore } from 'firebase-admin/firestore'

getFirestore();

admin.instanceId() import { getInstanceId } from 'firebase-admin/instance-id'

getInstanceId();

admin.machineLearning() import { getMachineLearning } from 'firebase-admin/machine-learning'

getMachineLearning();

admin.messaging() import { getMessaging } from 'firebase-admin/messaging'

getMessaging()

admin.projectManagement() import { getProjectManagement } from 'firebase-admin/project-management'

getProjectManagement();

admin.remoteConfig() import { getRemoteConfig } from 'firebase-admin/remote-config'

getRemoteConfig();

admin.securityRules() import { getSecurityRules } from 'firebase-admin/security-rules'

getSecurityRules()

admin.storage() import { getStorage } from 'firebase-admin/storage'

getStorage();

Utiliser les fonctions exportées au lieu des méthodes sur l'application

Dans l'ancienne API, l'objet App exposait un certain nombre de méthodes telles que app.auth() et app.database() . Nous recommandons aux développeurs d'éviter d'utiliser ces méthodes et d'utiliser à la place les mêmes points d'entrée de module décrits ci-dessus pour obtenir des instances de service étendues à un objet App donné et effectuer d'autres tâches spécifiques à l'application.

v9 v10
app.auth() import { getAuth } from 'firebase-admin/auth';

getAuth(app);

app.database() import { getDatabase } from 'firebase-admin/database';

getDatabase(app);

app.database(url) import { getDatabaseWithUrl } from 'firebase-admin/database';

getDatabaseWithUrl(url, app);

app.firestore() import { getFirestore } from 'firebase-admin/firestore'

getFirestore(app);

app.instanceId() import { getInstanceId } from 'firebase-admin/instance-id'

getInstanceId(app);

app.machineLearning() import { getMachineLearning } from 'firebase-admin/machine-learning'

getMachineLearning(app);

app.messaging() import { getMessaging } from 'firebase-admin/messaging'

getMessaging(app);

app.projectManagement() import { getProjectManagement } from 'firebase-admin/project-management'

getProjectManagement(app);

app.remoteConfig() import { getRemoteConfig } from 'firebase-admin/remote-config'

getRemoteConfig(app);

app.securityRules() import { getSecurityRules } from 'firebase-admin/security-rules'

getSecurityRules(app);

app.storage() import { getStorage } from 'firebase-admin/storage'

getStorage(app);

app.delete() import { deleteApp } from 'firebase-admin/app';

deleteApp(app);

Prise en charge des modules ES

Node.js 12 et supérieur sont livrés avec une prise en charge expérimentale des modules ES, permettant même aux développeurs non TypeScript d'utiliser les mots-clés export et import dans leur code. À partir de la version v10, le SDK Admin Node.js fournit également la prise en charge des modules ES, afin que les développeurs implémentant des modules ES sur Node.js brut puissent importer le SDK à l'aide de la syntaxe import .

Pour utiliser les modules ES avec le SDK Admin, assurez-vous d'abord d'avoir activé la prise en charge ESM pour votre environnement d'exécution Node.js. Cela se fait généralement en ajoutant un champ "type": "module" à votre fichier package.json . Ensuite, vous pouvez écrire un code d'application qui ressemble à ceci :

// With {type: module} in the package.json...

// Import only what you need
import { initializeApp }  from 'firebase-admin/app';
import { getAuth } from 'firebase-admin/auth';

const app = initializeApp();

const token = await getAuth().createCustomToken('alice');

const user = getAuth().getUser('bob');