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 come le variabili di ambiente di 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).

Questi parametri sono disponibili per il riferimento 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.

  • All'interno di extension.yaml e POSTINSTALL.md, utilizza ${param:PARAMETER_NAME}.

    Dopo l'installazione, la console Firebase mostra i contenuti del file POSTINSTALL.md e compila tutti i riferimenti ai parametri con i valori effettivi per l'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 dei parametri sono i valori predefiniti per il progetto Firebase (come il bucket Storage predefinito) o sono specifici dell'estensione (come l'ID istanza dell'estensione).

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

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

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

Formato generalizzato:
project-id

Valore di esempio:
project-123

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

Formato generalizzato:
https://project-id-default-rtdb.firebaseio.com
(istanze negli Stati Uniti)
o
https://project-id-default-rtdb.region-code.firebasedatabase.app
(istanze non negli 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 generalizzato:
project-id

Valore di esempio:
project-123

STORAGE_BUCKET Il nome del bucket Cloud Storage predefinito del progetto Firebase

Formato generalizzato:
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 campo name specificato nel file extension.yaml.

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

Valore di esempio:
my-awesome-extension


Formato generalizzato per la seconda istanza installata e 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 chiedergli di specificare i valori parametro durante l'installazione. Per richiedere questi valori, configura i prompt nella sezione params del file extension.yaml.

Ecco una sezione params di esempio, seguita da una tabella che descrive tutti i campi dei parametri 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 richiesto il valore del parametro

description
(facoltativo) 		stringa

Descrizione dettagliata del parametro

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

Supporta Markdown

type
(facoltativo) 		stringa

Meccanismo di immissione per l'impostazione del valore del parametro da parte dell'utente (ad esempio, inserimento diretto del testo o selezione da un elenco a discesa)

I valori validi includono:

  • string: consente l'inserimento di testo in formato libero (come limitato dal tuo validationRegex)
  • select: consente di selezionare una voce da un elenco predefinito di opzioni. Se specifichi questo valore, devi anche definire il campo options.
  • multiSelect: consente di selezionare una o più voci da un elenco predefinito di opzioni. 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ù facile da usare nell'interfaccia utente di installazione. Per questo motivo, utilizza i parametri selectResource quando possibile.

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

  • secret: consente l'archiviazione di stringhe sensibili, come le chiavi API per i 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 l'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 parametro viene impostato per impostazione predefinita su type di string.

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

Elenco di valori tra cui l'utente può scegliere

Includi i campi label e value all'interno del campo options:

  • label (string): breve descrizione dell'opzione selezionabile
  • value (string): valore effettivo dell'opzione selezionabile

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

Il tipo di risorsa Firebase che l'utente deve 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 la UI visualizzerà il parametro come campo di immissione string in formato 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 la sezione Convalida e messaggi di errore di seguito.

validationErrorMessage
(facoltativo) 		stringa

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

Per maggiori dettagli sui messaggi di errore, consulta la sezione Convalida e messaggi di errore di seguito.

default
(facoltativo) 		stringa

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

Se applicabile, puoi specificare un valore del parametro compilato automaticamente per il valore default (per un esempio, consulta il parametro IMG_BUCKET dell'estensione Resize Images).

required
(facoltativo) 		booleano

Definisce se l'utente può inviare una stringa vuota quando gli 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 nel relativo oggetto param.

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

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

Inoltre, per molte estensioni, un valore 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 dell'inserimento del valore parametro:

  • Se il database o il bucket Cloud Storage specificato è configurato all'interno del progetto Firebase dell'utente
  • Se il percorso del database specificato esiste all'interno del database dell'utente

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

Ti consigliamo vivamente di informare gli utenti di questi requisiti nel file PREINSTALL, in modo che, quando installano l'estensione, l'installazione vada a buon fine e l'estensione funzioni come previsto.

Parametri di sistema

I parametri di sistema controllano la configurazione di base delle risorse di un'estensione. Poiché sono destinate a controllare la configurazione delle risorse, non sono accessibili come variabili di ambiente dall'interno del 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 l'estensione ha requisiti di risorse speciali, puoi impostare valori specifici a livello di singola risorsa in extension.yaml. Queste impostazioni di configurazione per risorsa sostituiranno le impostazioni dell'istanza dell'estensione dell'utente. 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 (comprensibile) 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 per ogni funzione?
firebaseextensions.v1beta.function/timeoutSeconds Timeout funzione timeout Per quanti secondi devono essere eseguite le funzioni prima del timeout?
firebaseextensions.v1beta.function/vpcConnectorEgressSettings Traffico in uscita connettore VPC vpcConnectorEgressSettings Controlla il traffico in uscita quando è configurato un connettore VPC
firebaseextensions.v1beta.function/vpcConnector Connettore VPC vpcConnector Connette 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 traffico in entrata 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