Menyiapkan dan menggunakan parameter di ekstensi Anda

Parameter adalah mekanisme yang digunakan pengguna untuk menyesuaikan setiap instance ekstensi yang diinstal. Parameter mirip seperti variabel lingkungan untuk ekstensi. Nilai untuk parameter dapat terisi otomatis (disediakan oleh Firebase setelah penginstalan) atau dikonfigurasi pengguna (ditentukan oleh pengguna selama penginstalan).

Parameter ini tersedia untuk Anda referensikan dalam kode sumber fungsi ekstensi, file extension.yaml, dan file POSTINSTALL.md Anda. Berikut adalah sintaksis cara mereferensikan parameter bernama PARAMETER_NAME:

  • Dalam kode sumber fungsi Anda, gunakan modul params (misalnya, params.defineInt("PARAMETER_NAME")) atau process.env.PARAMETER_NAME.

  • Dalam extension.yaml dan POSTINSTALL.md, gunakan ${param:PARAMETER_NAME}.

    Setelah penginstalan, Firebase console akan menampilkan isi file POSTINSTALL.md dan mengisi referensi parameter dengan nilai sebenarnya untuk instance yang diinstal.

Parameter yang terisi otomatis

Setiap instance ekstensi yang diinstal akan otomatis memiliki akses ke sejumlah parameter default dan terisi otomatis yang disediakan oleh Firebase (lihat tabel di bawah). Parameter value ini dapat berupa nilai default untuk project Firebase (seperti bucket Storage default) atau parameter value khusus ekstensi (seperti ID instance ekstensi).

Semua parameter value yang terisi otomatis tidak dapat diubah. Parameter tersebut ditetapkan selama pembuatan project atau penginstalan ekstensi.

Meskipun otomatis mengisi parameter value ini untuk ekstensi, Firebase tidak otomatis menyediakan produk terkait untuk pengguna selama penginstalan. Pengguna yang menginstal ekstensi harus mengaktifkan produk yang terkait dan berlaku dalam project-nya sebelum penginstalan. Misalnya, jika ekstensi Anda menggunakan Cloud Firestore, pengguna harus menyiapkan Cloud Firestore dalam project-nya. Sebaiknya beri tahukan persyaratan ini kepada pengguna dalam file PREINSTALL.md.

Referensi untuk parameter yang terisi otomatis Deskripsi Parameter value (disediakan oleh Firebase)
Parameter dengan nilai default dari project Firebase
PROJECT_ID ID unik untuk project Firebase tempat ekstensi diinstal

Format umum:
project-id

Contoh nilai:
project-123

DATABASE_URL URL instance Realtime Database default project Firebase

Format umum:
https://project-id-default-rtdb.firebaseio.com
(instance AS)
or
https://project-id-default-rtdb.region-code.firebasedatabase.app
(instance non-AS)

Contoh nilai:
https://project-123-default-rtdb.firebaseio.com

DATABASE_INSTANCE

Nama instance Realtime Database default project Firebase

Biasanya, nilai ini sama dengan project ID, atau diakhiri dengan -default-rtdb.

Format umum:
project-id

Contoh nilai:
project-123

STORAGE_BUCKET Nama bucket Cloud Storage default project Firebase

Format umum:

Contoh nilai:
project-123.firebasestorage.app

Parameter dengan nilai default dari penginstalan ekstensi
EXT_INSTANCE_ID

ID unik untuk instance ekstensi yang diinstal

Nilai ini dihasilkan dari kolom name yang ditentukan dalam file extension.yaml.

Format umum untuk instance yang diinstal pertama (otomatis ditetapkan oleh Firebase; tidak dapat diubah oleh pengguna selama penginstalan):
name-from-extension.yaml

Contoh nilai:
my-awesome-extension


Format umum untuk instance yang diinstal kedua dan seterusnya (otomatis ditetapkan oleh Firebase; dapat diubah oleh pengguna selama penginstalan):
name-from-extension.yaml-4-digit-alphanumeric-hash

Contoh nilai:
my-awesome-extension-6m31

Parameter yang dikonfigurasi oleh pengguna

Agar pengguna dapat menyesuaikan setiap instance ekstensi yang diinstal, Anda dapat meminta mereka menentukan parameter value selama penginstalan. Untuk meminta nilai ini, siapkan perintah di bagian params file extension.yaml.

Berikut adalah contoh bagian params, diikuti dengan tabel yang mendeskripsikan semua kolom parameter yang tersedia.

# extension.yaml
...

