Google berkomitmen untuk mendorong terwujudnya keadilan ras bagi komunitas Kulit Hitam. Lihat caranya.

Memulai: menulis, menguji, dan men-deploy fungsi pertama Anda

Untuk memulai Cloud Functions, coba pelajari tutorial ini, yang dimulai dengan berbagai tugas penyiapan yang diperlukan, kemudian memproses pembuatan, pengujian, dan deployment dua fungsi yang terkait:

  • addMessage(), yang mengekspos URL yang menerima nilai teks dan menuliskannya ke Cloud Firestore.
  • makeUppercase(), yang memicu penulisan di Cloud Firestore dan mengubah teks menjadi huruf kapital.

Kami telah memilih Cloud Firestore dan fungsi JavaScript yang dipicu HTTP untuk contoh ini sebagian karena pemicu latar belakang ini dapat diuji secara menyeluruh melalui Firebase Local Emulator Suite. Kumpulan alat ini juga mendukung pemicu callable Realtime Database, PubSub, Auth, dan HTTP. Jenis pemicu latar belakang lainnya seperti pemicu Remote Config, TestLab, dan Analytics dapat diuji secara interaktif menggunakan kumpulan alat yang tidak dijelaskan di halaman ini.

Bagian tutorial berikut ini menjelaskan langkah-langkah yang diperlukan untuk mem-build, menguji, dan men-deploy sampel. Jika Anda lebih memilih untuk menjalankan kode dan memeriksanya, langsung saja baca bagian Meninjau kode contoh lengkap.

Membuat project Firebase

  1. Di Firebase console, klik Tambahkan project, lalu pilih atau masukkan Nama project.

    Jika sudah memiliki project Google Cloud, Anda dapat memilih project dari menu drop-down untuk menambahkan resource Firebase ke project tersebut.

  2. (Opsional) Jika sedang membuat project baru, Anda dapat mengedit Project ID.

    Firebase menetapkan ID unik ke project Firebase Anda secara otomatis. Buka Memahami Project Firebase untuk mempelajari cara Firebase menggunakan project ID.

  3. Klik Lanjutkan.

  4. (Opsional) Siapkan Google Analytics untuk project Anda supaya Anda memiliki pengalaman optimal menggunakan produk Firebase berikut:

    Saat diminta, pilih untuk menggunakan akun Google Analytics yang ada atau untuk membuat akun baru.
    Jika Anda memilih untuk membuat akun baru, pilih lokasi pelaporan Analytics Anda, lalu setujui setelan berbagi data dan persyaratan Google Analytics untuk project Anda.

  5. Klik Buat project (atau Tambahkan Firebase, jika Anda menggunakan project Google Cloud yang sudah ada).

Firebase menyediakan resource untuk project Firebase Anda secara otomatis. Setelah selesai, Anda akan dibawa ke halaman ringkasan untuk project Firebase Anda di Firebase console.

Menyiapkan Node.js dan Firebase CLI

Anda akan memerlukan lingkungan Node.js untuk menulis fungsi, dan Firebase CLI untuk men-deploy fungsi ke runtime Cloud Functions. Untuk menginstal Node.js dan npm, sebaiknya gunakan Node Version Manager.

Setelah Node.js dan npm terinstal, instal Firebase CLI melalui metode pilihan Anda. Untuk menginstal CLI melalui npm, gunakan:

npm install -g firebase-tools

Tindakan ini akan menginstal perintah firebase yang tersedia secara global. Jika perintah gagal, Anda mungkin perlu mengubah izin npm. Untuk mengupdate ke versi terbaru firebase-tools, jalankan kembali perintah yang sama.

Menginisialisasi project

Saat menginisialisasi Firebase SDK untuk Cloud Functions, Anda membuat project kosong yang berisi dependensi dan beberapa kode sampel minimal, lalu memilih TypeScript atau JavaScript untuk membuat fungsi. Untuk keperluan tutorial ini, Anda juga perlu menginisialisasi Cloud Firestore.

