Dokumentacja rozszerzeniaextension.yaml

Plik specyfikacji rozszerzenia (extension.yaml) zawiera następujące dane: metadanych, deklaruje zasoby utworzone przez rozszerzenie i interfejsy API oraz dostępu wymaganego przez rozszerzenie i definiuje wszystkie parametry skonfigurowane przez użytkownika udostępniane przez rozszerzenie.

Tabele na tej stronie zawierają opis pól dostępnych dla: extension.yaml .

Podstawowe informacje 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
ciąg znaków
(wymagane)

Identyfikator rozszerzenia.

Może zawierać tylko małe litery, cyfry i myślniki. 40 znaków .

Uwaga: ta wartość służy do generowania parametru instancji (który jest następnie używany do generowania nazw konto usługi rozszerzenia i zasoby dotyczące danego rozszerzenia).

version
ciąg znaków
(wymagane)

Wersja rozszerzenia.

Musi być zgodna z obsługą wersji semver (np. 1.2.0).

specVersion
ciąg znaków
(wymagane)

Wersja specyfikacji rozszerzeń w Firebase.

Bieżąca wartość: v1beta

license
ciąg znaków
(opcjonalnie)

Licencja na rozszerzenie.

Rozszerzenie musi być licencjonowane przez: Apache-2.0.

billingRequired
wartość logiczna
(opcjonalnie)

czy usługi wykorzystywane przez rozszerzenie wymagają poziomu płatnego. konta rozliczeniowego Firebase.

Zawsze ustawiona na true.

displayName
ciąg znaków
(opcjonalnie)

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

Obowiązuje limit 40 znaków.

description
ciąg znaków
(opcjonalnie)
Krótki opis zadania wykonywanego przez rozszerzenie (ok. 1 zdanie).
icon
ciąg znaków
(opcjonalnie)

Plik, który będzie używany jako ikona rozszerzenia extensions.dev i w konsoli Firebase.

Ten plik musi być kwadratowym plikiem PNG o wymiarach od 512 x 512 do 1024 x 1024 pikseli. Umieść plik w tym samym katalogu, w którym znajduje się katalog extension.yaml. Ty nie można określić podkatalogu.

Projektując ikonę dla swojej ikony, pamiętaj o poniższych wskazówkach. rozszerzenie:

  • Wybierz kolory tła i grafiki, które pasują do Twojego marki.
  • Używaj prostych kolorów ikon, używając tylko 2 kolorów. Wiele kolorów może sprawić, że Twoja ikona będzie przytłaczająca.
  • Z tego samego powodu nie używaj w niej gradientów. Gradienty są trudne do rozpoznania przy małym rozmiarze i złożone.
  • Używaj prostych, unikalnych zdjęć, które oddają charakter rozszerzenia funkcji.
  • Jeśli Twoja firma tworzy wiele rozszerzeń, nie używaj logo jako ikonę. Użytkownicy będą mieć trudność z rozróżnieniem rozszerzeń.
  • Postaraj się, aby grafika była wyrazista i pogrubiona. Nie używaj elementów skomplikowanych ani skomplikowanych które nie będą dobrze wyglądać na mniejszych ekranach.
  • Nie używaj słów, które opisują działanie rozszerzenia. Tekst to często nieczytelne przy mniejszych rozmiarach.
tags
lista ciągów
(opcjonalnie)
Tagi, które ułatwiają użytkownikom znalezienie rozszerzenia. Te tagi są mapowane na kategorie w Centrum rozszerzeń: marketing, messaging, payments, search, shipping, social, utilities, ai
sourceUrl
ciąg znaków
(opcjonalnie)
Publiczny adres URL, pod którym można uzyskać dostęp do katalogu rozszerzenia.
releaseNotesUrl
ciąg znaków
(opcjonalnie)
Publiczny adres URL, pod którym można uzyskać dostęp do informacji o wersji rozszerzenia.
author
1 obiekt autora
(opcjonalnie)

Główny autor i osoba kontaktowa ds. rozszerzenia.

author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/
Pola autora
authorName
ciąg znaków
(wymagane)

Imię i nazwisko autora.

Może to być osoba, firma, organizacja itp.

