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ą podobne do zmiennych środowiskowych w przypadku rozszerzenia. Wartości parametrów mogą być wypełniane automatycznie (dostarczane przez Firebase po instalacji) lub konfigurowane przez użytkownika (określane przez użytkownika podczas instalacji).

Możesz się do nich odwoływać w kodzie źródłowym funkcji rozszerzenia, w pliku extension.yaml i w pliku POSTINSTALL.md. Oto składnia odwołania 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 przypadku języków extension.yaml i POSTINSTALL.md użyj ${param:PARAMETER_NAME}.

    Po instalacji w konsoli Firebase wyświetlana jest zawartość pliku POSTINSTALL.md, a odwołania do parametrów są wypełniane rzeczywistymi wartościami zainstalowanej instancji.

Parametry wypełniane automatycznie

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

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

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

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

Format ogólny:
project-id

Przykładowa wartość:
project-123

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

Uogólniony format:
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

Domyślna nazwa instancji Realtime Database 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 Domyślna nazwa zasobnika Cloud Storage projektu 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żna go modyfikować 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 konfigurowane przez użytkownika

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

Oto przykładowa params sekcja, 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) 		ciąg znaków Nazwa parametru
label
(wymagane) 		ciąg znaków

Krótki opis parametru

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

description
(opcjonalnie) 		ciąg znaków

Szczegółowy opis parametru

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

Obsługa Markdown

type
(opcjonalnie) 		ciąg znaków

Mechanizm wprowadzania wartości parametru przez użytkownika (np. wpisywanie tekstu bezpośrednio lub wybieranie z listy)

Prawidłowe wartości:

  • string: umożliwia wpisywanie tekstu w dowolnej formie (w zakresie limitu określonego przez validationRegex)
  • select: umożliwia wybranie jednego wpisu z wcześniej zdefiniowanej listy opcji. Jeśli określisz tę wartość, musisz też zdefiniować pole options.
  • multiSelect: umożliwia wybór co najmniej 1 pozycji z wcześniej zdefiniowanej listy opcji. Jeśli określisz tę wartość, musisz też zdefiniować pole options.
  • selectResource: umożliwia wybór określonego typu zasobu Firebase (np. Cloud Storage) w projekcie użytkownika.

    Jeśli określisz parametr tego typu, użytkownicy zobaczą w interfejsie instalacji bardziej przyjazny dla użytkownika widżet wyboru. Z tego powodu w miarę możliwości używaj parametrów selectResource.

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

  • secret: umożliwia przechowywanie ciągów znaków zawierających dane wrażliwe, np. kluczy interfejsu API do 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 wiązać się z opłatami dla użytkowników instalujących Twoje rozszerzenie. Jeśli używasz typu parametru secret, w pliku PREINSTALL udokumentuj, że rozszerzenie korzysta z usługi Cloud Secret Manager.

Jeśli pominiesz to pole, domyślna wartość parametru to type of string.

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

Lista wartości, z których użytkownik może wybrać jedną

Uwzględnij pola label i value w polu options:

  • label (string): 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 symbol label zostanie pominięty, domyślnie opcja listy będzie wyświetlana jako value.
resourceType
(wymagany, jeśli parametr type ma wartość selectResource) 		ciąg znaków

Typ zasobu Firebase, który ma być wyświetlany użytkownikowi do wyboru. Obecnie selektory zasobów obsługują tylko te zasobniki Cloud Storage:

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

Nieznane wartości resourceType będą ignorowane, a interfejs użytkownika będzie renderować parametr jako pole wprowadzania string w formie swobodnej.
example
(opcjonalnie) 		ciąg znaków

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

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

Więcej informacji o weryfikacji znajdziesz w sekcji Weryfikacja i komunikaty o błędach poniżej.

validationErrorMessage
(opcjonalnie) 		ciąg znaków

Komunikat o błędzie, który ma się wyświetlać, jeśli funkcja validationRegex się nie powiedzie.

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

default
(opcjonalnie) 		ciąg znaków

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

W odpowiednich przypadkach 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 zostanie poproszony o podanie wartości parametru.

Jeśli pominiesz wartość required, domyślną wartością będzie true (czyli 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 parametr immutable zostanie pominięty, domyślna wartość to false.

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

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

Gdy skonfigurujesz 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 żądaną wartością parametru jest ścieżka do bazy danych lub zasobnik Cloud Storage. Pamiętaj, że podczas instalacji, ponownej konfiguracji lub aktualizacji usługa Extensions nie weryfikuje tych elementów w momencie wprowadzania wartości parametru:

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

Gdy jednak rozszerzenie faktycznie wdraża swoje zasoby, w Firebase konsoli lub Firebase interfejsie CLI wyświetla się komunikat o błędzie, jeśli w projekcie nie skonfigurowano jeszcze bazy danych lub Cloud Storage zasobnika, do których odwołuje się rozszerzenie.

Zdecydowanie zalecamy powiadomienie użytkowników w PREINSTALLpliku o tych wymaganiach, aby po zainstalowaniu rozszerzenia działało ono prawidłowo.

Parametry systemowe

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

Zwykle nie musisz deklarować niczego 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 extension.yaml. Te ustawienia konfiguracji poszczególnych zasobów zastąpią ustawienia rozszerzenia użytkownika w całej 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 systemowe:

Nazwa Etykieta (czytelna dla ludzi) 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 Ile sekund powinny działać funkcje, 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ć uruchomione jednocześnie
firebaseextensions.v1beta.function/maxInstances Maksymalna liczba instancji funkcji maxInstances Maksymalna liczba instancji tej funkcji, które mają być uruchamiane 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.