Referensi untuk extension.yaml

File spesifikasi ekstensi (extension.yaml) berisi metadata ekstensi Anda, mendeklarasikan resource yang dibuat oleh ekstensi serta API dan akses yang diperlukan oleh ekstensi, dan menentukan parameter yang dikonfigurasi pengguna yang disediakan oleh ekstensi.

Tabel di halaman ini menjelaskan kolom yang tersedia untuk file extension.yaml.

Informasi dasar dan identifikasi

name: your-extension-name
version: 1.0.0         # Semantic versioning (semver)
specVersion: v1beta    # Always "v1beta"
license: Apache-2.0    # Always "Apache-2.0" (required to publish on extensions.dev)
billingRequired: true  # Always "true"

displayName: Your extension name
description: >-
  Description of the extension. (One or two
  sentences.)
icon: icon.png
tags: [tag, anothertag]

sourceUrl: https://github.com/your-org/your-repo   # GitHub repo URL
releaseNotesUrl: https://github.com/your-org/your-repo/blob/main/CHANGELOG.md

author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/
contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: colleague@example.net
    url: https://github.com/their-org/
Kolom dasar
name
string
(wajib)

ID untuk ekstensi.

Hanya dapat berisi huruf kecil, angka, dan tanda hubung; maksimal 40 karakter

Catatan: Nilai ini digunakan untuk membuat ID instance ekstensi (yang kemudian digunakan untuk membuat nama akun layanan ekstensi dan resource khusus ekstensi).

version
string
(wajib)

Versi ekstensi.

Wajib mengikuti pembuatan versi semver (misalnya 1.2.0)
specVersion
string
(wajib)

Versi spesifikasi Firebase Extensions.

Nilai saat ini: v1beta
license
string
(opsional)

Lisensi untuk ekstensi.

Ekstensi Anda harus dilisensikan menggunakan Apache-2.0.
billingRequired
boolean
(opsional)

Apakah layanan yang digunakan oleh ekstensi memerlukan akun penagihan Firebase paket berbayar atau tidak.

Selalu ditetapkan ke true.
displayName
string
(opsional)

Nama tampilan yang praktis untuk ekstensi (3-5 kata).

Maksimal 40 karakter.
description
string
(opsional) 		Deskripsi singkat tentang tugas yang dijalankan ekstensi Anda (~1 kalimat).
icon
string
(opsional)

File yang akan digunakan sebagai ikon ekstensi Anda di extensions.dev dan Firebase console.

File ini harus berupa PNG persegi antara 512x512 hingga 1024x1024 piksel. Tempatkan file di direktori yang sama dengan extension.yaml; Anda tidak dapat menentukan subdirektori.

Perhatikan panduan berikut saat mendesain ikon untuk ekstensi Anda:

  • Pilih warna latar belakang dan poster yang sesuai untuk merek Anda.
  • Pastikan warna ikon Anda sederhana, hanya menggunakan 2 warna. Terlalu banyak warna dapat membuat ikon Anda terlihat berlebihan secara visual.
  • Karena alasan yang sama, jangan gunakan gradien pada ikon Anda. Gradien sulit dibedakan dalam ukuran kecil dan membuat ikon terlihat rumit.
  • Gunakan gambar yang sederhana dan unik yang mengomunikasikan fungsi ekstensi Anda.
  • Jika perusahaan Anda membuat beberapa ekstensi, jangan gunakan logo sebagai ikon. Pengguna akan kesulitan membedakan ekstensi-ekstensi Anda.
  • Buat poster yang grafis dan jelas. Jangan gunakan gambar yang sulit atau rumit, yang tidak akan dirender dengan baik pada ukuran yang lebih kecil.
  • Jangan sertakan kata-kata yang menjelaskan fungsi ekstensi Anda. Teks sering kali tidak terbaca pada ukuran yang lebih kecil.
tags
daftar string
(opsional) 		Tag akan membantu pengguna menemukan ekstensi Anda. Tag berikut memetakan ke kategori di Extensions Hub: marketing, messaging, payments, search, shipping, social, utilities, ai
sourceUrl
string
(opsional) 		URL publik tempat direktori ekstensi dapat diakses.
releaseNotesUrl
string
(opsional) 		URL publik tempat catatan rilis untuk ekstensi dapat diakses.
author
satu objek penulis
(opsional)

Penulis utama dan kontak untuk ekstensi.

