Google is committed to advancing racial equity for Black communities. See how.
Cette page a été traduite par l'API Cloud Translation.
Switch to English

Guide de mise à niveau du SDK Firebase pour Cloud Functions: version bêta vers la version 1.0 ou supérieure

La version 1.0.0 du SDK Firebase pour Cloud Functions a introduit des changements importants dans l'API. La principale modification, un remplacement du format event.data par data paramètres de data et de context , affecte toutes les fonctions asynchrones (non HTTP). Le SDK mis à jour peut également être utilisé avec firebase-functions-test , un SDK compagnon de test unitaire. Voir Fonctions de test unitaire pour plus d'informations.

La version 2.0.0 du SDK Firebase pour Cloud Functions a introduit un changement radical pour les horodatages dans les fonctions déclenchées par Firestore .

Pour mettre à jour les SDK vers la dernière version, exécutez ce qui suit dans le dossier des fonctions:

 npm install firebase-functions@latest --save
npm install firebase-admin@latest --save-exact
 

Vous devez également mettre à jour Firebase CLI vers la dernière version:

 npm install -g firebase-tools
 

Modifications du SDK qui affectent toutes les fonctions asynchrones (non HTTP)

Modifications du SDK par type de déclencheur

Modifications de l'émulation des fonctions

Modifications du SDK qui affectent toutes les fonctions d'arrière-plan (non HTTP)

Paramètre d'événement divisé en données et contexte

Depuis la version 1.0 du SDK Firebase pour Cloud Functions, le paramètre d' event pour les fonctions asynchrones est obsolète. Il a été remplacé par deux nouveaux paramètres: les data et le context .

Le paramètre data représente les données qui ont déclenché la fonction. Les champs du paramètre de data sont déterminés par le type de déclencheur et varient en conséquence. Par exemple, pour la base de données en temps réel, le paramètre de data est un DataSnapshot . Voir les modifications par type de déclencheur pour plus d'informations sur le paramètre de data .

Le paramètre context fournit des informations sur l'exécution de la fonction. Identique à tous les types de fonctions asynchrones, le context contient les champs eventId , timestamp , eventType , resource et params . En outre, les fonctions de la base de données en temps réel fournissent des informations d'authentification pour l'utilisateur qui a déclenché la fonction. Voici un exemple de champs de contexte définis dans une fonction déclenchée par une écriture de base de données en temps réel:

 exports.dbWrite = functions.database.ref('/path/with/{id}').onWrite((data, context) => {
  const authVar = context.auth; // Auth information for the user.
  const authType = context.authType; // Permissions level for the user.
  const pathId = context.params.id; // The ID in the Path.
  const eventId = context.eventId; // A unique event ID.
  const timestamp = context.timestamp; // The timestamp at which the event happened.
  const eventType = context.eventType; // The type of the event that triggered this function.
  const resource = context.resource; // The resource which triggered the event.
  // ...
});
 

Nouvelle syntaxe d'initialisation pour firebase-admin

firebase-admin est maintenant initialisé sans aucun paramètre dans l' firebase-admin exécution Cloud Functions.

Avant (<= v0.9.1)

 const functions = require('firebase-functions');
const admin = require('firebase-admin');
admin.initializeApp(functions.config().firebase);
 

Maintenant (> = v1.0.0)

 const functions = require('firebase-functions');
const admin = require('firebase-admin');
admin.initializeApp();
 

Notez que vous ne pouvez plus transmettre functions.config().firebase lors de l'initialisation. Voir la section suivante pour plus de détails sur la façon d'accéder à la configuration dans la v1.0.0.

functions.config().firebase supprimé

functions.config().firebase a été supprimé. Si vous souhaitez accéder aux valeurs de configuration de votre projet Firebase, utilisez plutôt process.env.FIREBASE_CONFIG :

 let firebaseConfig = JSON.parse(process.env.FIREBASE_CONFIG);
/* {  databaseURL: 'https://databaseName.firebaseio.com',
       storageBucket: 'projectId.appspot.com',
       projectId: 'projectId' }
*/
 

Modifications du SDK par type de déclencheur

Pour de nombreux déclencheurs de fonction pris en charge, la version 1.0 a introduit des changements dans la dénomination des champs de données et des méthodes. Cette section répertorie les modifications par type de déclencheur.

