Impostare e utilizzare i parametri nell'estensione

I parametri sono il meccanismo attraverso il quale un utente personalizza ogni istanza installata di un'estensione. I parametri sono simili alle variabili di ambiente per un'estensione. I valori dei parametri possono essere compilati automaticamente (forniti da Firebase dopo l'installazione) o configurati dall'utente (specificati dall'utente durante l'installazione).

Puoi fare riferimento a questi parametri nel codice sorgente delle funzioni dell'estensione, nel file extension.yaml e nel file POSTINSTALL.md. Ecco la sintassi per fare riferimento a un parametro chiamato PARAMETER_NAME:

  • Nel codice sorgente delle funzioni, utilizza il modulo params (ad esempio, params.defineInt("PARAMETER_NAME")) o process.env.PARAMETER_NAME.

  • Utilizza ${param:PARAMETER_NAME} tra extension.yaml e POSTINSTALL.md.

    Dopo l'installazione, la console Firebase mostra i contenuti del POSTINSTALL.md file e completa eventuali riferimenti ai parametri con i valori effettivi dell'istanza installata.

Parametri compilati automaticamente

Ogni istanza installata di un'estensione ha automaticamente accesso a diversi parametri predefiniti compilati automaticamente forniti da Firebase (consulta la tabella di seguito). Questi valori del parametro sono i valori predefiniti per il progetto Firebase (ad esempio il bucket di archiviazione predefinito) o sono specifici dell'estensione (ad esempio l'ID istanza dell'estensione).

Tutti i valori dei parametri compilati automaticamente sono immutabili. Vengono impostate al momento della creazione del progetto o dell'installazione dell'estensione.

Anche se Firebase compila automaticamente questi valori di parametro per l'estensione, non esegue il provisioning automatico dei prodotti associati per l'utente durante l'installazione. L'utente che installa l'estensione deve attivare i prodotti associati e applicabili nel progetto prima dell'installazione. Ad esempio, se la tua estensione prevede Cloud Firestore, l'utente deve configurare Cloud Firestore nel suo progetto. Ti consigliamo di informare gli utenti di questi requisiti nel PREINSTALL.md file.

Riferimento per il parametro compilato automaticamente Descrizione Valore del parametro (fornito da Firebase)
Parametri con valori predefiniti del progetto Firebase
PROJECT_ID Identificatore univoco del progetto Firebase in cui è installata l'estensione

Formato generale:
project-id

Valore di esempio:
project-123

DATABASE_URL L'URL dell'istanza Realtime Database predefinita del progetto Firebase

Formato generale:
https://project-id-default-rtdb.firebaseio.com
(istanze negli Stati Uniti)
oppure
https://project-id-default-rtdb.region-code.firebasedatabase.app
(istanze al di fuori degli Stati Uniti)

Valore di esempio:
https://project-123-default-rtdb.firebaseio.com

DATABASE_INSTANCE

Il nome dell'istanza Realtime Database predefinita del progetto Firebase

In genere, questo valore corrisponde all'ID progetto o termina con -default-rtdb.

Formato generale:
project-id

Valore di esempio:
project-123

STORAGE_BUCKET Il nome del bucket Cloud Storage predefinito del progetto Firebase

Formato generale:
PROJECT_ID.firebasestorage.app

Valore di esempio:
project-123.firebasestorage.app

Parametro con valore predefinito dall'installazione dell'estensione
EXT_INSTANCE_ID

Identificatore univoco dell'istanza dell'estensione installata

Questo valore viene generato dal name campo specificato nel file extension.yaml.

Formato generale per la prima istanza installata (assegnato automaticamente da Firebase; non può essere modificato dall'utente durante l'installazione):
name-from-extension.yaml

Valore di esempio:
my-awesome-extension


Formato generalizzato per la seconda istanza installata e le successive (assegnato automaticamente da Firebase; può essere modificato dall'utente durante l'installazione):
name-from-extension.yaml-4-digit-alphanumeric-hash

Valore di esempio:
my-awesome-extension-6m31

Parametri configurati dall'utente

Per consentire a un utente di personalizzare ogni istanza installata di un'estensione, puoi chiedere all'utente di specificare i valori dei parametri durante l'installazione. Per richiedere questi valori, imposta i prompt nella sezione params del file extension.yaml.

Ecco un esempio di sezione params, seguita da una tabella che descrive tutti i campi del parametro disponibili.

# 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

Nella sezione params del file extension.yaml, utilizza i seguenti campi per definire un parametro configurato dall'utente:

Campo Tipo Descrizione
param
(obbligatorio) 		stringa Nome del parametro
label
(obbligatorio) 		stringa

Breve descrizione del parametro

Viene mostrato all'utente quando gli viene chiesto il valore del parametro

description
(facoltativo) 		stringa

Descrizione dettagliata del parametro

Viene mostrato all'utente quando gli viene chiesto il valore del parametro

Supporta Markdown

type
(facoltativo) 		stringa

Meccanismo di immissione per la modalità di impostazione del valore del parametro da parte dell'utente (ad es. inserire il testo direttamente o selezionare un valore dall'elenco a discesa)