author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/
Kolom penulis
authorName
string
(wajib)

Nama penulis.

Dapat berupa orang, perusahaan, organisasi, dll.
email
string
(opsional) 		Alamat email penulis.
url
string
(opsional) 		URL publik tempat informasi penulis dapat diakses.
contributors
daftar objek penulis
(opsional)

Semua penulis tambahan yang berkontribusi untuk ekstensi.

contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: colleague@example.net
    url: https://github.com/their-org/
Kolom penulis
authorName
string
(wajib)

Nama penulis.

Dapat berupa orang, perusahaan, organisasi, dll.
email
string
(opsional) 		Alamat email penulis.
url
string
(opsional) 		URL publik tempat informasi penulis dapat diakses.

Firebase dan Google Cloud API

Kolom ini menentukan Firebase dan Google API yang digunakan ekstensi. Saat menginstal ekstensi, pengguna dapat memilih untuk mengaktifkan API ini secara otomatis dalam project mereka.

apis:
  - apiName: apiname.googleapis.com
    reason: Explanation of why the extension uses this API
  - apiName: anotherapiname.googleapis.com
    reason: Explanation of why the extension uses this API
Kolom API
apiName
string
(wajib)

Nama Google API

Harus berkaitan dengan kolom Nama layanan seperti yang tercantum di setiap halaman ringkasan API (contoh) di Library Google Cloud API

reason
string
(wajib) 		Deskripsi singkat tentang alasan ekstensi perlu menggunakan API ini

Peran IAM

Kolom ini menentukan peran Cloud IAM yang diperlukan ekstensi. Akun layanan yang disediakan untuk ekstensi diberi peran ini.

Anda hanya dapat menentukan salah satu peran yang didukung.