Untuk menginisialisasi project Anda:

  1. Jalankan firebase login untuk login melalui browser dan mengautentikasi alat firebase.
  2. Buka direktori project Firebase Anda.
  3. Jalankan firebase init firestore. Untuk tutorial ini, Anda dapat menerima nilai default saat diminta untuk aturan Firestore dan file indeks. Jika belum menggunakan Cloud Firestore dalam project ini, Anda juga harus memilih mode awal dan lokasi untuk Firestore seperti yang dijelaskan di halaman Memulai Cloud Firestore.
  4. Jalankan firebase init functions. Alat ini memberi Anda pilihan untuk menginstal dependensi dengan npm. Anda bisa menolaknya jika ingin mengelola dependensi dengan cara lain, meskipun jika ini dilakukan, Anda harus menjalankan npm install sebelum mengemulasi atau men-deploy fungsi Anda.
  5. Alat ini memberi Anda dua opsi untuk dukungan bahasa:

    Untuk tutorial ini, pilih JavaScript.

Setelah perintah ini berhasil diselesaikan, struktur project Anda akan terlihat seperti ini:

myproject
 +- .firebaserc    # Hidden file that helps you quickly switch between
 |                 # projects with `firebase use`
 |
 +- firebase.json  # Describes properties for your project
 |
 +- functions/     # Directory containing all your functions code
      |
      +- .eslintrc.json  # Optional file containing rules for JavaScript linting.
      |
      +- package.json  # npm package file describing your Cloud Functions code
      |
      +- index.js      # main source file for your Cloud Functions code
      |
      +- node_modules/ # directory where your dependencies (declared in
                       # package.json) are installed

File package.json yang dibuat selama inisialisasi berisi kunci penting: "engines": {"node": "10"}. Kunci ini menentukan versi Node.js Anda untuk menulis dan men-deploy fungsi. Anda dapat memilih versi yang didukung lainnya.

Mengimpor modul yang diperlukan dan menginisialisasi aplikasi

Setelah menyelesaikan penyiapan tugas, Anda dapat membuka direktori sumber dan mulai menambahkan kode seperti yang diuraikan di bagian berikut. Untuk contoh ini, project Anda harus mengimpor Cloud Functions dan modul Admin SDK menggunakan pernyataan require Node. Tambahkan baris seperti berikut ini ke file index.js Anda:

// The Cloud Functions for Firebase SDK to create Cloud Functions and setup triggers.
const functions = require('firebase-functions');

// The Firebase Admin SDK to access Cloud Firestore.
const admin = require('firebase-admin');
admin.initializeApp();

Baris ini memuat modul firebase-functions dan firebase-admin, lalu menginisialisasi instance aplikasi admin tempat Anda bisa mengubah Cloud Firestore. Dukungan Admin SDK seperti untuk FCM, Authentication, dan Firebase Realtime Database, menyediakan cara andal untuk mengintegrasikan Firebase menggunakan Cloud Functions.

Firebase CLI menginstal Firebase dan modul Node Firebase SDK untuk Cloud Functions secara otomatis saat Anda menginisialisasi project. Untuk menambahkan library pihak ketiga ke project, Anda dapat mengubah package.json dan menjalankan npm install. Untuk mengetahui informasi lebih lanjut, baca bagian Menangani Dependensi.

Menambahkan fungsi addMessage()

Untuk fungsi addMessage(), tambahkan baris berikut ke index.js:

// Take the text parameter passed to this HTTP endpoint and insert it into
// Cloud Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Cloud Firestore using the Firebase Admin SDK.
  const writeResult = await admin.firestore().collection('messages').add({original: original});
  // Send back a message that we've successfully written the message
  res.json({result: `Message with ID: ${writeResult.id} added.`});
});

Fungsi addMessage() adalah endpoint HTTP. Setiap permintaan yang dibuat ke endpoint akan membuat object Request dan Response ExpressJS-style yang diteruskan ke callback onRequest().

Fungsi HTTP bersifat sinkron (mirip dengan fungsi callable), sehingga Anda harus mengirim respons secepat mungkin dan menunda pekerjaan menggunakan Cloud Firestore. Fungsi HTTP addMessage() meneruskan nilai teks ke endpoint HTTP dan memasukkannya ke dalam database di jalur /messages/:documentId/original.

Menambahkan fungsi makeUppercase()