Base de données en temps réel

Les données d'événement sont désormais un DataSnapshot

Dans les versions précédentes, event.data était un DeltaSnapshot ; à partir de la version 1.0, il s'agit d'un DataSnapshot .

Pour les événements onWrite et onUpdate , le paramètre data a des champs before et after . Chacun d'entre eux est un DataSnapshot avec les mêmes méthodes disponibles dans admin.database.DataSnapshot . Par exemple:

Avant (<= v0.9.1)

 exports.dbWrite = functions.database.ref('/path').onWrite((event) => {
  const beforeData = event.data.previous.val(); // data before the write
  const afterData = event.data.val(); // data after the write
});
 

Maintenant (> = v1.0.0)

 exports.dbWrite = functions.database.ref('/path').onWrite((change, context) => {
  const beforeData = change.before.val(); // data before the write
  const afterData = change.after.val(); // data after the write
});
 

Pour onCreate , le paramètre data est un DataSnapshot qui représente les données qui viennent d'être ajoutées:

Avant (<= v0.9.1)

 exports.dbCreate = functions.database.ref('/path').onCreate((event) => {
  const createdData = event.data.val(); // data that was created
});
 

Maintenant (> = v1.0.0)

 exports.dbCreate = functions.database.ref('/path').onCreate((snap, context) => {
  const createdData = snap.val(); // data that was created
});
 

Pour onDelete , le paramètre data est un DataSnapshot qui représente les données qui viennent d'être supprimées:

Avant (<= v0.9.1)

 exports.dbDelete = functions.database.ref('/path').onDelete((event) => {
  const deletedData = event.data.previous.val(); // data that was deleted
});

 

Maintenant (> = v1.0.0)

 exports.dbDelete = functions.database.ref('/path').onDelete((snap, context) => {
  const deletedData = snap.val(); // data that was deleted
});
 

Nouvelles propriétés pour les informations d'authentification utilisateur

EventContext.auth V1.0.0 a introduit deux nouvelles propriétés pour accéder aux informations utilisateur, y compris les autorisations, pour l'utilisateur qui a déclenché une fonction.

  • EventContext.auth . Contient des informations telles que l' uid et le jeton d'authentification de l'utilisateur authentifié.
  • EventContext.authType . Contient des niveaux d'autorisation, vous permettant de détecter si l'utilisateur est un utilisateur administrateur, par exemple.

Les développeurs utilisant les champs event.auth non event.auth doivent mettre à jour tout code associé pour utiliser ces nouvelles propriétés.

adminRef remplacé par ref

La référence .adminRef été supprimée au profit de la référence .ref qui est désormais autorisée avec des privilèges d'administrateur . L'ancienne façon d'utiliser .ref - en tant que référence à la modification autorisée en tant qu'utilisateur ayant déclenché la modification - n'est plus prise en charge.

Avant (<= v0.9.1)

 exports.dbCreate = functions.database.ref('/path/{uid}').onCreate((event) => {
  const parentRef = event.data.adminRef.parent; // The Database reference to the parent authorized with admin privileges.

  const parentRefAsUser = event.data.ref.parent; // The Database reference to the parent authorized as the user which triggered the change.
});
 

Maintenant (> = v1.0.0)

 exports.dbCreate = functions.database.ref('/path/{uid}').onCreate((snap, context) => {
  const parentRef = snap.ref.parent; // The Database reference to the parent authorized with admin privileges
});
 

Vous pouvez toujours effectuer des modifications autorisées par l'utilisateur dans la base de données en temps réel à l'aide du SDK d'administration:

 const functions = require('firebase-functions');
const admin = require('firebase-admin');

exports.impersonateMakeUpperCase = functions.database.ref('/messages/{pushId}/original')
    .onCreate((snap, context) => {
      const appOptions = JSON.parse(process.env.FIREBASE_CONFIG);
      appOptions.databaseAuthVariableOverride = context.auth;
      const app = admin.initializeApp(appOptions, 'app');
      const uppercase = snap.val().toUpperCase();
      const ref = snap.ref.parent.child('uppercase');

      const deleteApp = () => app.delete().catch(() => null);

      return app.database().ref(ref).set(uppercase).then(res => {
        // Deleting the app is necessary for preventing concurrency leaks
        return deleteApp().then(() => res);
      }).catch(err => {
        return deleteApp().then(() => Promise.reject(err));
      });
    });
 

