Mettre à niveau le SDK Admin Node.js vers la version 10 (SDK modulaire)

La version 10 du SDK Node.js Admin introduit deux modifications importantes:

  • La compatibilité avec Node.js 10 est interrompue (il s'agit d'un changement majeur)
  • 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 à partir de versions antérieures de Admin SDK vers la version 10.

Mettre à jour Node.js vers la version 12 ou ultérieure

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

Utiliser des modules au lieu d'espaces de noms

Depuis sa création, le SDK Node.js Admin propose une API stable structurée en hiérarchie d'espaces de noms imbriqués. Par conséquent, vous avez peut-être déjà écrit du code semblable à celui-ci:

// 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 version 10, 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 de module:

TypeScript

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

Node.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');

Utiliser les points d'entrée modulaires de la version 10

Notez que, dans les exemples ci-dessus, vous n'importez plus d'espace de noms admin global. Vous n'importez explicitement que les symboles dont vous avez besoin à partir de plusieurs points d'entrée de module. De plus, les développeurs TypeScript n'ont plus besoin d'utiliser d'identifiants de type à trois niveaux comme admin.auth.UserRecord et admin.database.Reference. Étant donné que chaque type appartient à un seul et unique module, vous pouvez simplement les importer par leur nom court, comme UserRecord et Reference.

Voici tous les points d'entrée de module disponibles dans le SDK à partir de la version 10:

  • firebase-admin/app
  • firebase-admin/auth
  • firebase-admin/database
  • firebase-admin/firestore
  • firebase-admin/instance-id
  • firebase-admin/machine-learning
  • firebase-admin/messaging
  • firebase-admin/project-management
  • firebase-admin/remote-config
  • firebase-admin/security-rules
  • firebase-admin/storage

Le tableau suivant indique la syntaxe d'importation de remplacement pour chacune des anciennes fonctions d'espace de noms:

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 des fonctions exportées au lieu de méthodes dans 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 plutôt les mêmes points d'entrée de module décrits ci-dessus pour obtenir des instances de service limitées à 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 versions ultérieures sont compatibles de manière expérimentale avec les modules ES, ce qui permet même aux développeurs non TypeScript d'utiliser les mots clés export et import dans leur code. À partir de la version 10, le SDK Admin Node.js est également compatible avec les modules ES, ce qui permet aux développeurs implémentant des modules ES sur Node.js standard d'importer le SDK à l'aide de la syntaxe import.

Pour utiliser des modules ES avec Admin SDK, assurez-vous d'abord d'avoir activé la prise en charge de l'ESM pour votre environnement d'exécution Node.js. Pour ce faire, il suffit généralement d'ajouter un champ "type": "module" à votre fichier package.json. Vous pouvez ensuite écrire le code d'application suivant:

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