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.

Tips: Realtime Database dan Cloud Storage memungkinkan, secara berurutan, beberapa instance database dan bucket dalam satu project Firebase. Jadi, Anda mungkin perlu menyiapkan parameter yang dikonfigurasi pengguna untuk meminta pengguna menentukan instance atau bucket mana yang mereka inginkan untuk digunakan oleh ekstensi (bukannya berasumsi bahwa pengguna ingin ekstensi menggunakan instance atau bucket default project).

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: project-id.appspot.com Contoh nilai: project-123.appspot.com
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 Pastikan untuk menempatkan tanda kutip di sekitar string ini untuk mencegah konversi jenis yang tidak disengaja. Kolom value bersifat wajib untuk kolom options. Jika label dihilangkan, opsi daftar akan ditetapkan secara default untuk menampilkan value. contoh sintaksis options: - label: value: - label: value: - label: 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 Bucket Cloud Storage 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