Riferimento per Extensions.yaml

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

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

Informazioni di base e identificative

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. 40 caratteri limite.

Nota: questo valore viene utilizzato per generare il valore-chiave l'ID istanza (che viene quindi utilizzato per generare i nomi l'account di servizio dell'estensione e le risorse specifiche dell'estensione).

version
stringa
(obbligatorio)

Versione dell'estensione.

Deve seguire il controllo delle versioni di semver (ad esempio, 1.2.0).
specVersion
stringa
(obbligatorio)

Versione della specifica Firebase Extensions.

Valore attuale: v1beta
license
stringa
(facoltativo)

Licenza per l'estensione.

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

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

Imposta sempre su true.
displayName
stringa
(facoltativo)

Nome visualizzato semplice per l'estensione (3-5 parole).

Puoi utilizzare 40 caratteri al massimo.
description
stringa
(facoltativo) 		Breve descrizione dell'attività eseguita dall'estensione (~1 frase).
icon
stringa
(facoltativo)

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

Questo file deve essere in formato PNG quadrato, 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 il tuo estensione:

  • Seleziona i colori di sfondo e dell'artwork adatti al tuo brand.
  • Utilizza colori semplici per le icone, utilizzando solo due colori. Più colori può rendere la tua icona visivamente abbondante.
  • Per lo stesso motivo, non utilizzare sfumature nell'icona. Gradienti sono difficili da distinguere con le dimensioni ridotte e dall'aspetto visivo complessi.
  • Utilizza immagini semplici e uniche che comunichino il tipo di estensione della tua estensione. funzionalità.
  • Se la tua azienda crea più estensioni, non utilizzare il tuo logo come l'icona. Gli utenti avranno difficoltà a distinguere i tuoi estensioni.
  • Crea un'opera d'arte grafica e audace. Non usare contenuti delicati o elaborati che non viene visualizzata correttamente con dimensioni ridotte.
  • Non includere parole che spieghino la funzione dell'estensione. Il testo è spesso illeggibili con dimensioni più piccole.
tags
elenco di stringhe
(facoltativo) 		Tag per aiutare gli utenti a scoprire la tua estensione. I seguenti tag sono mappati alle categorie nell'hub delle estensioni: marketing, messaging, payments, search, shipping, social, utilities, ai
sourceUrl
stringa
(facoltativo) 		URL pubblico da 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 ecc.
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 ecc.
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 attivare automaticamente queste API nel loro 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 di Google

Deve corrispondere al campo Nome servizio come indicato su ogni Pagina Panoramica dell'API (esempio) nel Libreria API 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. Il servizio all'account di cui è stato eseguito il provisioning per l'estensione sono concessi questi ruoli.

Puoi specificare un solo elemento 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 dei ruoli
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 richiede l'accesso da parte di questo ruolo
resource
stringa
(facoltativo)

Limita l'ambito del ruolo a questa risorsa.

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

Servizi esterni

Questi campi specificano i servizi non Firebase e non Google utilizzati dall'estensione (in genere le API REST). La piattaforma Firebase Extensions non fornisce mezzo per abilitare 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 delle informazioni sui prezzi del servizio

Parametri configurabili dall'utente

Questi campi definiscono i parametri messi a disposizione degli utenti dall'estensione 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. Utilizza questo nome per fare riferimento al valore del parametro nel codice.
label
stringa
(obbligatorio) 		Descrizione breve del parametro. Mostrato all'utente quando viene richiesto il valore del parametro.
description
stringa
(facoltativo)

