Riferimento per Extensions.yaml

Il file delle specifiche dell'estensione (extension.yaml) contiene i metadati dell'estensione, dichiara le risorse create dall'estensione, le API e l'accesso richiesti dall'estensione e definisce gli eventuali parametri configurati dall'utente forniti dall'estensione.

Le tabelle in questa pagina descrivono i campi disponibili per un file extension.yaml.

Informazioni di base e di identificazione

name: your-extension-name
version: 1.0.0         # Semantic versioning (semver)
specVersion: v1beta    # Always "v1beta"
license: Apache-2.0    # Always "Apache-2.0" (required to publish on extensions.dev)
billingRequired: true  # Always "true"

displayName: Your extension name
description: >-
  Description of the extension. (One or two
  sentences.)
icon: icon.png
tags: [tag, anothertag]

sourceUrl: https://github.com/your-org/your-repo   # GitHub repo URL
releaseNotesUrl: https://github.com/your-org/your-repo/blob/main/CHANGELOG.md

author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/
contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: colleague@example.net
    url: https://github.com/their-org/
Campi di base
name
stringa
(obbligatorio)

Identificatore dell'estensione.

Può contenere solo lettere minuscole, numeri e trattini; può contenere massimo 40 caratteri.

Nota: questo valore viene utilizzato per generare l'ID istanza dell'estensione (che viene poi utilizzato per generare i nomi dell'account di servizio dell'estensione e delle risorse specifiche dell'estensione).

version
stringa
(obbligatorio)

Versione dell'estensione.

Deve seguire il sistema di versionamento semver (ad esempio 1.2.0).
specVersion
stringa
(obbligatorio)

Versione della specifica Firebase Extensions.

Valore corrente: v1beta
license
stringa
(facoltativo)

Licenza per l'estensione.

L'estensione deve essere concessa in licenza utilizzando Apache-2.0.
billingRequired
boolean
(facoltativo)

Indica se i servizi utilizzati dall'estensione richiedono un account di fatturazione Firebase di livello a pagamento.

Deve essere sempre impostato su true.
displayName
stringa
(facoltativo)

Nome visualizzato facile da ricordare per l'estensione (3-5 parole).

Limite di 40 caratteri.
description
stringa
(facoltativo) 		Breve descrizione dell'attività svolta dall'estensione (~1 frase).
icon
stringa
(facoltativo)

File da utilizzare come icona dell'estensione su extensions.dev e la console Firebase.

Questo file deve essere un'immagine PNG quadrata con dimensioni comprese tra 512 x 512 e 1024 x 1024 pixel. Inserisci il file nella stessa directory di extension.yaml. Non puoi specificare una sottodirectory.

Tieni presente le seguenti linee guida quando progetti un'icona per la tua estensione:

  • Seleziona colori di sfondo e artwork adatti al tuo brand.
  • Mantieni semplici i colori delle icone, utilizzando solo due colori. Più colori possono rendere l'icona visivamente troppo complessa.
  • Per lo stesso motivo, non utilizzare gradienti nell'icona. I gradienti sono difficili da distinguere a dimensioni ridotte e rendono l'icona visualmente complessa.
  • Utilizza immagini semplici e uniche che comunichino la funzionalità della tua estensione.
  • Se la tua azienda crea più estensioni, non utilizzare il logo come icona. Gli utenti avranno difficoltà a distinguere le tue estensioni.
  • Crea un'opera d'arte grafica e audace. Non utilizzare artwork delicati o elaborati, che non verranno visualizzati correttamente a dimensioni ridotte.
  • Non includere parole che spiegano cosa fa l'estensione. Il testo è spesso illeggibile a dimensioni ridotte.
tags
elenco di stringhe
(facoltativo) 		Tag per aiutare gli utenti a scoprire la tua estensione. I seguenti tag corrispondono alle categorie in Hub delle estensioni: marketing, messaging, payments, search, shipping, social, utilities, ai
sourceUrl
stringa
(facoltativo) 		URL pubblico a cui è possibile accedere alla directory dell'estensione.
releaseNotesUrl
stringa
(facoltativo) 		URL pubblico a cui è possibile accedere alle note di rilascio dell'estensione.
author
un oggetto author
(facoltativo)

Autore principale e punto di contatto per l'estensione.

author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/
Campi autore
authorName
stringa
(obbligatorio)

Nome dell'autore.

Può essere una persona, un'azienda, un'organizzazione e così via.
email
stringa
(facoltativo) 		Indirizzo email dell'autore.
url
stringa
(facoltativo) 		URL pubblico a cui è possibile accedere per informazioni sull'autore.
contributors
elenco di oggetti autore
(facoltativo)

Eventuali altri autori che hanno contribuito all'estensione.

contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: colleague@example.net
    url: https://github.com/their-org/
Campi autore
authorName
stringa
(obbligatorio)

Nome dell'autore.

Può essere una persona, un'azienda, un'organizzazione e così via.
email
stringa
(facoltativo) 		Indirizzo email dell'autore.
url
stringa
(facoltativo) 		URL pubblico a cui è possibile accedere per informazioni sull'autore.

API Firebase e Google Cloud

Questi campi specificano le API Firebase e Google utilizzate dall'estensione. Quando gli utenti installano l'estensione, possono scegliere di abilitare automaticamente queste API nel progetto.

apis:
  - apiName: apiname.googleapis.com
    reason: Explanation of why the extension uses this API
  - apiName: anotherapiname.googleapis.com
    reason: Explanation of why the extension uses this API
Campi API
apiName
stringa
(obbligatorio)

Nome dell'API Google

Deve corrispondere al campo Nome servizio indicato nella pagina di panoramica di ogni API (esempio) nella libreria API di Google Cloud.

reason
stringa
(obbligatorio) 		Breve descrizione del motivo per cui l'estensione deve utilizzare questa API

Ruoli IAM

Questi campi specificano i ruoli Cloud IAM richiesti dall'estensione. All'account di servizio di cui è stato eseguito il provisioning per l'estensione vengono concessi questi ruoli.

Puoi specificare solo uno dei ruoli supportati.

roles:
  - role: product.role
    reason: Explanation of why the extension needs this level of access
  - role: anotherproduct.role
    resource: projects/${project_id}/resource_type/*
    reason: Explanation of why the extension needs this level of access
Campi del ruolo
role
stringa
(obbligatorio)

Nome del ruolo IAM necessario per il funzionamento dell'estensione

Deve essere uno dei ruoli supportati

reason
stringa
(obbligatorio) 		Breve descrizione del motivo per cui l'estensione ha bisogno dell'accesso concesso da questo ruolo
resource
stringa
(facoltativo)

Limita l'ambito del ruolo a questa risorsa.

Se omesso, il valore predefinito è projects/${project_id}. Consulta Ridurre l'ambito dei ruoli.

Servizi esterni

Questi campi specificano i servizi non Firebase e non Google utilizzati dall'estensione (in genere API REST). La piattaforma Firebase Extensions non fornisce alcun modo per attivare o eseguire automaticamente l'autorizzazione per questi servizi.

externalServices:
  - name: Example API
    pricingUri: https://developers.example.com/pricing
  - name: Another Example API
    pricingUri: https://developers.example.com/pricing
Campi relativi ai servizi esterni
name
stringa
(obbligatorio) 		Nome del servizio esterno necessario per il funzionamento dell'estensione
pricingUri
stringa
(obbligatorio) 		URI alle informazioni sui prezzi del servizio

Parametri configurabili dall'utente

Questi campi definiscono i parametri che l'estensione mette a disposizione degli utenti per la configurazione.

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What do you want to set PARAM_ID to?
      This is a longer description of the parameter, often phrased as a prompt
      to the user.
  - param: ANOTHER_PARAM_ID
    label: Short description of the parameter
    description: >
      What do you want to set ANOTHER_PARAM_ID to?
      This is a longer description of the parameter.
    example: example-input
    validationRegex: "^[a-zA-Z][a-zA-Z-]*[a-zA-Z]?$"
    validationErrorMessage:
      Must be a hyphen-delimited string of alphabetic characters
    default: default-value
    required: false
    immutable: true
Campi dei parametri
param
stringa
(obbligatorio) 		Nome del parametro. Utilizzalo per fare riferimento al valore del parametro nel codice.
label
stringa
(obbligatorio) 		Breve descrizione del parametro. Viene mostrato all'utente quando viene richiesto il valore del parametro.
description
stringa
(facoltativo)

Descrizione dettagliata del parametro. Visualizzato all'utente quando viene richiesto il valore del parametro.

Supporta Markdown.
example
stringa
(facoltativo) 		Valore di esempio per il parametro.
default
stringa
(facoltativo) 		Valore predefinito del parametro se l'utente lascia vuoto il valore.
validationRegex
stringa
(facoltativo) 		Espressione regolare per la convalida del valore configurato dall'utente del parametro. Sintassi di Google RE2.
validationErrorMessage
stringa
(facoltativo) 		Messaggio di errore da visualizzare se la convalida della regex non va a buon fine.
required
boolean
(facoltativo) 		Consente di specificare se l'utente può inviare una stringa vuota quando viene richiesto il valore del parametro. Il valore predefinito è true.
immutable
boolean
(facoltativo)

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

Nota: se definisci un parametro "location" per le funzioni di deployment della tua estensione, imposta questo campo su true.
type
stringa
(facoltativo) 		Il tipo di parametro. I tipi di parametri speciali potrebbero avere requisiti aggiuntivi o una presentazione dell'interfaccia utente diversa. Consulta le sezioni seguenti.

Parametri selezionabili e multiselezionabili

I parametri selezionabili e a selezione multipla consentono agli utenti di scegliere da un elenco di opzioni predefinite.

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      Do you want to enable the option?
    type: select
    options:
      - label: Yes
        value: true
      - label: No
        value: false
  - param: ANOTHER_PARAM_ID
    label: Short description of the parameter
    description: >-
      Which options do you want to enable?
    type: multiselect
    options:
      - value: red
      - value: green
      - value: blue
Campi dei parametri a scelta multipla
type
stringa

select o multiselect

Specifica che il parametro può essere un valore (select) o più valori (multiselect) selezionati da un insieme di scelte predefinite
options
elenco di opzioni
(obbligatorio)

Le opzioni tra cui l'utente può scegliere

Campi opzione
value
una stringa
(obbligatoria) 		Uno dei valori che l'utente può scegliere. Questo è il valore che ottieni quando leggi il valore del parametro nel codice.
label
stringa
(facoltativo) 		Breve descrizione dell'opzione selezionabile. Se omesso, il valore predefinito è value.

Parametri della risorsa selezionabili

I parametri delle risorse selezionabili chiedono agli utenti di selezionare una risorsa (istanza di database, bucket di archiviazione e così via) dal loro progetto.

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      Which resource do you want to use?
    type: selectresource
    resourceType: product.googleapis.com/ResourceType
Campi dei parametri della risorsa
type
stringa

selectresource

Specifica che il parametro rappresenta una risorsa di progetto
resourceType
stringa
(obbligatorio)

Il tipo di risorsa da chiedere all'utente di selezionare.

Valori validi:

  • storage.googleapis.com/Bucket
  • firestore.googleapis.com/Database
  • firebasedatabase.googleapis.com/DatabaseInstance

Tuttavia, al momento solo i bucket Cloud Storage dispongono di un'interfaccia utente di selezione (gli altri tipi di risorse sono presentati come campi di immissione di testo libero).

Parametri secret

I valori delle chiavi forniti dall'utente (ad esempio le chiavi API) vengono gestiti in modo diverso:

  • I valori dei secret vengono archiviati utilizzando Cloud Secret Manager. Solo i client autorizzati (ad esempio un'istanza installata di un'estensione) possono accedere a questi valori.
  • Quando agli utenti viene chiesto di fornire questi valori, il loro input non viene visualizzato.
params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What is the secret value?
    type: secret
Campi dei parametri segreti
type
stringa

secret

Specifica che il parametro è un valore secret

Risorse Cloud Functions

Questi campi dichiarano le funzioni Cloud incluse in un'estensione. La sintassi della dichiarazione delle risorse ha un aspetto leggermente diverso tra le funzioni di 1a e 2a generazione, che possono coesistere in un'estensione.

Cloud Functions di prima generazione

resources:
  - name: functionName
    type: firebaseextensions.v1beta.function
    description: >-
      Description of what the function does. (One or two
      sentences.)
    properties:
      runtime: runtime-version
      eventTrigger:
        eventType: google.product.event
        resource: projects/_/resource/specifier
Campi delle risorse
name
stringa
(obbligatorio)

Nome intuitivo per la funzione esportata.

Se non specifichi la proprietà entryPoint (vedi di seguito), questo valore deve corrispondere al nome della funzione nel codice sorgente delle funzioni.

Il nome finale della funzione implementata sarà nel seguente formato: ext-extension-instance-id-name.
type
stringa
(obbligatorio) 		Per una risorsa funzione di 1ª gen.: firebaseextensions.v1beta.function
description
stringa
(obbligatorio)

Breve descrizione dell'attività svolta dalla funzione per l'estensione.
properties
(obbligatorio)

Proprietà Cloud Functions di 1ª gen. Le proprietà più importanti sono elencate di seguito, ma puoi trovare l'elenco completo nella documentazione di riferimento di Cloud Functions.

Proprietà
location
(facoltativo)

Posizione in cui eseguire il deployment della funzione. Il valore predefinito è us-central1
entryPoint
(facoltativo) 		Nome della funzione esportata all'interno del codice sorgente delle funzioni che l'estensione deve cercare. Il valore predefinito è name, sopra.
sourceDirectory
(facoltativo)

Directory che contiene package.json nella sua radice. Il file del codice sorgente delle funzioni deve trovarsi in questa directory. Il valore predefinito è functions

Nota: il campo main di package.json specifica il file per il codice sorgente delle funzioni (ad esempio index.js).
timeout
(facoltativo)

Il tempo massimo di esecuzione della funzione.

  • Valore predefinito: 60s
  • Valore massimo: 540s
availableMemoryMb
(facoltativo)

Quantità di memoria in MB disponibile per la funzione.

  • Valore predefinito: 256
  • Valori validi: 128, 256, 512, 1024 e 2048
runtime
(consigliato)

Ambiente di runtime per la funzione.
httpsTrigger
o
eventTrigger
o
scheduleTrigger
o
taskQueueTrigger
(è obbligatorio uno di questi tipi di attivatori di funzioni) 		Per informazioni specifiche su ciascun tipo di trigger, consulta Scrivere Cloud Functions per un'estensione.

Cloud Functions di seconda generazione

resources:
  - name: functionName
    type: firebaseextensions.v1beta.v2function
    description: >-
      Description of what the function does. (One or two
      sentences.)
    properties:
      buildConfig:
        runtime: nodejs16
      serviceConfig:
        availableMemory: 512M
      eventTrigger:
        eventType: google.firebase.firebasealerts.alerts.v1.published
        triggerRegion: global
        eventFilters:
          - attribute: alerttype
            value: crashlytics.newFatalIssue
Campi delle risorse
name
stringa
(obbligatorio)

Nome intuitivo per la funzione esportata.

Se non specifichi la proprietà entryPoint (vedi di seguito), questo valore deve corrispondere al nome della funzione nel codice sorgente delle funzioni.

Il nome finale della funzione implementata sarà nel seguente formato: ext-extension-instance-id-name.
type
stringa
(obbligatorio) 		Per una risorsa funzione di 2ª generazione: firebaseextensions.v1beta.v2function
description
stringa
(obbligatorio)

Breve descrizione dell'attività svolta dalla funzione per l'estensione.
properties
(obbligatorio)

Proprietà Cloud Functions di 2ª generazione. Le proprietà più importanti sono elencate di seguito, ma puoi trovare l'elenco completo nel documento di riferimento di Cloud Functions.

Proprietà
location
(facoltativo)

Posizione in cui eseguire il deployment della funzione. Il valore predefinito è us-central1
sourceDirectory
(facoltativo)

Directory che contiene package.json nella sua radice. Il file del codice sorgente delle funzioni deve trovarsi in questa directory. Il valore predefinito è functions

Nota: il campo main di package.json specifica il file per il codice sorgente delle funzioni (ad esempio index.js).

Esistono anche tre campi di tipo di oggetto con le proprie proprietà:

Proprietà buildConfig
buildConfig.runtime
(consigliato)

Ambiente di runtime per la funzione.
buildConfig.entryPoint
(facoltativo) 		Nome della funzione esportata all'interno del codice sorgente delle funzioni che l'estensione deve cercare. Il valore predefinito è name, sopra.
Proprietà serviceConfig
serviceConfig.timeoutSeconds
(facoltativo)

Il tempo massimo di esecuzione della funzione.

  • Valore predefinito: 60
  • Valore massimo: 540
serviceConfig.availableMemory
(facoltativo) 		La quantità di memoria disponibile per una funzione. Il valore predefinito è 256M. Le unità supportate sono k, M, G, Mi, Gi. Se non viene fornita alcuna unità, il valore viene interpretato come byte.
Proprietà eventTrigger
eventTrigger.eventType
(obbligatorio) 		Il tipo di evento da ascoltare. Consulta Scrivere un'estensione di Cloud Functions per i tipi di eventi disponibili per ciascun prodotto.
eventTrigger.eventFilters
(facoltativo) 		Filtri che limitano ulteriormente gli eventi da ascoltare. Ad esempio, potresti ascoltare solo gli eventi corrispondenti a un determinato schema della risorsa. Per informazioni su come filtrare ogni tipo di evento, consulta Scrivere funzioni Cloud per un'estensione.
eventTrigger.channel
(facoltativo) 		Il nome del canale associato all'attivatore in formato projects/{project}/locations/{location}/channels/{channel}. Se ometti questa proprietà, la funzione ascolterà gli eventi sul canale predefinito del progetto.
eventTrigger.triggerRegion
(facoltativo) 		L'attivatore riceverà solo gli eventi provenienti da questa regione. Può essere la stessa regione della funzione, un'altra regione o più regioni oppure la regione globale. Se non viene fornito, viene utilizzato per impostazione predefinita la stessa regione della funzione.

Eventi del ciclo di vita

Gli eventi del ciclo di vita ti consentono di specificare le funzioni da eseguire quando un utente installa, aggiorna o configura un'istanza della tua estensione. Consulta Gestire gli eventi del ciclo di vita dell'estensione.

lifecycleEvents:
  onInstall:
    function: myTaskFunction
    processingMessage: Describes the task being completed
  onUpdate:
    function: myOtherTaskFunction
    processingMessage: Describes the task being completed
  onConfigure:
    function: myOtherTaskFunction
    processingMessage: Describes the task being completed
Campi evento del ciclo di vita
onInstall
(facoltativo)

Specifica una funzione che viene eseguita quando un utente installa l'estensione.

Specifiche della funzione
function
una stringa
(obbligatoria)

Nome della funzione attivata dalla coda dell'attività che gestirà l'evento.

Questa funzione deve essere dichiarata nella sezione resources e avere taskQueue definito.
processingMessage
una stringa
(obbligatoria) 		Messaggio da visualizzare nella console Firebase mentre l'attività è in corso.
onUpdate
(facoltativo)

Specifica una funzione che viene eseguita quando un utente aggiorna l'estensione.

Specifiche della funzione
function
una stringa
(obbligatoria)

Nome della funzione attivata dalla coda dell'attività che gestirà l'evento.

Questa funzione deve essere dichiarata nella sezione resources e avere taskQueue definito.
processingMessage
una stringa
(obbligatoria) 		Messaggio da visualizzare nella Console Firebase mentre l'attività è in corso.
onConfigure
(facoltativo)

Specifica una funzione che viene eseguita quando un utente riconfigura l'estensione.

Specifiche della funzione
function
una stringa
(obbligatoria)

Nome della funzione attivata dalla coda dell'attività che gestirà l'evento.

Questa funzione deve essere dichiarata nella sezione resources e avere taskQueue definito.
processingMessage
una stringa
(obbligatoria) 		Messaggio da visualizzare nella Console Firebase mentre l'attività è in corso.

Eventi personalizzati (Eventarc)

Gli eventi personalizzati sono eventi emessi dall'estensione per consentire agli utenti di inserire la propria logica nell'estensione. Consulta la sezione Eventarc in Aggiungere hook utente a un'estensione.

events:
  - type: publisher-id.extension-name.version.event-name
    description: Description of the event
  - type: publisher-id.extension-name.version.another-event-name
    description: Description of the other event
Campi evento personalizzati
type
stringa
(obbligatorio) 		L'identificatore del tipo dell'evento. Costruisci l'identificatore da 3-4 campi separati da punti: i campi ID publisher, nome dell'estensione e nome dell'evento sono obbligatori; il campo della versione è consigliato. Scegli un nome unico e descrittivo per ogni tipo di evento che pubblichi.
description
stringa
(obbligatorio) 		Descrizione dell'evento.