I valori validi includono:

  • string: consente di inserire testo libero (secondo le limitazioni impostate dal tuo validationRegex)
  • select: consente di selezionare una voce da un elenco di opzioni predefinite. Se specifichi questo valore, devi anche definire il campo options.
  • multiSelect: consente di selezionare una o più voci da un elenco di opzioni predefinite. Se specifichi questo valore, devi anche definire il campo options.
  • selectResource: consente di selezionare un tipo specifico di risorsa Firebase (ad esempio un bucket Cloud Storage) dal progetto dell'utente.

    Quando specifichi un parametro di questo tipo, gli utenti visualizzeranno un widget di selezione più intuitivo nell'interfaccia utente dell'installazione. Per questo motivo, utilizza i parametri selectResource se possibile.

    Se specifichi questo valore, devi anche definire il campo resourceType.

  • secret: consente di archiviare stringhe sensibili, ad esempio chiavi API per servizi di terze parti. Questi valori verranno archiviati in Cloud Secret Manager.

    Cloud Secret Manager è un servizio a pagamento, il cui utilizzo potrebbe comportare addebiti per gli utenti che installano la tua estensione. Se utilizzi il tipo di parametro secret, assicurati di documentare nel file PREINSTALL che l'estensione utilizza Cloud Secret Manager.

Se questo campo viene omesso, il valore predefinito del parametro è type di string.

options
(obbligatorio se il parametro type è select o multiSelect) 		list

Elenco di valori tra cui l'utente può effettuare una selezione

Includi i campi label e value nel campo options:

  • label (stringa): descrizione breve dell'opzione selezionata
  • value (stringa): valore effettivo dell'opzione selezionata.

Il campo value è obbligatorio per il campo options.
Se label viene omesso, l'opzione dell'elenco predefinita è value.
resourceType
(obbligatorio se il parametro type è selectResource) 		stringa

Il tipo di risorsa Firebase da chiedere all'utente di selezionare. Al momento, solo i bucket Cloud Storage supportano i selettori di risorse:

Tipo di risorsa ID tipo
Cloud Storage bucket storage.googleapis.com/Bucket

I valori resourceType sconosciuti verranno ignorati e l'interfaccia utente representerà il parametro come un campo di input string di tipo libero.
example
(facoltativo) 		stringa

Valore di esempio per il parametro
validationRegex
(facoltativo)
(applicabile solo quando il parametro type è string) 		stringa

Stringa regex per la convalida del valore configurato dall'utente del parametro

L'espressione regolare viene compilata utilizzando la libreria Go: RE2

Per informazioni dettagliate sulla convalida, consulta Convalida e messaggi di errore di seguito.

validationErrorMessage
(facoltativo) 		stringa

Messaggio di errore da visualizzare se la verifica validationRegex non va a buon fine

Per informazioni dettagliate sui messaggi di errore, consulta Convalida e messaggi di errore di seguito.

default
(facoltativo) 		stringa

Valore predefinito per il parametro se l'utente lascia vuoto il valore del parametro

