Konfigurowanie i używanie parametrów w rozszerzeniu

Parametry to mechanizm, za pomocą którego użytkownik dostosowuje każdą zainstalowaną instancję rozszerzenia. Parametry są jak zmienne środowiskowe rozszerzenia. Wartości parametrów mogą być wypełniane automatycznie (podawane przez Firebase po instalacji) lub konfigurowane przez użytkownika (określane przez użytkownika podczas instalacji).

Możesz odwoływać się do tych parametrów w kodzie źródłowym funkcji rozszerzenia, pliku extension.yaml i pliku POSTINSTALL.md. Oto składnia, której należy użyć, aby odwołać się do parametru o nazwie PARAMETER_NAME:

  • W kodzie źródłowym funkcji użyj modułu params (np. params.defineInt("PARAMETER_NAME")) lub process.env.PARAMETER_NAME.

  • W polach extension.yaml i POSTINSTALL.md użyj ${param:PARAMETER_NAME}.

    Po instalacji konsola Firebase wyświetla zawartość pliku POSTINSTALL.md i wypełnia wszystkie odwołania do parametrów rzeczywistymi wartościami zainstalowanej instancji.

Parametry wypełniane automatycznie

Każda zainstalowana instancja rozszerzenia ma automatycznie dostęp do kilku domyślnych, automatycznie wypełnianych parametrów dostarczanych przez Firebase (patrz tabela poniżej). Te wartości parametrów są wartościami domyślnymi dla projektu Firebase (np. domyślny zasobnik Storage) lub są specyficzne dla rozszerzenia (np. identyfikator instancji rozszerzenia).

Wszystkie automatycznie wypełniane wartości parametrów są niezmienne. Są one ustawiane podczas tworzenia projektu lub instalowania rozszerzenia.

Mimo że Firebase automatycznie wypełnia te wartości parametrów dla rozszerzenia, Firebase nie udostępnia automatycznie powiązanych usług użytkownikowi podczas instalacji. Użytkownik instalujący rozszerzenie musi przed instalacją włączyć w swoim projekcie powiązane i odpowiednie usługi. Jeśli na przykład rozszerzenie obejmuje Cloud Firestore, użytkownik musi skonfigurować Cloud Firestore w swoim projekcie. Zalecamy poinformowanie użytkowników o tych wymaganiach w pliku PREINSTALL.md.

Dokumentacja dotycząca automatycznie wypełnianych parametrów Opis Wartość parametru (podana przez Firebase)
Parametry z wartościami domyślnymi z projektu w Firebase
PROJECT_ID Unikalny identyfikator projektu w Firebase, w którym zainstalowano rozszerzenie.

Format ogólny:
project-id

Przykładowa wartość:
project-123

DATABASE_URL Domyślny adres URL instancji Realtime Database projektu w Firebase.

Format ogólny:
https://project-id-default-rtdb.firebaseio.com
(instancje w USA)
lub
https://project-id-default-rtdb.region-code.firebasedatabase.app
(instancje poza USA)

Przykładowa wartość:
https://project-123-default-rtdb.firebaseio.com

DATABASE_INSTANCE

Nazwa domyślnej instancji Realtime Database w projekcie Firebase

Zwykle ta wartość jest taka sama jak identyfikator projektu lub kończy się ciągiem znaków -default-rtdb.

Format ogólny:
project-id

Przykładowa wartość:
project-123

STORAGE_BUCKET Nazwa domyślnego zasobnika Cloud Storage projektu w Firebase.

Format ogólny:
PROJECT_ID.firebasestorage.app

Przykładowa wartość:
project-123.firebasestorage.app

Parametr z wartością domyślną z instalacji rozszerzenia
EXT_INSTANCE_ID

Unikalny identyfikator zainstalowanej instancji rozszerzenia.

Ta wartość jest generowana na podstawie pola name określonego w pliku extension.yaml.

Uogólniony format pierwszej zainstalowanej instancji (przypisywany automatycznie przez Firebase; nie może być modyfikowany przez użytkownika podczas instalacji):
name-from-extension.yaml

Przykładowa wartość:
my-awesome-extension


Uogólniony format dla drugiej i kolejnych zainstalowanych instancji (przypisywany automatycznie przez Firebase; może być modyfikowany przez użytkownika podczas instalacji):
name-from-extension.yaml-4-digit-alphanumeric-hash

Przykładowa wartość:
my-awesome-extension-6m31

Parametry skonfigurowane przez użytkownika

Aby umożliwić użytkownikowi dostosowanie każdej zainstalowanej instancji rozszerzenia, możesz poprosić go o określenie wartości parametrów podczas instalacji. Aby poprosić o te wartości, skonfiguruj prompty w sekcji params pliku extension.yaml.