email
ciąg znaków
(opcjonalnie)
Adres e-mail autora.
url
ciąg znaków
(opcjonalnie)
Publiczny adres URL, pod którym można uzyskać dostęp do informacji o autorze.
contributors
lista obiektów autora
(opcjonalnie)

Dodatkowych autorów pracujących nad rozszerzeniem.

contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: colleague@example.net
    url: https://github.com/their-org/
Pola autora
authorName
ciąg znaków
(wymagane)

Imię i nazwisko autora.

Może to być osoba, firma, organizacja itp.

email
ciąg znaków
(opcjonalnie)
Adres e-mail autora.
url
ciąg znaków
(opcjonalnie)
Publiczny adres URL, pod którym można uzyskać dostęp do informacji o autorze.

Interfejsy API Firebase i Google Cloud

Te pola określają interfejsy API Firebase i Google używane przez rozszerzenie. Gdy użytkownicy zainstalować rozszerzenie, może automatycznie włączyć te interfejsy API nad ich projektem.

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
ciąg znaków
(wymagane)

Nazwa interfejsu API Google

Musi odpowiadać polu Nazwa usługi podaną w każdym Strona przeglądu interfejsu API (przykład) w Biblioteka interfejsów API Google Cloud

reason
ciąg znaków
(wymagane)
Krótki opis tego, dlaczego rozszerzenie musi używać tego interfejsu API

Role uprawnień

Te pola określają role Cloud IAM wymagane przez rozszerzenie. Usługa konto udostępnione na potrzeby rozszerzenia otrzyma te role.

Możesz podać tylko jeden 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
ciąg znaków
(wymagane)

Nazwa roli uprawnień niezbędnej do działania rozszerzenia

Musi być jednym z obsługiwane role

reason
ciąg znaków
(wymagane)
Krótki opis powodu, dla którego rozszerzenie potrzebuje dostępu przyznanego przez ta rola
resource
ciąg znaków
(opcjonalnie)

Ogranicz zakres roli do tego zasobu.

W przypadku pominięcia tej opcji stosowana jest domyślna wartość projects/${project_id}. Zobacz sekcję Ograniczenie zakres ról.

Usługi zewnętrzne

Te pola określają usługi spoza Firebase i innych systemów Google, z których korzysta rozszerzenie (zwykle są to interfejsy API typu REST). Platforma Rozszerzenia w Firebase nie udostępnia żadnych środków automatycznego włączania lub przeprowadzania autoryzacji dla 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
ciąg znaków
(wymagane)
Nazwa usługi zewnętrznej niezbędnej do działania rozszerzenia
pricingUri
ciąg znaków
(wymagane)
Identyfikator URI informacji o cenach usługi

Parametry konfigurowane przez użytkownika

Te pola określają parametry, które rozszerzenie udostępnia użytkownikom aby skonfigurować tę funkcję.

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 parametrów
param
ciąg znaków
(wymagane)
Nazwa parametru. Ta nazwa służy do odwoływania się do parametru w kodzie.
label
ciąg znaków
(wymagane)
Krótki opis parametru. Wyświetlane użytkownikowi, gdy pojawi się prośba o podanie wartości parametru.
description
ciąg znaków
(opcjonalnie)

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

Obsługuje format Markdown.

