Plik extension.yaml – informacje poglądowe

Plik specyfikacji rozszerzenia (extension.yaml) zawiera metadane rozszerzenia, deklaruje zasoby utworzone przez rozszerzenie oraz interfejsy API i dostęp wymagany przez rozszerzenie, a także definiuje parametry skonfigurowane przez użytkownika, które są udostępniane przez rozszerzenie.

Tabele na tej stronie opisują pola dostępne w pliku extension.yaml.

Informacje podstawowe i umożliwiające identyfikację

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/
Pola podstawowe
name
string
(wymagany)

Identyfikator rozszerzenia.

Może zawierać tylko małe litery, cyfry i łączniki. Limit znaków: 40.

Uwaga: ta wartość służy do generowania identyfikatora instancji rozszerzenia (który jest następnie używany do generowania nazw konta usługi rozszerzenia i zasobów powiązanych z rozszerzeniem).

version
string
(wymagany)

Wersja rozszerzenia.

Musi być zgodna z obsługą wersji semantycznej (np. 1.2.0).
specVersion
string
(wymagany)

Wersja specyfikacji Rozszerzeń w Firebase.

Bieżąca wartość: v1beta
license
string
(opcjonalnie)

Licencja na rozszerzenie.

Rozszerzenie musi być licencjonowane za pomocą Apache-2.0.
billingRequired
boolean
(opcjonalnie)

Czy usługi używane przez rozszerzenie wymagają płatnego konta rozliczeniowego Firebase.

Zawsze ma wartość true.
displayName
string
(opcjonalnie)

Przyjazna wyświetlana nazwa rozszerzenia (3–5 słów).

Limit znaków: 40.
description
string
(opcjonalnie) 		Krótki opis zadania, które wykonuje rozszerzenie (około 1 zdania).
icon
string
(opcjonalnie)

Plik, który ma być używany jako ikona rozszerzenia na stronie extensions.dev i w konsoli Firebase.

Ten plik musi być kwadratowym obrazem PNG o rozmiarze od 512 x 512 do 1024 x 1024 pikseli. Umieść plik w tym samym katalogu co extension.yaml. Nie możesz określić podkatalogu.

Podczas projektowania ikony rozszerzenia pamiętaj o tych wskazówkach:

  • Wybierz kolory tła i grafiki, które pasują do Twojej marki.
  • Używaj prostych kolorów ikon, ograniczając się do 2 kolorów. Zbyt wiele kolorów może sprawić, że ikona będzie przytłaczać wizualnie.
  • Z tego samego powodu nie używaj w ikonie gradientów. Gradienty są trudne do odróżnienia w małych rozmiarach i sprawiają, że ikona jest wizualnie złożona.
  • Używaj prostych, unikalnych obrazów, które przedstawiają funkcje rozszerzenia.
  • Jeśli Twoja firma tworzy wiele rozszerzeń, nie używaj logo jako ikony. Użytkownicy będą mieli trudności z odróżnieniem Twoich rozszerzeń.
  • Stwórz grafikę i pogrubienie. Nie używaj delikatnych ani skomplikowanych grafik, które nie będą dobrze wyglądać w mniejszych rozmiarach.
  • Nie używaj słów, które wyjaśniają, co robi rozszerzenie. Tekst jest często nieczytelny przy mniejszych rozmiarach.
tags
lista ciągów znaków
(opcjonalnie) 		Tagi, które pomogą użytkownikom znaleźć Twoje rozszerzenie. Te tagi są mapowane na kategorie w Centrum rozszerzeń: marketing, messaging, payments, search, shipping, social, utilities, ai.
sourceUrl
string
(opcjonalnie) 		Publiczny adres URL, pod którym można uzyskać dostęp do katalogu rozszerzeń.
releaseNotesUrl
string
(opcjonalnie) 		Publiczny adres URL, pod którym można uzyskać dostęp do informacji o wersji rozszerzenia.
author
1 obiekt author
(opcjonalny)

Główny autor i osoba kontaktowa w sprawie rozszerzenia.