Cloud Firestore

Tout comme les modifications apportées à la base de données en temps réel pour la version 1.0, onWrite et onUpdate ont un paramètre de données qui a des champs before et after . Les événements pour onCreate et onDelete ont tous deux un paramètre de données qui est un Cloud Firestore DocumentSnapshot .

Avant (<= v0.9.1)

 exports.dbWrite = functions.firestore.document('/doc/path').onWrite((event) => {
  const beforeData = event.data.previous.data(); // data before the write
  const afterData = event.data.data(); // data after the write
});
 

Maintenant (> = v1.0.0)

 exports.dbWrite = functions.firestore.document('/doc/path').onWrite((change, context) => {
  const beforeData = change.before.data(); // data before the write
  const afterData = change.after.data(); // data after the write
});
 

Les événements pour onCreate et onDelete ont tous deux un paramètre de données qui est un DocumentSnapshot .

Avant (<= v0.9.1)

 exports.dbDelete = functions.firestore.document('/doc/path').onDelete((event) => {
  const deletedData = event.data.previous.data(); // data that was deleted
});

 

Maintenant (> = v1.0.0)

 exports.dbDelete = functions.firestore.document('/doc/path').onDelete((snap, context) => {
  const deletedData = snap.data(); // data that was deleted
});
 

Changement de rupture dans la v2.0.0 pour les horodatages Firestore

À partir de la version 2.0.0 du SDK Firebase pour Cloud Functions, les valeurs d'horodatage d'un instantané Firestore reçu à l'intérieur d'une fonction sont des objets Firestore Timestamp . Cela s'applique à snapshot.createTime , snapshot.updateTime , snapshot.readTime et toutes les valeurs d'horodatage dans snapshot.data()

Maintenant (> = v2.0.0)

 exports.dbCreate = functions.firestore.document('/doc/path').onCreate((snap, context) => {
  //seconds of UTC time since Unix epoch
  console.log(snap.createTime.seconds);

  //fractions of a second at nanosecond resolution, 0 to 999,999,999
  console.log(snap.createTime.nanoseconds);
});
 

Authentification

Dans les versions précédentes, event.data.metadata contenait les champs obsolètes createdAt et lastSignedInAt . La version 1.0 supprime complètement ces champs et les remplace par les champs creationTime et lastSignInTime dans le paramètre userRecord.metadata .

Avant (<= v0.9.1)

 // This code won't work with Cloud Functions SDK 1.0 and higher!
