Watch demos on how to build & run AI-powered apps with Firebase at Demo Day '24. Watch now.

Questa pagina è stata tradotta dall'API Cloud Translation.

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.appspot.com` Valore di esempio: `project-123.appspot.com`
Parametro con valore predefinito dall'installazione dell'estensione
`EXT_INSTANCE_ID`	Identificatore univoco per l'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 chiedergli 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 sono:

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 l'archiviazione di 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 parametro predefinito è 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
Assicurati di racchiudere queste stringhe tra virgolette per evitare conversioni di tipo involontarie.

Il campo value è obbligatorio per il campo options.
Se label viene omesso, l'opzione di elenco predefinita è value.

sintassi di esempio

options:
  - label:
    value:
  - label:
    value:
  - label:
    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 dell'estensione