Descrizione dettagliata del parametro. Viene mostrato 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 per il parametro se l'utente lascia vuoto il valore del parametro.
validationRegex
stringa
(facoltativo) 		Espressione regolare per la convalida del valore configurato dall'utente del parametro. RE2 di Google a riga di comando.
validationErrorMessage
stringa
(facoltativo) 		Messaggio di errore da visualizzare se la convalida della regex non va a buon fine.
required
booleano
(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 (ad esempio se l'estensione viene riconfigurata). Il valore predefinito è false.

Nota: se definisci una "località" per l'attributo di cui è stato eseguito il deployment funzioni dell'estensione, imposta questo campo su true.
type
stringa
(facoltativo) 		Il tipo di parametro. I tipi di parametri speciali possono avere o una diversa presentazione dell'interfaccia utente. Consulta le sezioni seguenti.

Parametri selezionabili e multiselezionabili

I parametri selezionabili e multiselezionabili richiedono agli utenti di scegliere da un elenco di 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 solo 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
stringa
(obbligatorio) 		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, i valori predefiniti a value.

Parametri delle risorse selezionabili

I parametri delle risorse selezionabili richiedono agli utenti di selezionare una risorsa (database istanza, 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 per richiedere 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 hanno una UI di selezione (altri tipi di risorse sono presentati come campi di immissione di testo in formato libero).

Parametri secret

I valori dei secret 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 clienti 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 secret
type
stringa

secret

Specifica che il parametro è un valore secret

Risorse della funzione Cloud Functions

Questi campi dichiarano le funzioni Cloud Functions incluse in un'estensione. La risorsa la sintassi della dichiarazione è un po' diversa tra 1a gen. e 2a gen. 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 semplice 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 deployed sarà nella seguente formato: ext-extension-instance-id-name
type
stringa
(obbligatorio) 		Per una risorsa di funzione di 1a generazione: firebaseextensions.v1beta.function
description
stringa
(obbligatorio)

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

Proprietà Cloud Functions di prima 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)

Località 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 il tuo package.json principale. Il file del codice sorgente delle funzioni deve trovarsi in questo . Il valore predefinito è functions

Nota: il campo main di package.json specifica il file del codice sorgente delle funzioni (come 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
(uno di questi tipi di trigger di funzione è obbligatorio) 		Vedi Scrittura Cloud Functions per un'estensione per informazioni specifiche su ciascun tipo di trigger.

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 semplice 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 deployed sarà nella seguente formato: ext-extension-instance-id-name
type
stringa
(obbligatorio) 		Per una risorsa di funzione di 2a generazione: firebaseextensions.v1beta.v2function
description
stringa
(obbligatorio)

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

Proprietà Cloud Functions di seconda generazione. Le proprietà più importanti sono elencate di seguito, ma puoi trovare l'elenco completo nei Cloud Riferimento per le funzioni.

Proprietà
location
(facoltativo)

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

Directory che contiene il tuo package.json principale. Il file del codice sorgente delle funzioni deve trovarsi in questo . Il valore predefinito è functions

Nota: il campo main di package.json specifica il file del codice sorgente di funzioni (come index.js).

Esistono anche tre campi di tipo 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 dovrebbe 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à di misura, il valore viene interpretato come byte.
Proprietà eventTrigger
eventTrigger.eventType
(obbligatorio) 		Il tipo di evento da ascoltare. Consulta Scrittura Cloud Funzioni per un'estensione per i tipi di evento disponibili per ogni 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 projects/{project}/locations/{location}/channels/{channel} formato. Se ometti questa proprietà, la funzione rimane in ascolto eventi sul canale predefinito del progetto.
eventTrigger.triggerRegion
(facoltativo) 		Il trigger riceverà solo eventi che hanno origine in questa regione. Può essere la stessa regione della funzione, una regione diversa o o la regione globale. Se non viene specificato, il valore predefinito è la stessa regione della funzione.

Eventi del ciclo di vita

Gli eventi del ciclo di vita ti consentono di specificare le funzioni che verranno eseguite quando un utente o configurare un'istanza dell'estensione. Consulta Gestire gli eventi del ciclo di vita delle estensioni.

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 degli eventi del ciclo di vita
onInstall
(facoltativo)

Specifica una funzione che viene eseguita quando un utente installa .

Specifica della funzione
function
una stringa
(obbligatoria)

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

Questa funzione deve essere dichiarata nel resources e in cui hai definito taskQueue.
processingMessage
stringa
(obbligatorio) 		Messaggio da visualizzare nella console Firebase mentre l'attività è in progressi.
onUpdate
(facoltativo)

Specifica una funzione che viene eseguita quando un utente aggiorna la .

Specifica della funzione
function
una stringa
(obbligatoria)

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

Questa funzione deve essere dichiarata nel resources e in cui hai definito taskQueue.
processingMessage
stringa
(obbligatorio) 		Messaggio da visualizzare nella console Firebase mentre l'attività è in progressi.
onConfigure
(facoltativo)

Specifica una funzione che viene eseguita quando un utente riconfigura la .

Specifica della funzione
function
una stringa
(obbligatoria)

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

Questa funzione deve essere dichiarata nel resources e in cui hai definito taskQueue.
processingMessage
stringa
(obbligatorio) 		Messaggio da visualizzare nella Console Firebase mentre l'attività è in corso.

Eventi personalizzati (Eventarc)

Gli eventi personalizzati sono eventi generati 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. Crea l'identificatore da 3 a 4 Campi delimitati da punti: ID publisher, nome dell'estensione e nome dell'evento i campi sono obbligatori; il campo della versione è consigliato. Scegli un'istanza e un nome descrittivo per ogni tipo di evento che pubblichi.
description
stringa
(obbligatorio) 		Descrizione dell'evento.