Panduan upgrade Firebase SDK untuk Cloud Functions: versi beta hingga versi 1.0 atau yang lebih tinggi

Firebase SDK untuk Cloud Functions versi 1.0.0 memperkenalkan beberapa perubahan penting pada API. Perubahan utamanya, yaitu penggantian format event.data dengan parameter data dan context, memengaruhi semua fungsi asinkron (non-HTTP). SDK baru ini juga dapat digunakan dengan firebase-functions-test, yakni SDK pendamping pengujian unit. Baca bagian Pengujian Unit Functions untuk mengetahui informasi selengkapnya.

Firebase SDK untuk Cloud Functions versi 2.0.0 memperkenalkan perubahan yang dapat menyebabkan gangguan untuk stempel waktu dalam fungsi yang dipicu Firestore.

Untuk mengupdate SDK ke versi terbaru, jalankan hal-hal berikut di folder fungsi:

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

Anda juga harus mengupdate Firebase CLI ke versi yang terbaru:

npm install -g firebase-tools

Perubahan SDK yang memengaruhi semua fungsi asinkron (non-HTTP)

Perubahan SDK menurut jenis pemicu

Referensi API Baru dan Lama

Perubahan pada emulasi fungsi

Perubahan SDK yang memengaruhi semua fungsi latar belakang (non-HTTP)

Parameter peristiwa terbagi menjadi data dan konteks

Parameter event untuk fungsi yang terjadi secara tidak bersamaan sudah tidak digunakan lagi pada Firebase SDK untuk Cloud Functions versi 1.0. Parameter tersebut telah diganti oleh 2 parameter baru: data dan context.

Parameter data mewakili data yang memicu fungsi. Kolom parameter data ditentukan oleh jenis pemicu dan bervariasi sesuai jenis tersebut. Misalnya, untuk Realtime Database, parameter data adalah DataSnapshot. Baca bagian perubahan berdasarkan jenis pemicu untuk memperoleh informasi lebih lanjut tentang parameter data.

Parameter context memberikan informasi tentang eksekusi fungsi. context berisi kolom eventId, timestamp, eventType, resource, dan params, dan parameter ini identik di seluruh jenis fungsi yang tidak bersamaan. Selain itu, fungsi Realtime Database memberikan informasi autentikasi untuk pengguna yang memicu fungsi. Berikut ini adalah contoh kolom konteks yang ditentukan dalam fungsi yang dipicu oleh penulisan Realtime Database:

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

Sintaks inisialisasi baru untuk firebase-admin

firebase-admin kini sudah diinisialisasi tanpa parameter apa pun dalam runtime Cloud Functions.

Versi sebelumnya (<= v0.9.1)

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

Versi sekarang (>= v1.0.0)

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

Perlu diperhatikan bahwa Anda tidak bisa lagi meneruskan functions.config().firebase saat melakukan inisialisasi. Baca bagian berikut untuk mengetahui detail tentang cara mengakses konfigurasi pada versi v1.0.0.

functions.config().firebase telah dihapus

functions.config().firebase telah dihapus. Jika ingin mengakses nilai konfigurasi dari project Firebase Anda, gunakan process.env.FIREBASE_CONFIG:

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

Perubahan SDK menurut jenis pemicu

Untuk banyak pemicu fungsi yang didukung, v 1.0 memperkenalkan perubahan penamaan kolom data dan metode. Bagian ini mencantumkan perubahan menurut jenis pemicu.

Realtime Database

Data peristiwa sekarang adalah DataSnapshot

Dalam rilis sebelumnya, event.data adalah DeltaSnapshot; sekarang menjadi DataSnapshot dalam v 1.0.

Untuk peristiwa onWrite dan onUpdate, parameter data memiliki kolom before dan after. Setiap kolom ini adalah DataSnapshot dengan metode yang sama seperti yang tersedia di admin.database.DataSnapshot. Misalnya:

Versi sebelumnya (<= 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
});

Versi sekarang (>= 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
});

Untuk onCreate, parameter datanya adalah DataSnapshot yang mewakili data yang baru ditambahkan:

Versi sebelumnya (<= v0.9.1)

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

Versi sekarang (>= v1.0.0)

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

Untuk onDelete, parameter datanya adalah DataSnapshot yang mewakili data yang baru dihapus:

Versi sebelumnya (<= v0.9.1)

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

Versi sekarang (>= v1.0.0)

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

Properti baru untuk informasi autentikasi pengguna

EventContext.auth V1.0.0 memperkenalkan dua properti baru untuk mengakses informasi pengguna, termasuk izin, bagi pengguna yang memicu fungsi.

  • EventContext.auth. Berisi informasi seperti uid dan token autentikasi pengguna yang telah diautentikasi.
  • EventContext.authType. Berisi tingkat izin yang memungkinkan Anda mendeteksi apakah pengguna adalah pengguna admin, misalnya.

Developer yang menggunakan kolom event.auth yang tidak terdokumentasi harus mengupdate setiap kode terkait untuk menggunakan properti baru ini.

adminRef diganti dengan ref