Oto przykładowa sekcja params, a pod nią tabela z opisem wszystkich dostępnych pól parametrów.

# 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

W sekcji params pliku extension.yaml użyj tych pól, aby zdefiniować parametr skonfigurowany przez użytkownika:

Pole Typ Opis
param
(wymagane)
tekst Nazwa parametru
label
(wymagane)
tekst

Krótki opis parametru

Wyświetlana użytkownikowi, gdy pojawi się prośba o podanie wartości parametru.

description
(opcjonalnie)
tekst

Szczegółowy opis parametru

Wyświetlana użytkownikowi, gdy pojawi się prośba o podanie wartości parametru.

Obsługiwany jest język Markdown.

type
(opcjonalnie)
tekst

mechanizm wprowadzania, który określa, jak użytkownik ustawia wartość parametru (np. wpisuje tekst bezpośrednio lub wybiera go z listy);

Prawidłowe wartości:

  • string: umożliwia wpisywanie dowolnego tekstu (zgodnie z ograniczeniami validationRegex).
  • select: umożliwia wybranie jednego wpisu ze wstępnie zdefiniowanej listy opcji. Jeśli podasz tę wartość, musisz też zdefiniować pole options.
  • multiSelect: umożliwia wybór co najmniej 1 pozycji z wstępnie zdefiniowanej listy opcji. Jeśli podasz tę wartość, musisz też zdefiniować pole options.
  • selectResource: umożliwia wybór określonego typu zasobu Firebase (np. zasobnika Cloud Storage) z projektu użytkownika.

    Gdy określisz parametr tego typu, użytkownicy zobaczą w interfejsie instalacji bardziej przyjazny dla użytkownika widżet wyboru. Z tego powodu, gdy tylko jest to możliwe, używaj parametrów selectResource.

    Jeśli podasz tę wartość, musisz też zdefiniować pole resourceType.

  • secret: umożliwia przechowywanie ciągów znaków zawierających dane wrażliwe, takich jak klucze interfejsu API do usług innych firm. Te wartości będą przechowywane w usłudze Cloud Secret Manager.

    Cloud Secret Manager to usługa płatna, której używanie może wiązać się z opłatami dla użytkowników, którzy zainstalują Twoje rozszerzenie. Jeśli używasz typu parametru secret, pamiętaj, aby w pliku PREINSTALL udokumentować, że rozszerzenie korzysta z Cloud Secret Managera.

Jeśli pominiesz to pole, parametr będzie miał domyślną wartość type z string.

options
(wymagany, jeśli parametr type ma wartość select lub multiSelect)
list

Lista wartości, z których użytkownik może wybierać

Uwzględnij pola label i value w polu options:

  • label (ciąg znaków): krótki opis opcji do wyboru
  • value (ciąg znaków): rzeczywista wartość opcji do wyboru.

Pole value jest wymagane w przypadku pola options.
Jeśli pominiesz parametr label, opcja listy będzie domyślnie wyświetlać value.

resourceType
(wymagany, jeśli parametr type ma wartość selectResource)
tekst

Typ zasobu Firebase, o którego wybranie zostanie poproszony użytkownik. Obecnie tylko zasobniki Cloud Storage obsługują selektory zasobów:

Typ zasobu Identyfikator typu
Cloud Storage zasobnik storage.googleapis.com/Bucket

Nieznane wartości resourceType będą ignorowane, a interfejs będzie renderować parametr jako pole do wprowadzania danych string w formacie swobodnym.

example
(opcjonalnie)
tekst

Przykładowa wartość parametru

validationRegex
(opcjonalny)
(ma zastosowanie tylko wtedy, gdy parametr type ma wartość string)
tekst

Ciąg wyrażenia regularnego do weryfikacji wartości parametru skonfigurowanej przez użytkownika

Wyrażenie regularne jest kompilowane przy użyciu biblioteki go: RE2

Szczegółowe informacje o weryfikacji znajdziesz poniżej w sekcji Weryfikacja i komunikaty o błędach.

validationErrorMessage
(opcjonalnie)
tekst

Komunikat o błędzie wyświetlany, gdy nie uda się wykonać działania validationRegex

Szczegółowe informacje o komunikatach o błędach znajdziesz poniżej w sekcji Komunikaty o błędach i weryfikacji.

default
(opcjonalnie)
tekst

Wartość domyślna parametru, jeśli użytkownik pozostawi wartość parametru pustą