example
ciąg znaków
(opcjonalnie)
Przykładowa wartość parametru.
default
ciąg znaków
(opcjonalnie)
Domyślna wartość parametru, gdy użytkownik pozostawi wartość parametru puste.
validationRegex
ciąg znaków
(opcjonalnie)
Wyrażenie regularne do weryfikacji parametru skonfigurowanego przez użytkownika . Google RE2 .
validationErrorMessage
ciąg znaków
(opcjonalnie)
Komunikat o błędzie wyświetlany w przypadku niepowodzenia weryfikacji wyrażenia regularnego.
required
wartość logiczna
(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
wartość logiczna
(opcjonalnie)

Określa, czy użytkownik może zmienić wartość parametru po instalacji (np. gdy użytkownik zmieni konfigurację rozszerzenia). Domyślna wartość to false

Uwaga: jeśli zdefiniujesz „lokalizację” parametr dla wdrożonego Twojego rozszerzenia ustaw w tym polu wartość true.

type
ciąg znaków
(opcjonalnie)
Typ parametru. Typy parametrów specjalnych mogą zawierać dodatkowe lub innej prezentacji UI. Więcej informacji znajdziesz w sekcjach poniżej.

Parametry, które można wybrać i w sposób umożliwiający ich wybór

Parametry do wyboru lub do wyboru informują użytkownika o wyborze 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 zdefiniowane opcje

options
lista opcji
(wymagane)

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

Pola opcji
value
ciąg znaków
(wymagane)
Jedna z wartości, które może wybrać użytkownik. Oto wartość, jaką zyskujesz .
label
ciąg znaków
(opcjonalnie)
Krótki opis opcji, którą można wybrać. W przypadku pominięcia wartości domyślne do value.

Parametry zasobu do wyboru

Parametry zasobu do wyboru wyświetlają użytkownikom prośbę o wybranie zasobu (baza danych) instancję, zasobnik na dane itp.) z 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
ciąg znaków
(wymagane)

Typ zasobu, o który użytkownik prosi o wybranie.

Prawidłowe wartości:

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

Jednak tylko zasobniki Cloud Storage mają obecnie interfejs wyboru (inne typy zasobów są wyświetlane jako pola do wprowadzania tekstu).

Parametry obiektu tajnego

Wartości obiektów tajnych podanych przez użytkownika (na przykład kluczy interfejsu API) są obsługiwane w inny sposób:

  • Wartości obiektów tajnych są przechowywane przy użyciu usługi Cloud Secret Manager. Tylko autoryzowani klienci (np. zainstalowane wystąpienie rozszerzenia) może uzyskać dostęp do tych wartości.
  • Gdy użytkownicy są proszeni o ich podanie, 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 obiektu tajnego
type
ciąg znaków

secret

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

Zasoby w Cloud Functions

Te pola deklarują funkcje w Cloud Functions dostępne w rozszerzeniu. Zasób składnia deklaracji wygląda nieco inaczej w pierwszej i drugiej generacji które mogą współistnieć w rozszerzeniu.

Funkcje w Cloud Functions pierwszej 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
ciąg znaków
(wymagane)

Przyjazna dla użytkownika nazwa wyeksportowanej funkcji.

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

Ostateczna nazwa wdrożonej funkcji będzie znajdować się w sekcji w tym formacie: ext-extension-instance-id-name.

type
ciąg znaków
(wymagane)
W przypadku zasobu funkcji 1 generacji: firebaseextensions.v1beta.function
description
ciąg znaków
(wymagane)

Krótki opis zadania wykonywanego przez funkcję .

properties
(wymagane)

Usługi w Cloud Functions pierwszej generacji. Najważniejsze właściwości podane niżej, ale ich pełną listę znajdziesz Chmura Dokumentacja funkcji

Usługi
location
(opcjonalnie)

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

entryPoint
(opcjonalnie)
Nazwa wyeksportowanej funkcji w kodzie źródłowym funkcji których ma szukać rozszerzenie. Przyjmuje wartość domyślną name powyżej.
sourceDirectory
(opcjonalnie)

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

Uwaga: pole main parametru package.json określa plik dla 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 dostępnej dla funkcji w MB.

  • Domyślnie: 256
  • 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)
Zobacz Zapis Cloud Functions dla rozszerzenia, aby uzyskać szczegółowe informacje. na temat poszczególnych typów reguł.

Funkcje w Cloud Functions drugiej 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
ciąg znaków
(wymagane)

Przyjazna dla użytkownika nazwa wyeksportowanej funkcji.

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

Ostateczna nazwa wdrożonej funkcji będzie znajdować się w sekcji w tym formacie: ext-extension-instance-id-name.

type
ciąg znaków
(wymagane)
W przypadku zasobu funkcji 2 generacji: firebaseextensions.v1beta.v2function
description
ciąg znaków
(wymagane)

Krótki opis zadania wykonywanego przez funkcję .

properties
(wymagane)

Właściwości w Cloud Functions drugiej generacji. Najważniejsze właściwości podane niżej, ale ich pełną listę znajdziesz Chmura Dokumentacja funkcji

Usługi
location
(opcjonalnie)

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