Referensi .adminRef sekarang dihapus dan diganti dengan referensi .ref, yang kini diotorisasi dengan hak istimewa administrator. Cara sebelumnya yang menggunakan .ref—sebagai referensi pada perubahan yang diotorisasi oleh pengguna yang memicu perubahan—tidak lagi didukung.

Versi sebelumnya (<= 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.
});

Versi sekarang (>= 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
});

Anda tetap dapat melakukan perubahan yang diotorisasi pengguna pada Realtime Database menggunakan Admin SDK:

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

Sama seperti perubahan Realtime Database untuk v 1.0, onWrite dan onUpdate memiliki parameter data yang memiliki kolom before dan after. Peristiwa untuk onCreate dan onDelete memiliki parameter data yang merupakan DocumentSnapshot Cloud Firestore.

Versi sebelumnya (<= 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
});

Versi sekarang (>= 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
});

Peristiwa untuk onCreate dan onDelete sama-sama memiliki parameter data yang berupa DocumentSnapshot.

Versi sebelumnya (<= v0.9.1)

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

Versi sekarang (>= v1.0.0)

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

Perubahan Terkini di v2.0.0 untuk stempel waktu Firestore

Mulai Firebase SDK v2.0.0 untuk Cloud Functions, nilai stempel waktu dalam snapshot Firestore yang diterima di dalam fungsi adalah objek Stempel Waktu Firestore. Hal ini berlaku untuk snapshot.createTime, snapshot.updateTime, snapshot.readTime, dan nilai stempel waktu apa pun di snapshot.data()

Versi sekarang (>= v1.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);
});

Authentication

Pada rilis sebelumnya, event.data.metadata berisi kolom createdAt dan lastSignedInAt yang sudah tidak digunakan lagi. Versi 1.0 menghapus kolom ini sepenuhnya dan menggantinya dengan kolom creationTime dan lastSignInTime pada parameter userRecord.metadata.

Versi sebelumnya (<= 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
}

Versi sekarang (>= 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

Pada v 1.0, penangan peristiwa yang aktif setiap kali masalah baru terjadi adalah onNew. Penangan sebelumnya yang disebut onNewDetected telah dihapus.

Versi sebelumnya (<= 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;
}

Versi sekarang (>= 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;
}

Storage

Penangan peristiwa onChange telah dihapus. Sebagai gantinya, v 1.0 mendukung peristiwa berikut:

  • onArchive Hanya dikirim saat bucket telah mengaktifkan pembuatan versi objek. Peristiwa ini menunjukkan bahwa versi live dari sebuah objek telah menjadi versi yang diarsipkan, baik karena versi tersebut telah diarsipkan atau ditimpa oleh objek yang diupload dengan nama yang sama.
  • onDelete Dikirim saat sebuah objek telah dihapus secara permanen. Hal ini mencakup objek yang ditimpa atau dihapus sebagai bagian dari konfigurasi siklus proses bucket. Untuk bucket yang telah mengaktifkan pembuatan versi objek, peristiwa ini tidak dikirim saat objek diarsipkan (lihat onArchive), meskipun pengarsipan terjadi melalui metode storage.objects.delete.
  • onFinalize Dikirim saat objek baru (atau pembuatan baru dari objek yang sudah ada) berhasil dibuat dalam bucket. Hal ini meliputi penyalinan atau penulisan ulang objek yang sudah ada. Proses upload yang gagal tidak akan memicu peristiwa ini.
  • onMetadataUpdate Dikirim saat metadata objek yang ada berubah.

Versi sebelumnya (<= 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;
  }

  // ...
}

Versi sekarang (>= 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

Karena jenis pemicu yang mendasari telah berubah, Anda harus mengganti nama dan menerapkan ulang fungsi pub/sub. Kode fungsi tidak perlu diubah.

Untuk memperbarui fungsi pub/sub:

  1. Ganti nama fungsi. Misalnya, ganti nama 'myPubSubFunction' menjadi 'myNewPubSubFunction'.
  2. Hanya terapkan fungsi tersebut menggunakan penerapan sebagian:

    firebase deploy --only functions:myNewPubSubFunction

  3. Setelah berhasil menerapkan 'myNewPubSubFunction', hapus fungsi pra-v.1.0.0 yang tidak lagi digunakan dengan menerapkan semua fungsi:

    firebase deploy --only functions

Selama periode singkat antara perintah penerapan ini, Anda mungkin akan menerima pemicu duplikat. Untuk menangani kasus ini dan untuk operasi normal, pastikan untuk menulis fungsi idempoten.

Referensi API Baru dan Lama

Untuk mempelajari lebih lanjut, baca referensi API untuk firebase-functions v1.0.0. Anda juga dapat membaca referensi API untuk v0.9.1 untuk membantu Anda saat melakukan migrasi.

Perubahan pada emulasi fungsi

  • firebase serve kini menyediakan hosting dan fungsi HTTP secara default.
  • firebase experimental:functions:shell, yang mengemulasi semua fungsi, telah diubah namanya menjadi firebase functions:shell.

Perubahan sintaks untuk shell fungsi

Sintaks untuk mengaktifkan fungsi melalui shell fungsi telah diperbarui untuk mencerminkan sintaks firebase-functions 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’)

Kirim masukan tentang...

Butuh bantuan? Kunjungi halaman dukungan kami.