W razie potrzeby możesz określić wartość parametru wypełnianego automatycznie dla wartości default (przykład znajdziesz w parametrze IMG_BUCKET rozszerzenia Resize Images).

required
(opcjonalnie)
wartość logiczna

Określa, czy użytkownik może przesłać pusty ciąg znaków, gdy pojawi się prośba o podanie wartości parametru.

Jeśli pominiesz parametr required, jego wartość domyślna będzie wynosić true (czyli będzie to parametr wymagany).

immutable
(opcjonalnie)
wartość logiczna

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

Jeśli pominiesz parametr immutable, domyślnie zostanie użyta wartość false.

Uwaga: jeśli zdefiniujesz parametr "location" dla wdrożonych funkcji rozszerzenia, musisz uwzględnić pole immutable w obiekcie param.

Weryfikacja i komunikaty o błędach dotyczące wartości skonfigurowanych przez użytkownika

Gdy konfigurujesz parametr z wartością type równą string, musisz zdefiniować odpowiednią weryfikację wyrażenia regularnego w polu validationRegex parametru.

W przypadku wielu rozszerzeń często wymagana jest wartość parametru, która jest ścieżką bazy danych lub zasobnikiem Cloud Storage. Pamiętaj, że podczas instalacji, ponownej konfiguracji lub aktualizacji usługa Extensions nie sprawdza tych elementów w momencie wprowadzania wartości parametru:

  • czy określona baza danych lub zasobnik Cloud Storage są skonfigurowane w projekcie w Firebase użytkownika;
  • Czy określona ścieżka bazy danych istnieje w bazie danych użytkownika

Jeśli jednak rozszerzenie faktycznie wdraża swoje zasoby, konsola Firebase lub interfejs wiersza poleceń Firebase wyświetli komunikat o błędzie, jeśli przywoływana baza danych lub zasobnik Cloud Storage nie zostały jeszcze skonfigurowane w projekcie.

Zdecydowanie zalecamy powiadomienie użytkowników o tych wymaganiach w pliku PREINSTALL, aby po zainstalowaniu rozszerzenia działało ono zgodnie z oczekiwaniami.

Parametry systemu

Parametry systemowe kontrolują podstawową konfigurację zasobów rozszerzenia. Służą one do kontrolowania konfiguracji zasobów, więc nie są dostępne jako zmienne środowiskowe w kodzie funkcji.

Zwykle nie musisz niczego deklarować w przypadku tych parametrów w extension.yaml. Są one automatycznie definiowane dla każdej instancji rozszerzenia, a użytkownicy mogą ustawiać wartości niestandardowe podczas instalowania rozszerzenia.

Jeśli jednak rozszerzenie ma specjalne wymagania dotyczące zasobów, możesz ustawić konkretne wartości na poziomie poszczególnych zasobów w pliku extension.yaml. Te ustawienia konfiguracji poszczególnych zasobów zastąpią ustawienia rozszerzenia użytkownika w całej instancji. Na przykład:

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

Dostępne parametry systemowe:

Nazwa Etykieta (czytelna dla człowieka) Odpowiednie pole w: properties Opis
firebaseextensions.v1beta.function/location Lokalizacja location W którym regionie należy wdrożyć Cloud Functions?
firebaseextensions.v1beta.function/memory Pamięć funkcji memory Ile megabajtów pamięci należy przydzielić każdej funkcji?
firebaseextensions.v1beta.function/timeoutSeconds Limit czasu funkcji timeout Przez ile sekund funkcje powinny działać, zanim upłynie limit czasu?
firebaseextensions.v1beta.function/vpcConnectorEgressSettings Ruch wychodzący przez oprogramowanie sprzęgające VPC vpcConnectorEgressSettings Kontroluje ruch wychodzący, gdy skonfigurowane jest oprogramowanie sprzęgające VPC
firebaseextensions.v1beta.function/vpcConnector Oprogramowanie sprzęgające VPC vpcConnector Łączy Cloud Functions z określonym oprogramowaniem sprzęgającym VPC.
firebaseextensions.v1beta.function/minInstances Minimalna liczba instancji funkcji minInstances Minimalna liczba instancji tej funkcji, które mają być uruchamiane jednocześnie
firebaseextensions.v1beta.function/maxInstances Maksymalna liczba instancji funkcji maxInstances Maksymalna liczba instancji tej funkcji, które mogą być uruchomione jednocześnie
firebaseextensions.v1beta.function/ingressSettings Ustawienia ruchu przychodzącego ingressSettings Określa, skąd jest akceptowany ruch przychodzący
firebaseextensions.v1beta.function/labels Etykiety labels Etykiety do zastosowania do wszystkich zasobów w rozszerzeniu