Untuk fungsi makeUppercase(), tambahkan baris berikut ke index.js:

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore.document('/messages/{documentId}')
    .onCreate((snap, context) => {
      // Grab the current value of what was written to Cloud Firestore.
      const original = snap.data().original;

      // Access the parameter `{documentId}` with `context.params`
      functions.logger.log('Uppercasing', context.params.documentId, original);

      const uppercase = original.toUpperCase();

      // You must return a Promise when performing asynchronous tasks inside a Functions such as
      // writing to Cloud Firestore.
      // Setting an 'uppercase' field in Cloud Firestore document returns a Promise.
      return snap.ref.set({uppercase}, {merge: true});
    });

Fungsi makeUppercase() dijalankan saat terjadi penulisan Cloud Firestore. Fungsi ref.set menentukan dokumen yang akan diproses. Untuk memperoleh performa terbaik, Anda harus mengaturnya sespesifik mungkin.

Tanda kurung kurawal — misalnya, {documentId} — melingkupi "parameter", yaitu karakter pengganti yang mengekspos data yang sesuai dalam callback.

Cloud Firestore memicu callback onWrite() setiap kali data ditulis atau diupdate di dokumen yang ditentukan.

Fungsi yang digerakkan peristiwa seperti peristiwa Cloud Firestore bersifat asinkron. Fungsi callback harus menampilkan null, Objek, atau Promise. Jika tidak menampilkan hasil apa pun, waktu fungsi akan habis, sehingga akan menghasilkan sinyal error, dan fungsi tersebut akan dicoba ulang. Baca artikel tentang Sinkronisasi, Asinkronisasi, dan Promise.

Mengemulasi eksekusi fungsi Anda

Dengan Firebase Local Emulator Suite, Anda dapat mem-build dan menguji aplikasi di mesin lokal Anda, bukan men-deploy-nya ke project Firebase. Pengujian lokal selama pengembangan sangat direkomendasikan, sebagian karena mengurangi risiko terjadinya error coding yang berpotensi dikenai biaya di lingkungan produksi (misalnya, loop tak terbatas).

Untuk mengemulasi fungsi Anda:

  1. Jalankan firebase emulators:start dan periksa output untuk URL UI Emulator Suite. Setelan defaultnya adalah localhost:4000, tetapi mungkin dihosting di port yang berbeda di mesin Anda. Masukkan URL tersebut di browser Anda untuk membuka UI Emulator Suite.

  2. Periksa output perintah firebase emulators:start untuk URL fungsi HTTP addMessage(). URL tersebut akan tampak seperti http://localhost:5001/MY_PROJECT/us-central1/addMessage, dengan pengecualian:

    1. MY_PROJECT akan diganti dengan ID project Anda.
    2. Port-nya mungkin berbeda di mesin lokal Anda.
  3. Tambahkan string kueri ?text=uppercaseme ke akhir URL fungsi. Ini akan terlihat seperti: http://localhost:5001/MY_PROJECT/us-central1/addMessage?text=uppercaseme. Jika ingin, Anda dapat mengubah pesan "uppercaseme" menjadi pesan kustom.

  4. Buat pesan baru dengan membuka URL di tab baru pada browser Anda.

  5. Lihat efek fungsi di UI Emulator Suite:

    1. Di tab Log, Anda akan melihat log baru yang menunjukkan bahwa fungsi addMessage() dan makeUppercase() telah menjalankan:

      fungsi i: Memulai eksekusi fungsi "addMessage"

      fungsi i: Memulai eksekusi fungsi "makeUppercase"

    2. Di tab Firestore, Anda akan melihat dokumen yang berisi pesan asli Anda serta versi huruf kapital dari pesan tersebut (jika awalnya adalah "uppercaseme", Anda akan melihat "UPPERCASEME").

Men-deploy fungsi ke lingkungan produksi

Setelah fungsi berjalan seperti yang diinginkan di emulator, Anda dapat melanjutkan untuk men-deploy, menguji, dan menjalankannya di lingkungan produksi. Perlu diingat bahwa untuk men-deploy ke lingkungan runtime Node.js 10 yang direkomendasikan, project Anda harus menggunakan paket penagihan Blaze bayar sesuai penggunaan. Lihat Harga Cloud Functions.

