Mengelola konfigurasi project dengan manifes Ekstensi

Manifes ekstensi adalah daftar instance ekstensi dan konfigurasinya. Dengan manifes, Anda dapat:

  • Membagikan konfigurasi ekstensi kepada orang lain
  • Menyalin konfigurasi ekstensi Anda di antara berbagai project (misalnya, dari project staging ke project produksi)
  • Men-deploy semua ekstensi Anda sekaligus
  • Menguji cara kerja ekstensi dengan aplikasi menggunakan Firebase Local Emulator Suite
  • Melakukan commit konfigurasi ekstensi ke kontrol sumber
  • Menyertakan ekstensi di pipeline CI/CD

Manifes ekstensi memiliki dua bagian:

  • Bagian extensions dari firebase.json Anda, yang merupakan peta ID instance ke referensi versi ekstensi. Contoh:

    {
 "extensions": {
   "my-bigquery-extension": "firebase/firestore-bigquery-export@^0.1.18",
   "my-image-resizer": "firebase/storage-resize-images@^0.1.22",
 }
}

  • File .env yang berisi konfigurasi untuk setiap instance ekstensi, di subdirektori extensions/ dari direktori project Firebase Anda. Misalnya, instance storage-resize-images mungkin memiliki file .env seperti berikut:

    IMAGE_TYPE=jpeg
LOCATION=us-central1
IMG_BUCKET=${param:PROJECT_ID}.appspot.com
IMG_SIZES=100x100
DELETE_ORIGINAL_FILE=false

Membuat manifes ekstensi

Ada tiga cara untuk mem-build manifes ekstensi:

  • Mengelola manifes ekstensi dengan Firebase CLI
  • Mengekspor konfigurasi ekstensi project
  • Mengedit file manifes secara manual

Dua metode pertama dijelaskan di bawah.

Mengelola manifes ekstensi dengan Firebase CLI

Anda dapat menjalankan sebagian besar perintah ext: Firebase CLI dengan opsi --local untuk mengupdate manifes ekstensi tanpa benar-benar mengubah konfigurasi project saat ini.

Contoh:

firebase ext:install --local firebase/firestore-bigquery-export

Jika menjalankan perintah di atas, Anda akan diminta untuk mengonfigurasi versi terbaru dari ekstensi firebase/firestore-bigquery-export dan menyimpan konfigurasi ke manifes, tetapi ekstensi ini tidak akan men-deploy konfigurasi ke project Anda.

Berikut beberapa contoh perintah yang mengubah manifes ekstensi:

# ext:configure changes the params for an extension instance in your extensions manifest
$ firebase ext:configure my-bigquery-extension --local

# ext:update --local updates an instance in your extensions manifest
# to the latest version of that extension
$ firebase ext:update my-bigquery-extension --local

# You can also specify a version if you don't want to update to the latest version
$ firebase ext:update my-bigquery-extension firebase/firestore-bigquery-export@0.1.10 --local 

# ext:uninstall --local removes an instance from your extensions manifest
$ firebase ext:uninstall my-bigquery-extension --local

Mengekspor konfigurasi ekstensi suatu project

Untuk menyimpan konfigurasi ekstensi project saat ini ke manifes, lakukan langkah berikut:

  1. Jika Anda belum melakukannya, siapkan Firebase CLI
  2. Dari perintah shell, ubah ke direktori project. (Direktori project Anda berisi file firebase.json).
  3. Jalankan perintah ext:export: 
    firebase ext:export

Perintah ext:export akan menambahkan bagian extensions ke file firebase.json. Selain itu, perintah ext:export akan membuat direktori extensions yang berisi file .env untuk setiap instance ekstensi yang telah diinstal. File ini berisi parameter konfigurasi untuk setiap instance.

Menguji konfigurasi ekstensi dengan Firebase Local Emulator Suite

Setelah menambahkan beberapa instance ekstensi ke manifes ekstensi, Anda dapat mengujinya menggunakan Local Emulator Suite.

  1. Menginstal dan mengonfigurasi Local Emulator Suite.

  2. Mulai Local Emulator Suite:

    • Untuk menjalankan Emulator Suite secara interaktif, jalankan: firebase emulators:start
    • Untuk menjalankan Emulator Suite dan menjalankan skrip pengujian, jalankan: firebase emulators:exec my-test.sh

Sekarang, jika Anda memiliki instance ekstensi yang tercantum dalam manifes, Local Emulator Suite akan mendownload kode sumber ekstensi tersebut ke ~/.cache/firebase/extensions. Setelah didownload, Local Emulator Suite akan dimulai dan Anda dapat memicu fungsi yang dipicu latar belakang ekstensi dan menghubungkan aplikasi ke Emulator Suite untuk menguji integrasinya dengan aplikasi Anda.

Men-deploy konfigurasi ekstensi ke project

Setelah menambahkan beberapa instance ekstensi ke manifes ekstensi, Anda dapat men-deploy-nya ke suatu project menggunakan Firebase CLI. Saat men-deploy dengan manifes ekstensi, Anda menginstal, mengupdate, dan mengonfigurasi semua instance ekstensi di manifes ke dalam suatu project sekaligus.

Untuk men-deploy manifes ekstensi:

  1. Dari perintah shell, ubah ke direktori yang berisi konfigurasi ekstensi yang disimpan. (Ini adalah direktori yang berisi firebase.json. Jika baru saja menjalankan ext:export, Anda sudah berada di direktori yang tepat.)
  2. Jalankan perintah deploy. Jika Anda ingin men-deploy ekstensi ke project selain ekstensi saat ini, tentukan juga --project=: 
    firebase deploy --only extensions –-project=YOUR_PROJECT_ID

Perintah deploy akan memvalidasi setiap konfigurasi instance, menanyakan apakah Anda ingin menghapus instance ekstensi dari project tujuan yang tidak tercantum dalam firebase.json, lalu men-deploy semua instance ekstensi Anda.

Konfigurasi ekstensi khusus project

Konfigurasi ekstensi yang tersimpan dapat digunakan untuk men-deploy ke beberapa project berbeda, misalnya project staging dan project produksi. Saat melakukannya, beberapa parameter value mungkin harus berbeda untuk setiap project. Anda dapat melakukannya dengan file .env khusus project:

  • Masukkan parameter value yang berbeda di antara project di extensions/EXTENSION_INSTANCE_ID.env.YOUR_PROJECT_ID
  • Masukkan parameter value bersama di extensions/EXTENSION_INSTANCE_ID.env.

Terkadang, Anda mungkin ingin menggunakan parameter value yang berbeda saat mengemulasi ekstensi: misalnya, Anda mungkin ingin memberikan kunci API pengujian, bukan kunci API produksi. Masukkan parameter ini dalam file .local:

  • Masukkan parameter non-rahasia yang ingin Anda gunakan selama emulasi di extensions/EXTENSION_INSTANCE_ID.env.local
  • Masukkan parameter value rahasia di extensions/EXTENSION_INSTANCE_ID.secret.local