author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/
Pola autora
authorName
string
(wymagany)

Imię i nazwisko autora.

Może to być osoba, firma, organizacja itp.
email
string
(opcjonalnie) 		Adres e-mail autora.
url
string
(opcjonalnie) 		Publiczny adres URL, pod którym można uzyskać informacje o autorze.
contributors
Lista obiektów Author
(opcjonalne)

Wszyscy dodatkowi autorzy rozszerzenia.

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

Imię i nazwisko autora.

Może to być osoba, firma, organizacja itp.
email
string
(opcjonalnie) 		Adres e-mail autora.
url
string
(opcjonalnie) 		Publiczny adres URL, pod którym można uzyskać informacje o autorze.

Interfejsy API Firebase i Google Cloud

Te pola określają interfejsy API Firebase i Google, których używa rozszerzenie. Gdy użytkownicy instalują rozszerzenie, mogą automatycznie włączyć te interfejsy API w swoim projekcie.

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
Pola interfejsu API
apiName
string
(wymagany)

Nazwa interfejsu API Google

Musi odpowiadać polu Nazwa usługi na stronie przeglądu każdego interfejsu API (przykład) w bibliotece Cloud APIs Google.

reason
string
(wymagany) 		Krótki opis, dlaczego rozszerzenie musi używać tego interfejsu API

Role uprawnień

Te pola określają role Cloud IAM, których wymaga rozszerzenie. Konto usługi udostępnione dla rozszerzenia ma przypisane te role.

Możesz określić tylko jedną z obsługiwanych ról.

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
Pola ról
role
string
(wymagany)

Nazwa roli uprawnień wymaganej do działania rozszerzenia.

Musi to być jedna z obsługiwanych ról.

reason
string
(wymagany) 		Krótki opis, dlaczego rozszerzenie potrzebuje dostępu przyznanego przez tę rolę
resource
string
(opcjonalnie)

Ogranicz zakres roli do tego zasobu.

Jeśli zostanie pominięty, domyślnie używana jest wartość projects/${project_id}. Zobacz Ograniczanie zakresu ról.

Usługi zewnętrzne

Te pola określają usługi inne niż Firebase i Google, których używa rozszerzenie (zwykle interfejsy API REST). Platforma Rozszerzenia w Firebase nie zapewnia żadnych sposobów automatycznego włączania ani autoryzowania tych usług.

externalServices:
  - name: Example API
    pricingUri: https://developers.example.com/pricing
  - name: Another Example API
    pricingUri: https://developers.example.com/pricing
Pola usług zewnętrznych
name
string
(wymagany) 		Nazwa usługi zewnętrznej wymaganej do działania rozszerzenia.
pricingUri
string
(wymagany) 		Identyfikator URI informacji o cenach usługi

Parametry konfigurowane przez użytkownika

Te pola definiują parametry, które rozszerzenie udostępnia użytkownikom do skonfigurowania.

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
Pola parametru
param
string
(wymagany) 		Nazwa parametru. Ta nazwa służy do odwoływania się do wartości parametru w kodzie.
label
string
(wymagany) 		Krótki opis parametru. Wyświetla się użytkownikowi, gdy jest proszony o podanie wartości parametru.
description
string
(opcjonalnie)

Szczegółowy opis parametru. Wyświetla się użytkownikowi, gdy pojawi się prośba o podanie wartości parametru.

Obsługiwany jest język Markdown.
example
string
(opcjonalnie) 		Przykładowa wartość parametru.
default
string
(opcjonalnie) 		Wartość domyślna parametru, jeśli użytkownik pozostawi wartość parametru pustą.
validationRegex
string
(opcjonalnie) 		Wyrażenie regularne do weryfikacji wartości parametru skonfigurowanej przez użytkownika. składnia Google RE2.
validationErrorMessage
string
(opcjonalnie) 		Komunikat o błędzie wyświetlany, gdy weryfikacja wyrażenia regularnego się nie powiedzie.
required
boolean
(opcjonalnie) 		Określa, czy użytkownik może przesłać pusty ciąg znaków, gdy pojawi się prośba o podanie wartości parametru. Domyślna wartość to true.
immutable
boolean
(opcjonalnie)