roles:
  - role: product.role
    reason: Explanation of why the extension needs this level of access
  - role: anotherproduct.role
    resource: projects/${project_id}/resource_type/*
    reason: Explanation of why the extension needs this level of access
Kolom peran
role
string
(wajib)

Nama peran IAM yang diperlukan agar ekstensi dapat beroperasi

Harus berupa salah satu peran yang didukung

reason
string
(wajib) 		Deskripsi singkat tentang alasan ekstensi memerlukan akses yang diberikan oleh peran ini
resource
string
(opsional)

Batasi cakupan peran ke resource ini.

Jika dihilangkan, setelan defaultnya adalah projects/${project_id}. Baca Mengurangi cakupan peran.

Layanan eksternal

Kolom ini menentukan layanan non-Firebase dan non-Google yang digunakan ekstensi (biasanya REST API). Platform Firebase Extensions tidak menyediakan cara untuk mengaktifkan atau melakukan otorisasi secara otomatis untuk layanan ini.

externalServices:
  - name: Example API
    pricingUri: https://developers.example.com/pricing
  - name: Another Example API
    pricingUri: https://developers.example.com/pricing
Kolom layanan eksternal
name
string
(wajib) 		Nama layanan eksternal yang diperlukan agar ekstensi dapat beroperasi
pricingUri
string
(wajib) 		URI ke informasi harga untuk layanan

Parameter yang dapat dikonfigurasi pengguna

Kolom ini menentukan parameter yang disediakan oleh ekstensi untuk dikonfigurasi pengguna.

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What do you want to set PARAM_ID to?
      This is a longer description of the parameter, often phrased as a prompt
      to the user.
  - param: ANOTHER_PARAM_ID
    label: Short description of the parameter
    description: >
      What do you want to set ANOTHER_PARAM_ID to?
      This is a longer description of the parameter.
    example: example-input
    validationRegex: "^[a-zA-Z][a-zA-Z-]*[a-zA-Z]?$"
    validationErrorMessage:
      Must be a hyphen-delimited string of alphabetic characters
    default: default-value
    required: false
    immutable: true
Kolom parameter
param
string
(wajib) 		Nama parameter. Anda menggunakan nama ini untuk mereferensikan parameter value dalam kode.
label
string
(wajib) 		Deskripsi singkat parameter. Ditampilkan kepada pengguna saat mereka diminta memasukkan nilai parameter.
description
string
(opsional)

Deskripsi terperinci parameter. Ditampilkan kepada pengguna saat mereka diminta memasukkan nilai parameter.

Mendukung Markdown.
example
string
(opsional) 		Contoh nilai untuk parameter.
default
string
(opsional) 		Nilai default untuk parameter jika pengguna mengosongkan nilai parameter.
validationRegex
string
(opsional) 		Ekspresi reguler untuk validasi nilai parameter yang dikonfigurasi pengguna. SIntaksis Google RE2.
validationErrorMessage
string
(opsional) 		Pesan error yang akan ditampilkan jika validasi ekspresi reguler gagal.
required
boolean
(opsional) 		Menentukan apakah pengguna dapat mengirim string kosong saat mereka diminta memasukkan nilai parameter. Nilai defaultnya adalah true.
immutable
boolean
(opsional)

Menentukan apakah pengguna dapat mengubah nilai parameter setelah penginstalan (misalnya, jika mereka mengonfigurasi ulang ekstensi). Nilai defaultnya adalah false.

Catatan: Jika Anda menentukan parameter "location" untuk fungsi ekstensi yang di-deploy, tetapkan kolom ini ke true.
type
string
(opsional) 		Jenis parameter. Jenis parameter khusus mungkin memiliki persyaratan tambahan atau presentasi UI yang berbeda. Lihat bagian berikut.

Parameter yang dapat dipilih dan multi-pilihan

Parameter yang dapat dipilih dan multi-pilihan meminta pengguna untuk memilih dari daftar opsi yang telah ditentukan.

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      Do you want to enable the option?
    type: select
    options:
      - label: Yes
        value: true
      - label: No
        value: false
  - param: ANOTHER_PARAM_ID
    label: Short description of the parameter
    description: >-
      Which options do you want to enable?
    type: multiselect
    options:
      - value: red
      - value: green
      - value: blue
Kolom parameter pilihan ganda
type
string

select atau multiselect

Menentukan bahwa parameter dapat berupa satu nilai (select) atau beberapa nilai (multiselect) yang dipilih dari kumpulan pilihan yang telah ditentukan
options
daftar opsi
(wajib)

Opsi-opsi yang dapat dipilih oleh pengguna

Kolom opsi
value
string
(wajib) 		Salah satu nilai yang dapat dipilih pengguna. Ini adalah nilai yang Anda dapatkan saat membaca parameter value dalam kode.
label
string
(opsional) 		Deskripsi singkat opsi yang dapat dipilih. Jika dihilangkan, setelan defaultnya adalah value.

Parameter resource yang dapat dipilih

Parameter resource yang dapat dipilih meminta pengguna untuk memilih resource (instance database, bucket penyimpanan, dsb.) dari project mereka.

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      Which resource do you want to use?
    type: selectresource
    resourceType: product.googleapis.com/ResourceType
Kolom parameter resource
type
string

selectresource

Menentukan bahwa parameter merepresentasikan resource project
resourceType
string
(wajib)

Jenis resource yang akan meminta pengguna memilih.

Nilai valid:

  • storage.googleapis.com/Bucket
  • firestore.googleapis.com/Database
  • firebasedatabase.googleapis.com/DatabaseInstance

Namun, saat ini hanya bucket Cloud Storage yang memiliki UI pilihan (jenis resource lainnya ditampilkan sebagai kolom input teks bentuk bebas).

Parameter secret

Nilai secret yang diberikan pengguna (misalnya, kunci API) ditangani secara berbeda:

  • Nilai secret disimpan menggunakan Cloud Secret Manager. Hanya klien yang diotorisasi (misalnya, instance terinstal dari suatu ekstensi) yang dapat mengakses nilai ini.
  • Saat pengguna diminta untuk memberikan nilai ini, input mereka tidak akan ditampilkan.
params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What is the secret value?
    type: secret
Kolom parameter secret
type
string

secret

Menentukan bahwa parameter adalah nilai secret

Resource Cloud Function

Kolom ini mendeklarasikan Cloud Functions yang disertakan dalam ekstensi. Sintaksis deklarasi resource terlihat sedikit berbeda antara fungsi generasi ke-1 dan generasi ke-2, yang dapat beroperasi berdampingan dalam suatu ekstensi.

Cloud Functions generasi ke-1

resources:
  - name: functionName
    type: firebaseextensions.v1beta.function
    description: >-
      Description of what the function does. (One or two
      sentences.)
    properties:
      runtime: runtime-version
      eventTrigger:
        eventType: google.product.event
        resource: projects/_/resource/specifier
Kolom resource
name
string
(wajib)

Nama yang mudah digunakan untuk fungsi yang diekspor.

Jika Anda tidak menentukan properti entryPoint (lihat di bawah), nilai ini harus cocok dengan nama fungsi dalam kode sumber fungsi Anda.

Nama akhir fungsi yang di-deploy akan menggunakan format berikut: ext-extension-instance-id-name.
type
string
(wajib) 		Untuk resource fungsi generasi ke-1: firebaseextensions.v1beta.function
description
string
(wajib)

Deskripsi singkat tugas yang dijalankan fungsi untuk ekstensi.
properties
(wajib)

Properti Cloud Functions generasi ke-1. Properti yang paling penting tercantum di bawah ini, tetapi Anda dapat menemukan daftar lengkapnya dalam referensi Cloud Functions.

Properti
location
(opsional)

Lokasi yang dituju untuk men-deploy fungsi. Nilai defaultnya adalah us-central1
entryPoint
(opsional) 		Nama fungsi yang diekspor dalam kode sumber fungsi Anda yang harus dicari ekstensi. Nilai defaultnya adalah name, di atas.
sourceDirectory
(opsional)

Direktori yang memuat package.json Anda di root-nya. File untuk kode sumber fungsi Anda harus ada dalam direktori ini. Nilai defaultnya adalah functions.

Catatan: Kolom main dari package.json menentukan file untuk kode sumber fungsi Anda (seperti index.js).
timeout
(opsional)

Waktu eksekusi maksimum fungsi.

  • Default: 60s
  • Nilai maks: 540s
availableMemoryMb
(opsional)

Jumlah memori dalam MB yang tersedia untuk fungsi.

  • Default: 256
  • Nilai yang valid: 128, 256, 512, 1024, dan 2048
runtime
(direkomendasikan)

Lingkungan runtime untuk fungsi.
httpsTrigger
atau
eventTrigger
atau
scheduleTrigger
atau
taskQueueTrigger
(salah satu jenis pemicu fungsi ini wajib ada) 		Baca bagian Menulis Cloud Functions untuk ekstensi guna mengetahui informasi spesifik tentang setiap jenis pemicu.

Cloud Functions generasi ke-2

resources:
  - name: functionName
    type: firebaseextensions.v1beta.v2function
    description: >-
      Description of what the function does. (One or two
      sentences.)
    properties:
      buildConfig:
        runtime: nodejs16
      serviceConfig:
        availableMemory: 512M
      eventTrigger:
        eventType: google.firebase.firebasealerts.alerts.v1.published
        triggerRegion: global
        eventFilters:
          - attribute: alerttype
            value: crashlytics.newFatalIssue
Kolom resource
name
string
(wajib)

Nama yang mudah digunakan untuk fungsi yang diekspor.

Jika Anda tidak menentukan properti entryPoint (lihat di bawah), nilai ini harus cocok dengan nama fungsi dalam kode sumber fungsi Anda.

Nama akhir fungsi yang di-deploy akan menggunakan format berikut: ext-extension-instance-id-name.
type
string
(wajib) 		Untuk resource fungsi generasi ke-2: firebaseextensions.v1beta.v2function
description
string
(wajib)

Deskripsi singkat tugas yang dijalankan fungsi untuk ekstensi.
properties
(wajib)

Properti Cloud Functions generasi ke-2. Properti yang paling penting tercantum di bawah ini, tetapi Anda dapat menemukan daftar lengkapnya dalam referensi Cloud Functions.

Properti
location
(opsional)

Lokasi yang dituju untuk men-deploy fungsi. Nilai defaultnya adalah us-central1
sourceDirectory
(opsional)

Direktori yang memuat package.json Anda di root-nya. File untuk kode sumber fungsi Anda harus ada dalam direktori ini. Nilai defaultnya adalah functions.

Catatan: Kolom main dari package.json menentukan file untuk kode sumber fungsi Anda (seperti index.js).

Ada juga tiga kolom jenis objek dengan propertinya sendiri:

Properti buildConfig
buildConfig.runtime
(direkomendasikan)

Lingkungan runtime untuk fungsi.
buildConfig.entryPoint
(opsional) 		Nama fungsi yang diekspor dalam kode sumber fungsi Anda yang harus dicari ekstensi. Nilai defaultnya adalah name, di atas.
Properti serviceConfig
serviceConfig.timeoutSeconds
(opsional)

Waktu eksekusi maksimum fungsi.

  • Default: 60
  • Nilai maks: 540
serviceConfig.availableMemory
(opsional) 		Jumlah memori yang tersedia untuk suatu fungsi. Nilai defaultnya adalah 256M. Unit yang didukung adalah k, M, G, Mi, Gi. Jika tidak ada unit yang diberikan, nilai akan ditafsirkan sebagai byte.
Properti eventTrigger
eventTrigger.eventType
(wajib) 		Jenis peristiwa yang akan diproses. Baca artikel Menulis Cloud Functions untuk ekstensi guna mengetahui jenis peristiwa yang tersedia untuk setiap produk.
eventTrigger.eventFilters
(opsional) 		Filter yang lebih lanjut membatasi peristiwa yang akan diproses. Misalnya, Anda hanya dapat memproses peristiwa yang cocok dengan pola resource tertentu. Baca artikel Menulis Cloud Functions untuk ekstensi guna mengetahui informasi tentang cara memfilter setiap jenis peristiwa.
eventTrigger.channel
(opsional) 		Nama saluran yang terkait dengan pemicu dalam format projects/{project}/locations/{location}/channels/{channel}. Jika Anda menghapus properti ini, fungsi tersebut akan memproses peristiwa di saluran default project.
eventTrigger.triggerRegion
(opsional) 		Pemicu hanya akan menerima peristiwa yang berasal dari region ini. Region dapat berupa region yang sama dengan fungsi, region atau multi-region yang berbeda, atau region global. Jika tidak diberikan, defaultnya adalah region yang sama dengan fungsi.

Peristiwa siklus proses

Peristiwa siklus proses memungkinkan Anda menentukan fungsi yang akan dijalankan saat pengguna menginstal, memperbarui, atau mengonfigurasi instance ekstensi Anda. Baca artikel Menangani peristiwa siklus proses ekstensi.

lifecycleEvents:
  onInstall:
    function: myTaskFunction
    processingMessage: Describes the task being completed
  onUpdate:
    function: myOtherTaskFunction
    processingMessage: Describes the task being completed
  onConfigure:
    function: myOtherTaskFunction
    processingMessage: Describes the task being completed
Kolom peristiwa siklus proses
onInstall
(opsional)

Menentukan fungsi yang dijalankan saat pengguna menginstal ekstensi.

Spesifikasi fungsi
function
string
(wajib)

Nama fungsi yang dipicu task queue yang akan menangani peristiwa.

Fungsi ini harus dideklarasikan di bagian resources dan memiliki taskQueue yang ditentukan.
processingMessage
string
(wajib) 		Pesan akan ditampilkan di Firebase console saat tugas sedang berlangsung.
onUpdate
(opsional)

Menentukan fungsi yang dijalankan saat pengguna memperbarui ekstensi.

Spesifikasi fungsi
function
string
(wajib)

Nama fungsi yang dipicu task queue yang akan menangani peristiwa.

Fungsi ini harus dideklarasikan di bagian resources dan memiliki taskQueue yang ditentukan.
processingMessage
string
(wajib) 		Pesan akan ditampilkan di Firebase console saat tugas sedang berlangsung.
onConfigure
(opsional)

Menentukan fungsi yang dijalankan saat pengguna mengonfigurasi ulang ekstensi.

Spesifikasi fungsi
function
string
(wajib)

Nama fungsi yang dipicu task queue yang akan menangani peristiwa.

Fungsi ini harus dideklarasikan di bagian resources dan memiliki taskQueue yang ditentukan.
processingMessage
string
(wajib) 		Pesan akan ditampilkan di Firebase console saat tugas sedang berlangsung.

Peristiwa kustom (Eventarc)

Peristiwa kustom adalah peristiwa yang dikeluarkan ekstensi Anda untuk memungkinkan pengguna memasukkan logika mereka sendiri ke dalam ekstensi Anda. Lihat bagian Eventarc di artikel Menambahkan hook pengguna ke ekstensi.

events:
  - type: publisher-id.extension-name.version.event-name
    description: Description of the event
  - type: publisher-id.extension-name.version.another-event-name
    description: Description of the other event
Kolom peristiwa kustom
type
string
(wajib) 		ID jenis peristiwa. Buat ID dari 3-4 kolom yang dipisahkan titik: kolom ID penayang, nama ekstensi, dan nama peristiwa wajib ada; kolom versi direkomendasikan. Pilih nama peristiwa yang unik dan deskriptif untuk setiap jenis peristiwa yang Anda publikasikan.
description
string
(wajib) 		Deskripsi peristiwa.