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ć automatycznie wypełniane (udostępniane przez Firebase po instalacji) lub konfigurowane przez użytkownika (określane przez użytkownika podczas instalacji).

Parametry te są dostępne do użycia w kodzie źródłowym funkcji rozszerzenia, pliku extension.yaml i pliku POSTINSTALL.md. Oto składnia odwoływania się do parametru o nazwie PARAMETER_NAME:

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

  • W przypadku wartości extension.yaml i POSTINSTALL.md należy użyć wartości ${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 dla zainstalowanej instancji.

Parametry wypełniane automatycznie

Każde zainstalowane wystąpienie rozszerzenia ma automatyczny dostęp do kilku domyślnych parametrów wypełnianych automatycznie przez Firebase (patrz tabela poniżej). Wartości tych parametrów to albo wartości domyślne projektu Firebase (np. domyślny kontener Storage), albo wartości specyficzne dla rozszerzenia (np. identyfikator instancji rozszerzenia).

Wszystkie wartości parametrów wypełniane automatycznie są niemodyfikowalne. Są one ustawiane w momencie tworzenia projektu lub instalacji rozszerzenia.

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

Informacje o parametrze wypełnianym automatycznie Opis Wartość parametru (podana przez Firebase)
Parametry o wartościach domyślnych z projektu Firebase
PROJECT_ID Unikalny identyfikator projektu Firebase, w którym jest zainstalowane rozszerzenie

Format ogólny:
project-id

Przykładowa wartość:
project-123

DATABASE_URL Domyślny adres URL instancji Realtime Database projektu Firebase

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

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

DATABASE_INSTANCE

Nazwa domyślnej Realtime Database instancji projektu Firebase

Zwykle ta wartość jest taka sama jak identyfikator projektu lub kończy się na -default-rtdb.

Format uogólniony:
project-id

Przykładowa wartość:
project-123

STORAGE_BUCKET Nazwa domyślnego zasobnika Cloud Storage projektu Firebase.

Format ogólny:
project-id.appspot.com

Przykładowa wartość:
project-123.appspot.com

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.

Ogólny format dla 1 zainstalowanej instancji (przypisana automatycznie przez Firebase; nie może zostać zmodyfikowana przez użytkownika podczas instalacji):
name-from-extension.yaml

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


Ogólny format dla 2 i późniejszych instancji zainstalowanych w ramach tej samej aplikacji (przypisany automatycznie przez Firebase; może zostać zmodyfikowany 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żdego zainstalowanego wystąpienia rozszerzenia, możesz poprosić go o podanie wartości parametrów podczas instalacji. Aby poprosić o te wartości, skonfiguruj prompty w sekcji params w pliku extension.yaml.

Oto przykład sekcji params, a następnie tabela ze wszystkimi dostępnymi polami 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) 		ciąg znaków Nazwa parametru
label
(wymagane) 		ciąg znaków

Krótki opis parametru

Wyświetlany użytkownikowi, gdy jest proszony o podanie wartości parametru.

description
(opcjonalnie) 		ciąg znaków

Szczegółowy opis parametru

Wyświetlany użytkownikowi, gdy zostanie poproszony o podanie wartości parametru.

Obsługuje format Markdown

type
(opcjonalnie) 		ciąg znaków

Sposób, w jaki użytkownik ustawia wartość parametru (np. wpisywanie tekstu bezpośrednio lub wybieranie z listy)

Prawidłowe wartości:

  • string: umożliwia wpisywanie dowolnego tekstu (w ramach ograniczeń określonych przez Ciebie w validationRegex).
  • select: umożliwia wybór 1 wpisu ze wstępnie zdefiniowanej listy opcji. Jeśli podasz tę wartość, musisz też zdefiniować pole options.
  • multiSelect: umożliwia wybranie co najmniej 1 elementu z listy wstępnie zdefiniowanych opcji. Jeśli podasz tę wartość, musisz też zdefiniować pole options.
  • selectResource: umożliwia wybranie konkretnego typu zasobu Firebase (np. zasobów Cloud Storage) z projektu użytkownika.

    Jeśli określisz parametr tego typu, w interfejsie instalacji użytkownicy zobaczą łatwiejszy w użyciu widżet wyboru. Z tego względu w miarę możliwości używaj parametrów selectResource.

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

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

    Cloud Secret Manager jest usługą płatną, dlatego korzystanie z niej może wiązać się z naliczeniem opłat przez użytkowników, którzy zainstalują Twoje rozszerzenie. Jeśli używasz typu parametru secret, pamiętaj, aby w pliku PREINSTALL udokumentować, że Twoje rozszerzenie korzysta z usługi Cloud Secret Manager.

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

options
(wymagany, jeśli parametr type to select lub multiSelect) 		list

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

W polu options uwzględnij pola label i value:

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

Pole value jest wymagane w przypadku pola options.
Jeśli pominiesz parametr label, opcja listy zostanie domyślnie wyświetlona jako value.
resourceType
(wymagany, jeśli parametr typema wartość selectResource) 		ciąg znaków

Typ zasobu Firebase, w którym użytkownik ma zobaczyć prośbę o wybranie. 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 zostaną zignorowane, a interfejs użytkownika wyświetli parametr jako pole wejściowe string.
example
(opcjonalnie) 		ciąg znaków

Przykładowa wartość parametru
validationRegex
(opcjonalnie)
(dotyczy tylko wtedy, gdy parametr type ma wartośćstring) 		ciąg znaków

Ciąg znaków wyrażenia regularnego do sprawdzania wartości skonfigurowanej przez użytkownika

Wyrażenie regularne jest kompilowane za pomocą biblioteki go: RE2.

Szczegółowe informacje o weryfikacji znajdziesz w sekcji Weryfikacja i przekazywanie komunikatów o błędach.

validationErrorMessage
(opcjonalnie) 		ciąg znaków

Komunikat o błędzie wyświetlany w przypadku niepowodzenia zadania validationRegex

Szczegółowe informacje o komunikatach o błędach znajdziesz w sekcji Weryfikacja i komunikaty o błędach.

default
(opcjonalnie) 		ciąg znaków

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

W razie potrzeby możesz podać wartość parametru wypełnianego automatycznie dla wartości default (np. parametr IMG_BUCKET w rozszerzeniu Resize Images).

required
(opcjonalnie) 		wartość logiczna

Określa, czy użytkownik może przesłać pusty ciąg znaków, gdy zostanie wyświetlony monit o podanie wartości parametru.

Jeśli pominiesz parametr required, jego wartość zostanie domyślnie ustawiona na true (czyli na wartość wymaganą).

immutable
(opcjonalnie) 		wartość logiczna

Określa, czy użytkownik może zmienić wartość parametru po instalacji (jeśli na przykład ponownie skonfigurujerozszerzenie)

Jeśli pominiesz właściwość immutable, domyślna wartość to false.

Uwaga: jeśli określisz parametr „location” dla wdrożonych funkcji rozszerzenia, umieść to pole immutable w jego obiekcie param.

Weryfikacja i komunikaty o błędach w przypadku wartości konfigurowanych przez użytkownika

Po skonfigurowaniu parametru z funkcją type o wartości string musisz zdefiniować odpowiednią weryfikację wyrażenia regularnego w polu validationRegex parametru.

Ponadto w przypadku wielu rozszerzeń często żądaną wartością parametru jest ścieżka bazy danych lub Cloud Storage. Podczas instalacji, zmiany konfiguracji lub aktualizacji usługa Extensions nie weryfikuje tych informacji w momencie wprowadzania wartości parametru:

  • Czy podana baza danych lub zasobnik Cloud Storage jest skonfigurowana w projekcie Firebase użytkownika
  • Określa, czy podana ścieżka do bazy danych istnieje w bazie danych użytkownika

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

Zdecydowanie zalecamy poinformowanie użytkowników w pliku PREINSTALL o tych wymaganiach. Dzięki temu po zainstalowaniu rozszerzenia pomyślnie zainstaluje się ono i działa zgodnie z oczekiwaniami.

Parametry systemu

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

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

Jeśli jednak Twoje rozszerzenie ma specjalne wymagania dotyczące zasobów, możesz ustawić określone wartości na poziomie zasobu w pliku extension.yaml. Te ustawienia konfiguracji zasobów zastąpią ustawienia użytkownika dotyczące rozszerzenia na poziomie instancji. 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 systemu:

Nazwa Etykieta (czytelna dla ludzi) Odpowiednie pole w properties Opis
firebaseextensions.v1beta.funkcja/lokalizacja Lokalizacja location W którym regionie należy wdrożyć funkcję Cloud Functions?
firebaseextensions.v1beta.function/memory Pamięć funkcji memory Ile megabajtów pamięci powinno być przydzielone do każdej funkcji?
firebaseextensions.v1beta.function/timeoutSeconds Limit czasu funkcji timeout Ile sekund powinny trwać funkcje przed przekroczeniem limitu czasu?
firebaseextensions.v1beta.function/vpcConnectorEgressSettings Oprogramowanie sprzęgające VPC – kierowanie ruchu wychodzącego vpcConnectorEgressSettings Kontroluje ruch wychodzący, gdy skonfigurowane jest oprogramowanie sprzęgające VPC
firebaseextensions.v1beta.function/vpcConnector Oprogramowanie sprzęgające VPC vpcConnector Łączy funkcje 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ć wykonywane jednocześnie
firebaseextensions.v1beta.function/maxInstances Maksymalna liczba instancji funkcji maxInstances Maksymalna liczba instancji tej funkcji, które można uruchomić 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, które mają być stosowane do wszystkich zasobów w rozszerzeniu;