Określa, czy użytkownik może zmienić wartość parametru po instalacji (np. jeśli ponownie skonfiguruje rozszerzenie). Domyślna wartość to false.

Uwaga: jeśli zdefiniujesz parametr „location” dla wdrożonych funkcji rozszerzenia, ustaw to pole na true.
type
string
(opcjonalnie) 		Typ parametru. Specjalne typy parametrów mogą mieć dodatkowe wymagania lub inny sposób prezentacji w interfejsie. Zapoznaj się z sekcjami poniżej.

Parametry z możliwością wyboru i wielokrotnego wyboru

Parametry z możliwością wyboru i wielokrotnego wyboru proszą użytkowników o wybranie opcji z listy wstępnie zdefiniowanych opcji.

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
Pola parametrów jednokrotnego wyboru
type
ciąg znaków

select lub multiSelect

Określa, że parametr może mieć jedną wartość (select) lub kilka wartości (multiSelect) wybranych ze zbioru wstępnie zdefiniowanych opcji.
options
lista opcji
(wymagany)

Opcje, które użytkownik może wybrać.

Pola opcji
value
string
(wymagany) 		Jedna z wartości, które użytkownik może wybrać. To jest wartość, którą otrzymujesz, gdy odczytujesz wartość parametru w kodzie.
label
string
(opcjonalnie) 		Krótki opis opcji do wyboru. Jeśli zostanie pominięty, domyślnie używana jest wartość value.

Parametry zasobów, które można wybrać

Parametry zasobów do wyboru proszą użytkowników o wybranie zasobu (instancji bazy danych, zasobnika na dane itp.) z ich projektu.

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
Pola parametrów zasobów
type
ciąg znaków

selectresource

Określa, że parametr reprezentuje zasób projektu
resourceType
string
(wymagany)

Typ zasobu, o którego wybranie zostanie poproszony użytkownik.

Prawidłowe wartości:

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

Jednak obecnie tylko zasobniki Cloud Storage mają interfejs wyboru (inne typy zasobów są prezentowane jako pola do wprowadzania danych).

Parametry obiektu tajnego

Wartości obiektów tajnych podane przez użytkownika (takie jak klucze interfejsu API) są obsługiwane inaczej:

  • Wartości obiektów tajnych są przechowywane za pomocą usługi Cloud Secret Manager. Dostęp do tych wartości mają tylko autoryzowani klienci (np. zainstalowana instancja rozszerzenia).
  • Gdy użytkownicy są proszeni o podanie tych wartości, ich dane wejściowe nie są wyświetlane.
params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What is the secret value?
    type: secret
Pola parametrów tajnych
type
ciąg znaków

secret

Określa, że parametr jest wartością obiektu tajnego

Zasoby funkcji w Cloud Functions

Te pola deklarują funkcje w Cloud Functions zawarte w rozszerzeniu. Składnia deklaracji zasobów wygląda nieco inaczej w przypadku funkcji 1 i 2 generacji, które mogą współistnieć w rozszerzeniu.

Funkcje w Cloud Functions 1 generacji

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
Pola zasobów
name
string
(wymagany)

Przyjazna dla użytkownika nazwa wyeksportowanej funkcji.

Jeśli nie określisz właściwości entryPoint (patrz poniżej), ta wartość musi być zgodna z nazwą funkcji w kodzie źródłowym funkcji.

Ostateczna nazwa wdrożonej funkcji będzie miała taki format: ext-extension-instance-id-name.
type
string
(wymagany) 		W przypadku zasobu funkcji 1 generacji: firebaseextensions.v1beta.function
description
string
(wymagany)

Krótki opis zadania, które funkcja wykonuje na potrzeby rozszerzenia.
properties
(wymagane)

Właściwości funkcji w Cloud Functions 1 generacji. Najważniejsze właściwości są wymienione poniżej, ale pełną listę znajdziesz w dokumentacji Cloud Functions.

