Impostare e utilizzare i parametri nell'estensione

I parametri sono il meccanismo mediante il quale un utente personalizza ogni dispositivo installato di un'estensione. I parametri sono come le variabili di ambiente per . I valori dei parametri possono essere compilato automaticamente (fornito da Firebase dopo installazione) o configurata dall'utente (specificata da l'utente durante l'installazione).

Puoi fare riferimento a questi parametri nella codice sorgente delle funzioni, il file extension.yaml e POSTINSTALL.md . Questa è 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, usa ${param:PARAMETER_NAME}.

    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 (fai riferimento alla tabella di seguito). Questi valori parametro sono i valori predefiniti per l'account 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. Sono impostati al momento per la creazione di progetti o l'installazione di estensioni.

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 le funzionalità associate e i prodotti applicabili nel loro progetto prima dell'installazione. Ad esempio, se l'estensione riguarda Cloud Firestore, l'utente deve configurare Cloud Firestore nel proprio progetto. Ti consigliamo di informare gli utenti di questi requisiti nel il PREINSTALL.md un file YAML.

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

Formato generalizzato:
project-id

Valore di esempio:
project-123

DATABASE_URL URL dell'istanza Realtime Database predefinito 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 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

Di solito, questo valore corrisponde all'ID progetto o termina con -default-rtdb.

Formato generalizzato:
project-id

Valore di esempio:
project-123

STORAGE_BUCKET Nome del bucket Cloud Storage predefinito del progetto Firebase

Formato generalizzato:
project-id.appspot.com

Valore di esempio:
project-123.appspot.com

Parametro con valore predefinito dell'installazione dell'estensione
EXT_INSTANCE_ID

Identificatore univoco per l'istanza dell'estensione installata

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

Formato generalizzato per la prima istanza installata (assegnato automaticamente da Firebase; non possono essere modificate 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 Chiedi all'utente di specificare i valori dei parametri durante l'installazione. Per richiedere questi devi configurare i prompt nella sezione params di 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

Descrizione breve del parametro

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

description
(facoltativo) 		stringa

Descrizione dettagliata del parametro

Visualizzato all'utente quando gli viene chiesto il parametro valore

Supporta Markdown

type
(facoltativo) 		stringa

Meccanismo di input per il modo in cui l'utente imposta il valore del parametro (ad ad esempio, inserisci il testo direttamente o selezionane una 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 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 definiscono anche options .
  • selectResource: consente di selezionare uno specifico tipo di risorsa Firebase (come un bucket Cloud Storage) dal progetto dell'utente.

    Se specifichi un parametro di questo tipo, gli utenti riceveranno un widget di selezione semplice da usare nell'interfaccia utente di installazione; per questo motivo, usa i parametri selectResource ogni volta che possibile.

    Se specifichi questo valore, devi definire anche resourceType .

  • secret: consente l'archiviazione di stringhe sensibili come 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 un addebito per gli utenti che installano l'estensione. Se utilizzi il tipo di parametro secret, assicurati di documentare la tua PREINSTALLAZIONE che la tua estensione utilizza Cloud Secret Manager.

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

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

Elenco di valori da cui l'utente può selezionare

Includi i campi label e value nel Campo options:

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

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

Il tipo di risorsa Firebase da richiedere all'utente di selezionare. Al momento, solo Cloud Storage bucket 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 visualizza il parametro come campo di immissione 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

Le espressioni regolari vengono compilate utilizzando la libreria go: RE2

Per maggiori dettagli sulla convalida, consulta Convalida ed errore messaggi di seguito.

validationErrorMessage
(facoltativo) 		stringa

Messaggio di errore da visualizzare se validationRegex non supera

Per maggiori dettagli sui messaggi di errore, consulta Convalida ed errore messaggi di seguito.

default
(facoltativo) 		stringa

Valore predefinito del parametro se l'utente esce dalla relativa impostazione valore vuoto

Se applicabile, puoi specificare Valore del parametro compilato automaticamente per il valore default (ad esempio, fai riferimento al IMG_BUCKET del parametro estensione Ridimensiona immagini).

required
(facoltativo) 		booleano

Definisce se l'utente può inviare una stringa vuota quando visualizza 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 dell'installazione (ad esempio, riconfigura l'estensione)

Se immutable viene omesso, questo valore predefinito è false.

Nota: se definisci una "località" per le funzioni dell'estensione di cui è stato eseguito il deployment, devi includere questo campo immutable nel parametro .

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

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

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
  • 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 mostreranno un messaggio di errore se il database a cui viene fatto riferimento o il bucket Cloud Storage non è ancora stato configurato nel progetto.

Ti consigliamo vivamente di informare gli utenti nel File PREINSTALL a questi requisiti in modo che, quando installano l'estensione, viene installato correttamente e funziona come previsto.

Parametri di sistema

I parametri di sistema controllano la configurazione di base delle risorse di un'estensione. Poiché hanno lo scopo di 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 l'estensione ha requisiti speciali per le risorse, puoi impostare valori specifici a livello di risorsa in extension.yaml. Queste impostazioni di configurazione per risorsa sostituiranno l'estensione dell'utente a livello di istanza. 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 funzioni memory Quanti megabyte di memoria devono essere assegnati a ogni funzione?
firebaseextensions.v1beta.function/timeoutSeconds Timeout funzione timeout Quanti secondi devono essere eseguite le funzioni prima del timeout?
firebaseextensions.v1beta.function/vpcConnectorEgressSettings In uscita dal connettore VPC vpcConnectorEgressSettings Controlla il traffico in uscita quando viene 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 da eseguire contemporaneamente di questa funzione
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 di 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