exports.authAction = functions.auth.user().onCreate((event) => {
  const userMetadata = event.data.metadata;

  const creationTime = userMetadata.createdAt; // 2016-12-15T19:37:37.059Z
  const lastSignInTime = userMetadata.lastSignedInAt; // 2018-01-03T16:23:12.051Z
}
 

Maintenant (> = v1.0.0)

 exports.authAction = functions.auth.user().onCreate((userRecord, context) => {
  const creationTime = userRecord.metadata.creationTime; // 2016-12-15T19:37:37.059Z
  const lastSignInTime = userRecord.metadata.lastSignInTime; // 2018-01-03T16:23:12.051Z
}
 

Crashlytics

Dans la version 1.0, le gestionnaire d'événements qui se déclenche chaque fois qu'un nouveau problème se produit est onNew . Le gestionnaire précédent nommé onNewDetected a été supprimé.

Avant (<= v0.9.1)

 exports.newIssue = functions.crashlytics.issue().onNewDetected((event) => {
  const issue = event.data;

  const issueId = issue.issueId;
  const issueTitle = issue.issueTitle;
  const appName = issue.appInfo.appName;
  const appId = issue.appInfo.appId;
  const appPlatform = issue.appInfo.appPlatform;
  const latestAppVersion = issue.appInfo.latestAppVersion;
  const createTime = issue.createTime;
}
 

Maintenant (> = v1.0.0)

 exports.newIssue = functions.crashlytics.issue().onNew((issue, context) => {
  const issueId = issue.issueId;
  const issueTitle = issue.issueTitle;
  const appName = issue.appInfo.appName;
  const appId = issue.appInfo.appId;
  const appPlatform = issue.appInfo.appPlatform;
  const latestAppVersion = issue.appInfo.latestAppVersion;
  const createTime = issue.createTime;
}
 

Espace de rangement

Le onChange gestionnaire d'événements a été supprimé. Au lieu de cela, la version 1.0 prend en charge ces événements:

  • onArchive uniquement lorsqu'un onArchive a activé la gestion des versions d'objet . Cet événement indique que la version active d'un objet est devenue une version archivée, soit parce qu'elle a été archivée, soit parce qu'elle a été écrasée par le téléchargement d'un objet du même nom.
  • onDelete Envoyé lorsqu'un objet a été définitivement supprimé. Cela inclut les objets qui sont écrasés ou supprimés dans le cadre de la configuration du cycle de vie du compartiment . Pour les buckets avec la gestion des versions d'objet activée, cela n'est pas envoyé lorsqu'un objet est archivé (voir onArchive ), même si l'archivage se produit via la méthode storage.objects.delete .
  • onFinalize Envoyé lorsqu'un nouvel objet (ou une nouvelle génération d'un objet existant) est créé avec succès dans le compartiment. Cela inclut la copie ou la réécriture d'un objet existant. Un téléchargement échoué ne déclenche pas cet événement.
  • onMetadataUpdate Envoyé lorsque les métadonnées d'un objet existant changent.

Avant (<= v0.9.1)

 exports.processFile = functions.storage.object().onChange((event) => {
  const object = event.data;

  const filePath = object.name; // Path of the File
  const contentType = object.contentType; // Mime type of the file

  // Exit if this is a deletion event.
  if (object.resourceState === 'not_exists') {
    console.log('This file was deleted.');
    return null;
  }

  // Exit if file exists but is not new and is only being triggered
  // because of a metadata change.
  if (resourceState === 'exists' && metageneration > 1) {
    console.log('This is a metadata change event.');
    return null;
  }

  // ...
}
 

Maintenant (> = v1.0.0)

 exports.processFile = functions.storage.object().onFinalize((object, context) => {
  const filePath = object.name; // Path of the File
  const contentType = object.contentType; // Mime type of the file

  // ...
}

exports.fileDeleted = functions.storage.object().onDelete((object, context) => {
  console.log('This file was deleted.');
}

exports.metadataUpdated = functions.storage.object().onMetadataUpdate((object, context) => {
  console.log('This is a metadata change event.');
}
 

Pub / Sub

Le type de déclencheur sous-jacent ayant changé, vous devez renommer et redéployer les fonctions pub / sub. Aucune modification du code de fonction n'est requise.

Pour mettre à jour les fonctions pub / sub:

  1. Renommez la fonction. Par exemple, renommez «myPubSubFunction» en «myNewPubSubFunction».
  2. Déployez uniquement cette fonction à l'aide d'un déploiement partiel:

    firebase deploy --only functions:myNewPubSubFunction

  3. Après avoir déployé avec succès «myNewPubSubFunction», supprimez la fonction obsolète antérieure à la v.1.0.0 en déployant toutes les fonctions:

    firebase deploy --only functions

Pendant la brève période entre ces commandes de déploiement, vous pouvez recevoir des déclencheurs en double. Pour gérer ce cas et pour un fonctionnement normal, assurez-vous d' écrire des fonctions idempotentes .

Pour en savoir plus, consultez la référence API .

Modifications de l'émulation des fonctions

  • firebase serve désormais à la fois les fonctions HTTP et l'hébergement par défaut.
  • firebase experimental:functions:shell , qui émule toutes les fonctions, a été renommé en firebase functions:shell .

Changements de syntaxe pour les fonctions shell

La syntaxe pour appeler des fonctions via le shell des fonctions a été mise à jour pour refléter la syntaxe des fonctions firebase v1.0.0 +.

 // Inside functions shell

// To emulate database writes done by an administrative user:
myDbFunction(‘data’)

// To emulate database writes done by an authenticated user:
myDbFunction(‘data’, { auth: { uid: ‘abc’ }})

// To emulate database writes done by an unauthenticated user:
myDbFunction(‘data’, { authMode: ‘UNAUTHENTICATED’)