Usługi
location
(opcjonalnie)

Lokalizacja, w której ma zostać wdrożona funkcja. Domyślna wartość to us-central1
entryPoint
(opcjonalnie) 		Nazwa wyeksportowanej funkcji w kodzie źródłowym funkcji, której powinno szukać rozszerzenie. Domyślnie jest to wartość name (patrz wyżej).
sourceDirectory
(opcjonalnie)

Katalog, który zawiera plik package.json w katalogu głównym. Plik z kodem źródłowym funkcji musi znajdować się w tym katalogu. Domyślna wartość to functions

Uwaga: pole main w package.json określa plik kodu źródłowego funkcji (np. index.js).
timeout
(opcjonalnie)

Maksymalny czas wykonania funkcji.

  • Domyślnie: 60s
  • Wartość maksymalna: 540s
availableMemoryMb
(opcjonalnie)

Ilość pamięci w MB dostępnej dla funkcji.

  • Domyślnie: 256
  • thought Prawidłowe wartości: 128, 256, 512, 1024 i 2048
runtime
(zalecane)

Środowisko wykonawcze funkcji.
httpsTrigger
lub
eventTrigger
lub
scheduleTrigger
lub
taskQueueTrigger
(wymagany jest jeden z tych typów aktywatorów funkcji) 		Szczegółowe informacje o poszczególnych typach aktywatorów znajdziesz w artykule Pisanie funkcji w Cloud Functions na potrzeby rozszerzenia.

Cloud Functions 2 generacji

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
Pola zasobów
name
string
(wymagany)

Przyjazna dla użytkownika nazwa wyeksportowanej funkcji.

Jeśli nie określisz właściwości entryPoint (patrz poniżej), ta wartość musi być zgodna z nazwą funkcji w kodzie źródłowym funkcji.

Ostateczna nazwa wdrożonej funkcji będzie miała taki format: ext-extension-instance-id-name.
type
string
(wymagany) 		W przypadku zasobu funkcji 2 generacji: firebaseextensions.v1beta.v2function
description
string
(wymagany)

Krótki opis zadania, które funkcja wykonuje na potrzeby rozszerzenia.
properties
(wymagane)

Właściwości funkcji Cloud Functions 2 generacji. Najważniejsze właściwości są wymienione poniżej, ale pełną listę znajdziesz w dokumentacji Cloud Functions.

Usługi
location
(opcjonalnie)

Lokalizacja, w której ma zostać wdrożona funkcja. Domyślna wartość to us-central1
sourceDirectory
(opcjonalnie)

Katalog, który zawiera plik package.json w katalogu głównym. Plik z kodem źródłowym funkcji musi znajdować się w tym katalogu. Domyślna wartość to functions

Uwaga: pole main w package.json określa plik kodu źródłowego funkcji (np. index.js).

Dostępne są też 3 pola typu obiekt z własnymi właściwościami:

Właściwości buildConfig
buildConfig.runtime
(zalecane)

Środowisko wykonawcze funkcji.
buildConfig.entryPoint
(opcjonalnie) 		Nazwa wyeksportowanej funkcji w kodzie źródłowym funkcji, której powinno szukać rozszerzenie. Domyślnie jest to wartość name (patrz wyżej).
Właściwości serviceConfig
serviceConfig.timeoutSeconds
(opcjonalnie)

Maksymalny czas wykonania funkcji.

  • Domyślnie: 60
  • Wartość maksymalna: 540