# Parameters (environment variables) for which the user specifies values during installation
params:
  - param: DB_PATH
    label: Realtime Database path
    description: >-
      What is the Realtime Database path where you will write new text
      for sentiment analysis?
    type: string
    validationRegex: ^\S+$
    validationErrorMessage: Realtime Database path cannot contain spaces.
    example: path/to/posts
    required: true

  - param: TEXT_KEY
    label: Key for text
    description: What is the name of the key that will contain text to be analyzed?
    type: string
    default: textToAnalyze
    required: true

Di bagian params file extension.yaml, gunakan kolom berikut untuk menentukan parameter yang dikonfigurasi pengguna:

Kolom Jenis Deskripsi
param
(wajib) 		string Nama parameter
label
(wajib) 		string

Deskripsi singkat parameter

Ditampilkan kepada pengguna saat mereka diminta memasukkan nilai parameter

description
(opsional) 		string

Deskripsi terperinci parameter

Ditampilkan kepada pengguna saat mereka diminta memasukkan nilai parameter

Mendukung markdown

type
(opsional) 		string

Masukkan mekanisme terkait cara pengguna menetapkan nilai parameter (misalnya, memasukkan teks secara langsung atau memilih dari daftar drop-down)

Nilai yang valid mencakup berikut ini:

  • string: memungkinkan entri teks format bebas (yang dibatasi oleh validationRegex)
  • select: memungkinkan pemilihan satu entri dari daftar opsi yang ditentukan sebelumnya. Jika menentukan nilai ini, Anda juga harus menentukan kolom options.
  • multiSelect: memungkinkan pemilihan satu atau beberapa entri dari daftar opsi yang ditentukan sebelumnya. Jika menentukan nilai ini, Anda juga harus menentukan kolom options.
  • selectResource: memungkinkan pemilihan jenis resource Firebase tertentu (seperti bucket Cloud Storage) dari project pengguna.

    Jika Anda menentukan parameter jenis ini, pengguna akan mendapatkan widget pilihan yang lebih mudah digunakan di UI penginstalan; oleh karena itu, gunakan parameter selectResource jika memungkinkan.

    Jika menentukan nilai ini, Anda juga harus menentukan kolom resourceType.

  • secret: memungkinkan penyimpanan string sensitif, seperti kunci API untuk layanan pihak ketiga. Nilai ini akan disimpan di Cloud Secret Manager.

    Cloud Secret Manager adalah layanan berbayar yang penggunaannya dapat menimbulkan biaya bagi pengguna yang menginstal ekstensi Anda. Jika menggunakan jenis parameter secret, pastikan untuk mendokumentasikan dalam file PREINSTALL bahwa ekstensi Anda menggunakan Cloud Secret Manager.

Jika kolom ini dihilangkan, parameter akan ditetapkan secara default ke type di string.

options
(wajib jika parameter type adalah select atau multiSelect) 		list

Daftar nilai yang dapat dipilih pengguna

Mencakup kolom label dan value dalam kolom options:

  • label (string): deskripsi singkat opsi yang dapat dipilih
  • value (string): nilai sebenarnya dari opsi yang dapat dipilih

Kolom value bersifat wajib untuk kolom options.
Jika label dihilangkan, opsi daftar akan ditetapkan secara default untuk menampilkan value.
resourceType
(wajib jika parameter type adalah selectResource) 		string

Jenis resource Firebase untuk meminta pengguna memilih. Saat ini, hanya bucket Cloud Storage yang mendukung pemilih resource:

Jenis resource ID jenis
Cloud Storage bucket storage.googleapis.com/Bucket

Nilai resourceType yang tidak diketahui akan diabaikan dan UI akan merender parameter sebagai kolom input string bentuk bebas.
example
(opsional) 		string

Contoh nilai untuk parameter
validationRegex
(opsional)
(hanya berlaku jika parameter type adalah string) 		string

String ekspresi reguler untuk validasi nilai yang dikonfigurasi pengguna untuk parameter

Ekspresi reguler dikompilasi menggunakan library go: RE2

Untuk mengetahui detail validasi, lihat Validasi dan pesan error di bawah.

validationErrorMessage
(opsional) 		string

Pesan error yang akan ditampilkan jika validationRegex gagal

Untuk mengetahui detail pesan error, lihat Validasi dan pesan error di bawah.

default
(opsional) 		string

Nilai default untuk parameter jika pengguna mengosongkan nilai parameter

Jika berlaku, Anda dapat menentukan parameter value yang terisi otomatis untuk nilai default (sebagai contoh, lihat parameter IMG_BUCKET dalam ekstensi Resize Images).

required
(opsional) 		boolean

