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łnianych automatycznie są niemodyfikowalne. Są one ustawiane w momencie tworzenia projektu lub instalacji rozszerzenia.

Wskazówka: zarówno Realtime Database, jak i Cloud Storage umożliwiają tworzenie odpowiednio wielu instancji baz danych i pojemników w jednym projekcie Firebase. Dlatego warto skonfigurować parametry konfigurowane przez użytkownika, aby poprosić użytkowników o wskazanie instancji lub zasobnika, którego ma używać rozszerzenie (zamiast zakładać, że użytkownicy chcą, aby rozszerzenie używało domyślnej instancji lub zasobnika projektu).

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	Adres URL domyślnej Realtime Database instancji 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 ogólny: 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 zostanie poproszony 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 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 ograniczonym zakresie przez validationRegex). select: umożliwia wybranie jednego wpisu z 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, użytkownicy otrzymają w interfejsie instalacji bardziej przyjazny interfejs wyboru. Z tego powodu używaj parametrów selectResource, gdy tylko to możliwe. 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 to płatna usługa, której używanie może skutkować opłatami dla użytkowników, którzy zainstalują Twoje rozszerzenie. Jeśli używasz typu parametru secret, w pliku PREINSTALL zanotuj, że Twoje rozszerzenie korzysta z Cloud Secret Manager. Jeśli pominiesz to pole, parametr przyjmie domyślnie 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 Aby zapobiec niezamierzonemu konwertowaniu typów, należy ująć te ciągi znaków w cudzysłowie. Pole value jest wymagane w przypadku pola options. Jeśli pominiesz parametr label, opcja listy zostanie domyślnie wyświetlona jako value. przykładowa składnia options: - label: value: - label: value: - label: value:
resourceType (wymagany, jeśli parametr typema wartość selectResource)	ciąg znaków	Typ zasobu Firebase, który użytkownik ma wybrać. Obecnie selektory zasobów obsługują tylko zbiory Cloud Storage: 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 służący do sprawdzania wartości parametru skonfigurowanej przez użytkownika Wyrażenie regularne jest kompilowane za pomocą biblioteki go: RE2. Szczegółowe informacje o weryfikacji znajdziesz w sekcji Weryfikacja i komunikowanie błędów.
validationErrorMessage (opcjonalnie)	ciąg znaków	Komunikat o błędzie wyświetlany, gdy funkcja validationRegex nie powiedzie się 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 (na przykład jeśli przekonfiguruje rozszerzenie). Jeśli nie podasz wartości immutable, zostanie użyta wartość domyślna false. Uwaga: jeśli zdefiniujesz parametr „location” dla wdrożonych funkcji rozszerzenia, w obiekcie param musisz uwzględnić pole immutable.

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

Gdy konfigurujesz parametr o typie type w typie string, musisz zdefiniować odpowiednią regułę 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. Pamiętaj, że 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, aby po zainstalowaniu przez nich rozszerzenia działało ono prawidłowo.

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 pliku 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 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 rozszerzenia na poziomie instancji użytkownika. 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.function/location	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 mogą być wykonywane 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;