sourceDirectory
(opcjonalnie)

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

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

Istnieją też 3 pola typu obiektu 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órych ma szukać rozszerzenie. Przyjmuje wartość domyślną name powyż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 żadnej jednostki, wartość zostanie zinterpretowana jako bajty.
właściwości eventTrigger
eventTrigger.eventType
(wymagane)
Typ nasłuchiwanego zdarzenia. Zobacz Zapisywanie w chmurze funkcje rozszerzenia związane z typami zdarzeń dostępnymi w przypadku usługi poszczególnych usług.
eventTrigger.eventFilters
(opcjonalnie)
Filtry, które jeszcze bardziej ograniczają nasłuchiwane zdarzenia. Przykład: można było nasłuchiwać tylko zdarzeń pasujących do określonego zasobu wzorcem. Zobacz Zapisywanie w chmurze funkcje rozszerzenia – informacje o filtrowaniu poszczególnych typu zdarzenia.
eventTrigger.channel
(opcjonalnie)
Nazwa kanału powiązanego z regułą w projects/{project}/locations/{location}/channels/{channel} . Jeśli pominiesz tę właściwość, funkcja będzie nasłuchiwać na domyślnym kanale projektu.
eventTrigger.triggerRegion
(opcjonalnie)
Reguła będzie otrzymywać tylko zdarzenia pochodzące z tego regionu. Może to być ten sam region co funkcja, inny region lub wiele regionów lub region globalny. Jeśli nie zostanie podana, domyślna wartość to w tym samym regionie co funkcja.

Zdarzenia cyklu życia

Zdarzenia cyklu życia pozwalają określić funkcje, które zostaną uruchomione po zainstalowaniu aplikacji przez użytkownika aktualizacje lub skonfigurowanie instancji rozszerzenia. Zapoznaj się z sekcją 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ę uruchamianą po zainstalowaniu przez użytkownika .

Specyfikacja funkcji
function
ciąg znaków
(wymagane)

Nazwa funkcji aktywowanej przez kolejkę zadań, która obsługuje do zdarzenia.

Ta funkcja musi być zadeklarowana w resources i mają zdefiniowane taskQueue.

processingMessage
ciąg znaków
(wymagane)
Komunikat wyświetlany w konsoli Firebase podczas wykonywania zadania postęp.
onUpdate
(opcjonalnie)

Określa funkcję uruchamianą, gdy użytkownik aktualizuje .

Specyfikacja funkcji
function
ciąg znaków
(wymagane)

Nazwa funkcji aktywowanej przez kolejkę zadań, która obsługuje do zdarzenia.

Ta funkcja musi być zadeklarowana w resources i mają zdefiniowane taskQueue.

processingMessage
ciąg znaków
(wymagane)
Komunikat wyświetlany w konsoli Firebase podczas wykonywania zadania postęp.
onConfigure
(opcjonalnie)

Określa funkcję uruchamianą po ponownej konfiguracji przez użytkownika .

Specyfikacja funkcji
function
ciąg znaków
(wymagane)

Nazwa funkcji aktywowanej przez kolejkę zadań, która obsługuje do zdarzenia.

Ta funkcja musi być zadeklarowana w resources i mają zdefiniowane taskQueue.

processingMessage
ciąg znaków
(wymagane)
Komunikat wyświetlany w konsoli Firebase podczas wykonywania zadania postęp.

Zdarzenia niestandardowe (Eventarc)

Zdarzenia niestandardowe to zdarzenia wysyłane przez rozszerzenie, które umożliwiają użytkownikom wstawianie mają własną logikę w Twoim rozszerzeniu. Zobacz sekcję Eventarc w Dodaj do rozszerzenia punkty zaczepienia użytkowników.

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
ciąg znaków
(wymagane)
Identyfikator typu zdarzenia. Utwórz identyfikator na skali 3–4 pola rozdzielane kropkami: identyfikator wydawcy, nazwa rozszerzenia i nazwa zdarzenia; pola są wymagane; zalecamy użycie pola wersji. Wybierz unikalny identyfikator i opisową nazwę zdarzenia dla każdego opublikowanego typu zdarzenia.
description
ciąg znaków
(wymagane)
Opis zdarzenia.