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/

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/

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

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

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

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

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

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

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

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

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

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

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