Impostare e utilizzare i parametri nell'estensione

I parametri sono il meccanismo tramite il quale un utente personalizza ogni istanza installata di un'estensione. I parametri sono come le 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 da l'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 denominato PARAMETER_NAME:

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

  • In extension.yaml e POSTINSTALL.md, utilizza ${param:PARAMETER_NAME}.

    Dopo l'installazione, la Firebase console visualizza i contenuti del POSTINSTALL.md file e compila tutti i 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 (vedi 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 dei parametri compilati automaticamente sono immutabili. Vengono impostati al momento della creazione del progetto o dell'installazione dell'estensione.

Anche se Firebase compila automaticamente questi valori dei parametri 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 attivare i prodotti associati e applicabili nel proprio progetto prima dell'installazione. Ad esempio, se l'estensione coinvolge Cloud Firestore, l'utente deve configurare Cloud Firestore nel proprio 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 predefinita Realtime Database 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 è uguale 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 name campo specificato nel extension.yaml file.

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 (assegnata automaticamente da Firebase; può essere modificata 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, configura i prompt nella sezione params del file extension.yaml.

Di seguito è riportata 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
(required) 		stringa Nome del parametro
label
(required) 		stringa

Breve descrizione del parametro

Visualizzata all'utente quando viene richiesto il valore del parametro

description
(optional) 		stringa

Descrizione dettagliata del parametro

Visualizzata all'utente quando viene richiesto il valore del parametro

Supporta Markdown

type
(optional) 		stringa

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

I valori validi includono:

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

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

  • 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 secret tipo di parametro, assicurati di documentare nel file PREINSTALL che l'estensione utilizza Cloud Secret Manager.

Se questo campo viene omesso, il parametro assume per impostazione predefinita type di string.

options
(required if parameter type is select or multiSelect) 		list

Elenco di valori da cui l'utente può selezionare

Includi i campi label e value nel campo options:

  • label (stringa): breve descrizione dell'opzione selezionabile

Il campo value è obbligatorio per il campo options field.
Se label viene omesso, l'opzione dell'elenco visualizza per impostazione predefinita value.
resourceType
(required if parameter type is selectResource) 		stringa

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

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

I valori resourceType sconosciuti verranno ignorati e l'interfaccia utente eseguirà il rendering del parametro come campo di input string in formato libero.
example
(optional) 		stringa

Valore di esempio per il parametro
validationRegex
(optional)
(only applicable when the parameter type is string) 		stringa

Stringa di espressione regolare per la convalida del valore configurato dall'utente del parametro

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

Per i dettagli sulla convalida, consulta la sezione Convalida e messaggi di errore di seguito.

validationErrorMessage
(optional) 		stringa

Messaggio di errore da visualizzare se il validationRegex non riesce

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

default
(optional) 		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 default valore (per un esempio, consulta il IMG_BUCKET parametro dell' estensione Ridimensiona immagini).

required
(optional) 		booleano

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

Se required viene omesso, questo valore assume per impostazione predefinita true (ovvero un parametro obbligatorio).

immutable
(optional) 		booleano

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

Se immutable viene omesso, questo valore assume per impostazione predefinita false.

Nota: se definisci un parametro "location" per le funzioni di cui è stato eseguito il deployment dell'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 il type di string, devi definire una convalida dell'espressione regolare appropriata tramite il campo validationRegex del parametro.

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

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

Tuttavia, quando l'estensione esegue il deployment delle risorse, la Firebase console o l'interfaccia a riga di comando Firebase visualizzerà un messaggio di errore se il database o il bucket Cloud Storage a cui si fa 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 destinati a controllare la configurazione delle risorse, non sono accessibili come variabili di ambiente dal codice della funzione.

In genere non devi 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 risorsa in extension.yaml. Queste impostazioni di configurazione per risorsa sostituiranno le impostazioni a livello di 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 (facile da usare) 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 quanti secondi devono essere eseguite le funzioni prima del timeout?
firebaseextensions.v1beta.function/vpcConnectorEgressSettings Traffico in uscita dal 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 della funzione minInstances Il numero minimo di istanze di questa funzione da eseguire contemporaneamente
firebaseextensions.v1beta.function/maxInstances Numero massimo di istanze della 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 dell'estensione