serviceConfig.availableMemory
(opcjonalnie) 		Ilość pamięci dostępnej dla funkcji. Domyślna wartość to 256M. Obsługiwane jednostki to k, M, G, Mi, Gi. Jeśli nie podasz jednostki, wartość zostanie zinterpretowana jako bajty.
Właściwości eventTrigger
eventTrigger.eventType
(wymagane) 		Typ zdarzenia, które ma być nasłuchiwane. Typy zdarzeń dostępne w przypadku poszczególnych usług znajdziesz w artykule Pisanie funkcji w Cloud Functions na potrzeby rozszerzenia.
eventTrigger.eventFilters
(opcjonalnie) 		Filtry, które dodatkowo ograniczają zdarzenia do nasłuchiwania. Możesz na przykład nasłuchiwać tylko zdarzeń pasujących do określonego wzorca zasobu. Informacje o filtrowaniu poszczególnych typów zdarzeń znajdziesz w artykule Pisanie funkcji w Cloud Functions na potrzeby rozszerzenia.
eventTrigger.channel
(opcjonalnie) 		Nazwa kanału powiązanego z aktywatorem w formacie projects/{project}/locations/{location}/channels/{channel}. Jeśli pominiesz tę właściwość, funkcja będzie nasłuchiwać zdarzeń na domyślnym kanale projektu.
eventTrigger.triggerRegion
(opcjonalnie) 		Aktywator będzie otrzymywać tylko zdarzenia pochodzące z tego regionu. Może to być ten sam region co funkcja, inny region, wiele regionów lub region globalny. Jeśli nie zostanie podany, domyślnie zostanie użyty ten sam region co funkcja.

Zdarzenia cyklu życia

Zdarzenia cyklu życia umożliwiają określenie funkcji, które będą uruchamiane, gdy użytkownik zainstaluje, zaktualizuje lub skonfiguruje instancję rozszerzenia. Zobacz Obsługa zdarzeń cyklu życia rozszerzenia.

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
Pola zdarzeń cyklu życia
onInstall
(opcjonalnie)

Określa funkcję, która jest uruchamiana, gdy użytkownik instaluje rozszerzenie.

Specyfikacja funkcji
function
string
(wymagany)

Nazwa funkcji wywoływanej przez kolejkę zadań, która będzie obsługiwać zdarzenie.

Ta funkcja musi być zadeklarowana w sekcji resources i mieć zdefiniowaną właściwość taskQueue.
processingMessage
string
(wymagany) 		Wiadomość, która ma się wyświetlać w konsoli Firebase podczas wykonywania zadania.
onUpdate
(opcjonalnie)

Określa funkcję, która jest uruchamiana, gdy użytkownik aktualizuje rozszerzenie.

Specyfikacja funkcji
function
string
(wymagany)

Nazwa funkcji wywoływanej przez kolejkę zadań, która będzie obsługiwać zdarzenie.

Ta funkcja musi być zadeklarowana w sekcji resources i mieć zdefiniowaną właściwość taskQueue.
processingMessage
string
(wymagany) 		Wiadomość, która ma się wyświetlać w konsoli Firebase podczas wykonywania zadania.
onConfigure
(opcjonalnie)

Określa funkcję, która jest uruchamiana, gdy użytkownik ponownie konfiguruje rozszerzenie.

Specyfikacja funkcji
function
string
(wymagany)

Nazwa funkcji wywoływanej przez kolejkę zadań, która będzie obsługiwać zdarzenie.

Ta funkcja musi być zadeklarowana w sekcji resources i mieć zdefiniowaną właściwość taskQueue.
processingMessage
string
(wymagany) 		Komunikat, który ma się wyświetlać w konsoli Firebase podczas wykonywania zadania.

Zdarzenia niestandardowe (Eventarc)

Zdarzenia niestandardowe to zdarzenia, które rozszerzenie emituje, aby umożliwić użytkownikom wstawianie do niego własnej logiki. Zobacz sekcję Eventarc w artykule Dodawanie punktów zaczepienia użytkownika do rozszerzenia.

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
Pola zdarzeń niestandardowych
type
string
(wymagany) 		Identyfikator typu zdarzenia. Utwórz identyfikator składający się z 3–4 pól rozdzielonych kropkami: pola identyfikatora wydawcy, nazwy rozszerzenia i nazwy zdarzenia są wymagane, a pole wersji jest zalecane. Wybierz unikalną i opisową nazwę zdarzenia dla każdego typu zdarzenia, które publikujesz.
description
string
(wymagany) 		Opis zdarzenia.