Untuk menyelesaikan tutorial, deploy fungsi Anda, lalu jalankan addMessage() untuk memicu makeUppercase().

  1. Jalankan perintah ini untuk men-deploy fungsi Anda:

    $ firebase deploy --only functions
    

    Setelah Anda menjalankan perintah ini, Firebase CLI akan membuat output URL untuk setiap endpoint fungsi HTTP. Dalam terminal, Anda akan melihat baris seperti ini:

    Function URL (addMessage): https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage
    

    URL berisi project ID Anda serta region untuk fungsi HTTP. Meskipun Anda tidak perlu mengkhawatirkannya sekarang, beberapa fungsi HTTP produksi akan menentukan lokasi untuk meminimalkan latensi jaringan.

    Jika Anda menemukan error akses seperti "Tidak dapat memberikan otorisasi akses ke project", coba periksa aliasing project Anda.

  2. Dengan menggunakan URL addMessage() yang dioutput oleh CLI, tambahkan parameter kueri teks, lalu buka di browser:

    https://us-central1-MY_PROJECT.cloudfunctions.net/addMessage?text=uppercasemetoo
    

    Fungsi ini menjalankan dan mengalihkan browser ke Firebase console di lokasi database tempat string teks disimpan. Peristiwa penulisan ini memicu makeUppercase(), yang menulis string dalam huruf kapital.

Setelah menerapkan dan menjalankan fungsi, Anda dapat melihat log di Firebase console untuk Cloud Functions. Jika Anda perlu menghapus fungsi dalam pengembangan atau produksi, gunakan Firebase CLI.

Meninjau kode contoh lengkap

Berikut ini adalah functions/index.js lengkap yang berisi fungsi addMessage() dan makeUppercase(). Dengan fungsi-fungsi ini, Anda dapat meneruskan parameter ke endpoint HTTP yang menulis nilai ke Cloud Firestore, lalu mengubahnya dengan mengganti semua karakter dalam string itu menjadi huruf kapital.

// The Cloud Functions for Firebase SDK to create Cloud Functions and setup triggers.
const functions = require('firebase-functions');

// The Firebase Admin SDK to access Cloud Firestore.
const admin = require('firebase-admin');
admin.initializeApp();

// Take the text parameter passed to this HTTP endpoint and insert it into
// Cloud Firestore under the path /messages/:documentId/original
exports.addMessage = functions.https.onRequest(async (req, res) => {
  // Grab the text parameter.
  const original = req.query.text;
  // Push the new message into Cloud Firestore using the Firebase Admin SDK.
  const writeResult = await admin.firestore().collection('messages').add({original: original});
  // Send back a message that we've successfully written the message
  res.json({result: `Message with ID: ${writeResult.id} added.`});
});

// Listens for new messages added to /messages/:documentId/original and creates an
// uppercase version of the message to /messages/:documentId/uppercase
exports.makeUppercase = functions.firestore.document('/messages/{documentId}')
    .onCreate((snap, context) => {
      // Grab the current value of what was written to Cloud Firestore.
      const original = snap.data().original;

      // Access the parameter `{documentId}` with `context.params`
      functions.logger.log('Uppercasing', context.params.documentId, original);

      const uppercase = original.toUpperCase();

      // You must return a Promise when performing asynchronous tasks inside a Functions such as
      // writing to Cloud Firestore.
      // Setting an 'uppercase' field in Cloud Firestore document returns a Promise.
      return snap.ref.set({uppercase}, {merge: true});
    });

Langkah berikutnya

Dalam dokumentasi ini, Anda dapat menemukan informasi lebih lanjut seputar konsep umum untuk Cloud Functions serta panduan untuk fungsi penulisan guna menangani jenis peristiwa yang didukung oleh Cloud Functions.

Untuk mempelajari lebih lanjut tentang Cloud Functions, Anda juga dapat melakukan hal berikut:

Video tutorial

Anda dapat mempelajari lebih lanjut tentang Cloud Functions dengan menonton video tutorial. Dalam video ini, Anda akan menemukan panduan terperinci untuk memulai Cloud Functions, termasuk penyiapan Node.js dan CLI.