Menentukan apakah pengguna dapat mengirim string kosong saat mereka diminta memasukkan nilai parameter

Jika required dihilangkan, nilai ini akan ditetapkan secara default ke true (artinya, parameter wajib).

immutable
(opsional) 		boolean

Menentukan apakah pengguna dapat mengubah nilai parameter setelah penginstalan (misalnya, jika mereka mengonfigurasi ulang ekstensi)

Jika immutable dihilangkan, nilai ini akan ditetapkan secara default ke false.

Catatan: Jika menentukan parameter "location" untuk fungsi ekstensi yang di-deploy, Anda harus menyertakan kolom immutable dalam objek parameternya.

Validasi dan pesan error untuk nilai yang dikonfigurasi pengguna

Saat menyiapkan parameter dengan type dari string, Anda harus menentukan validasi ekspresi reguler yang sesuai melalui kolom validationRegex parameter.

Selain itu, bagi banyak ekstensi, parameter value yang biasanya diminta adalah jalur database atau bucket Cloud Storage. Perlu diketahui bahwa selama penginstalan, pengonfigurasian ulang, atau update, layanan Extensions tidak memvalidasi hal berikut pada saat entri parameter value:

  • Apakah database atau bucket Cloud Storage yang ditentukan disiapkan dalam project Firebase pengguna
  • Apakah jalur database yang ditentukan ada dalam database pengguna

Namun, jika ekstensi benar-benar men-deploy resource-nya, Firebase console atau Firebase CLI akan menampilkan pesan error jika database atau bucket Cloud Storage yang direferensikan belum disiapkan dalam project tersebut.

Sebaiknya beri tahukan persyaratan ini kepada pengguna melalui file PREINSTALL, agar saat mereka menginstal ekstensi Anda, ekstensi tersebut berhasil diinstal dan berfungsi seperti yang diharapkan.

Parameter sistem

Parameter sistem mengontrol konfigurasi dasar dari suatu resource ekstensi. Karena ditujukan untuk mengontrol konfigurasi resource, parameter sistem tidak dapat diakses sebagai variabel lingkungan dari dalam kode fungsi Anda.

Biasanya, Anda tidak perlu mendeklarasikan apa pun untuk parameter ini di extension.yaml. Parameter sistem secara otomatis ditentukan untuk setiap instance ekstensi, dan pengguna dapat menetapkan nilai kustom saat menginstal ekstensi Anda.

Namun, jika ekstensi memiliki persyaratan resource khusus, Anda dapat menetapkan nilai tertentu pada tingkat per-resource di extension.yaml. Setelan konfigurasi per-resource ini akan menggantikan setelan seluruh instance ekstensi pengguna. Contoh:

resources:
- name: high_memory_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function needs at least 1GB of memory!
  properties:
    httpsTrigger: {}
    runtime: nodejs18
    availableMemoryMb: 1024
- name: normal_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function has no special memory requirements. It will use the
    default value, or the value of `firebaseextension.v1beta.function/memory`
  properties:
    httpsTrigger: {}
    runtime: nodejs18

Parameter sistem yang tersedia adalah:

Nama Label (cocok untuk manusia) Kolom yang sesuai di properties Deskripsi
firebaseextensions.v1beta.function/location Lokasi location Di region mana Cloud Functions harus di-deploy?
firebaseextensions.v1beta.function/memory Memori fungsi memory Berapa megabyte memori yang harus dialokasikan ke setiap fungsi?
firebaseextensions.v1beta.function/timeoutSeconds Waktu tunggu fungsi timeout Berapa detik fungsi harus berjalan sebelum waktu habis?
firebaseextensions.v1beta.function/vpcConnectorEgressSettings Traffic Keluar Konektor VPC vpcConnectorEgressSettings Mengontrol traffic keluar saat konektor VPC dikonfigurasi
firebaseextensions.v1beta.function/vpcConnector Konektor VPC vpcConnector Menghubungkan Cloud Functions ke konektor VPC yang ditentukan.
firebaseextensions.v1beta.function/minInstances Instance fungsi minimum minInstances Jumlah instance minimum dari fungsi ini yang akan dijalankan sekaligus
firebaseextensions.v1beta.function/maxInstances Instance fungsi maksimum maxInstances Jumlah instance maksimum dari fungsi ini yang akan dijalankan sekaligus
firebaseextensions.v1beta.function/ingressSettings Setelan Ingress ingressSettings Mengontrol dari mana traffic masuk diterima
firebaseextensions.v1beta.function/labels Label labels Label untuk diterapkan ke semua resource di ekstensi