Se applicabile, puoi specificare un valore di parametro compilato automaticamente per il valore default (ad esempio, consulta il parametro IMG_BUCKET dell'estensione Modifica le dimensioni delle immagini).

required
(facoltativo) 		booleano

Consente di specificare se l'utente può inviare una stringa vuota quando viene richiesto il valore del parametro

Se required viene omesso, il valore predefinito è true (ovvero un parametro obbligatorio).

immutable
(facoltativo) 		booleano

Definisce se l'utente può modificare il valore del parametro dopo l'installazione (ad esempio se riconfigura l'estensione)

Se immutable viene omesso, il valore predefinito è false.

Nota: se definisci un parametro "location" per le funzioni di cui è stato eseguito il deployment della tua estensione, devi includere questo campo immutable nell'oggetto param.

Convalida e messaggi di errore per i valori configurati dall'utente

Quando configuri un parametro con il valore type di string, devi definire la convalida regex appropriata tramite il campo validationRegex del parametro.

Inoltre, per molte estensioni, un valore del parametro comunemente richiesto è un percorso del database o un bucket Cloud Storage. Tieni presente che durante l'installazione, la riconfigurazione o l'aggiornamento, il servizio Extensions non convalida quanto segue al momento della digitazione del valore del parametro:

  • Se il database o il bucket Cloud Storage specificato è configurato nel progetto Firebase dell'utente
  • Indica se il percorso del database specificato esiste nel database dell'utente

Tuttavia, quando l'estensione esegue effettivamente il deployment delle risorse, la console Firebase o l'interfaccia a riga di comando Firebase mostrerà un messaggio di errore se il database o il bucket Firebase a cui si fa riferimento non è ancora configurato nel progetto.Cloud Storage

Ti consigliamo vivamente di informare gli utenti nel file PREINSTALL di questi requisiti in modo che, quando installano la tua estensione, essa si installi correttamente e funzioni come previsto.

Parametri di sistema

I parametri di sistema controllano la configurazione di base delle risorse di un'estensione. Poiché sono progettate per controllare la configurazione delle risorse, non sono accessibili come variabili di ambiente dal codice della funzione.

In genere, non è necessario dichiarare nulla per questi parametri in extension.yaml. Vengono definiti automaticamente per ogni istanza dell'estensione e gli utenti hanno la possibilità di impostare valori personalizzati quando installano l'estensione.

Tuttavia, se la tua estensione ha requisiti di risorse speciali, puoi impostare valori specifici a livello di risorsa in extension.yaml. Queste impostazioni di configurazione per risorsa sostituiscono le impostazioni dell'utente per l'intera istanza dell'estensione. Ad esempio:

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

I parametri di sistema disponibili sono:

Nome Etichetta (adatta agli utenti) Campo corrispondente in properties Descrizione
firebaseextensions.v1beta.function/location Località location In quale regione deve essere eseguito il deployment di Cloud Functions?
firebaseextensions.v1beta.function/memory Memoria della funzione memory Quanti megabyte di memoria devono essere allocati a ogni funzione?
firebaseextensions.v1beta.function/timeoutSeconds Timeout funzione timeout Per quanto tempo devono essere eseguite le funzioni prima del timeout?
firebaseextensions.v1beta.function/vpcConnectorEgressSettings Uscita del connettore VPC vpcConnectorEgressSettings Controlla il traffico in uscita quando è configurato un connettore VPC
firebaseextensions.v1beta.function/vpcConnector Connettore VPC vpcConnector Collega Cloud Functions al connettore VPC specificato.
firebaseextensions.v1beta.function/minInstances Numero minimo di istanze di funzione minInstances Il numero minimo di istanze di questa funzione da eseguire contemporaneamente
firebaseextensions.v1beta.function/maxInstances Numero massimo istanze di funzione maxInstances Il numero massimo di istanze di questa funzione da eseguire contemporaneamente
firebaseextensions.v1beta.function/ingressSettings Impostazioni Ingress ingressSettings Controlla da dove viene accettato il traffico in entrata
firebaseextensions.v1beta.function/labels Etichette labels Etichette da applicare a tutte le risorse nell'estensione