Documentation de référence pour extension.yaml

Le fichier de spécification de votre extension (extension.yaml) contient les métadonnées de votre extension, déclare les ressources créées par l'extension, les API et l'accès requis par l'extension, et définit tous les paramètres configurés par l'utilisateur fournis par l'extension.

Les tableaux de cette page décrivent les champs disponibles pour un fichier extension.yaml.

Informations de base et d'identification

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/
Champs de base
name
string
(obligatoire)

Identifiant de l'extension.

Il ne peut contenir que des lettres minuscules, des chiffres et des tirets (40 caractères maximum).

Remarque : Cette valeur est utilisée pour générer l'ID d'instance de l'extension (qui est ensuite utilisé pour générer les noms du compte de service de l'extension et des ressources spécifiques à l'extension).

version
string
(obligatoire)

Version de l'extension.

Doit respecter la version sémantique (par exemple, 1.2.0).
specVersion
string
(obligatoire)

Version de la spécification des extensions Firebase.

Valeur actuelle : v1beta
license
chaîne
(facultatif)

Licence de l'extension.

Votre extension doit être concédée sous licence à l'aide de Apache-2.0.
billingRequired
boolean
(facultatif)

Indique si les services utilisés par l'extension nécessitent un compte de facturation Firebase de niveau payant.

Toujours défini sur true.
displayName
chaîne
(facultatif)

Nom à afficher convivial pour l'extension (3 à 5 mots).

40 caractères maximum.
description
chaîne
(facultatif) 		Brève description de la tâche effectuée par votre extension (environ une phrase).
icon
chaîne
(facultatif)

Fichier à utiliser comme icône de votre extension sur extensions.dev et la console Firebase.

Ce fichier doit être un PNG carré de 512 x 512 à 1 024 x 1 024 pixels. Placez le fichier dans le même répertoire que extension.yaml. Vous ne pouvez pas spécifier de sous-répertoire.

Lorsque vous concevez une icône pour votre extension, tenez compte des consignes suivantes :

  • Sélectionnez des couleurs d'arrière-plan et d'illustration adaptées à votre marque.
  • Utilisez seulement deux couleurs pour vos icônes. Plusieurs couleurs peuvent rendre votre icône visuellement trop chargée.
  • Pour la même raison, n'utilisez pas de dégradés dans votre icône. Les dégradés sont difficiles à distinguer à petite taille et rendent l'icône visuellement complexe.
  • Utilisez des images simples et uniques qui communiquent la fonctionnalité de votre extension.
  • Si votre entreprise crée plusieurs extensions, n'utilisez pas votre logo comme icône. Les utilisateurs auront du mal à distinguer vos extensions.
  • Rendez l'illustration graphique et audacieuse. N'utilisez pas d'illustrations délicates ou élaborées, car elles ne s'afficheront pas correctement à des tailles plus petites.
  • N'incluez pas de mots qui expliquent ce que fait votre extension. Le texte est souvent illisible dans les petites tailles.
tags
liste de chaînes
(facultatif) 		Des tags pour aider les utilisateurs à découvrir votre extension. Les tags suivants correspondent à des catégories du Hub d'extensions : marketing, messaging, payments, search, shipping, social, utilities, ai
sourceUrl
chaîne
(facultatif) 		URL publique permettant d'accéder au répertoire d'extensions.
releaseNotesUrl
chaîne
(facultatif) 		URL publique permettant d'accéder aux notes de version de l'extension.
author
one author object
(optional)

Auteur principal et point de contact pour l'extension.

author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/
Champs "Auteur"
authorName
string
(obligatoire)

Nom de l'auteur.

Il peut s'agir d'une personne, d'une entreprise, d'une organisation, etc.
email
chaîne
(facultatif) 		Adresse e-mail de l'auteur.
url
chaîne
(facultatif) 		URL publique permettant d'accéder aux informations sur l'auteur.
contributors
liste d'objets auteur
(facultatif)

Tous les autres auteurs de l'extension.

contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: colleague@example.net
    url: https://github.com/their-org/
Champs "Auteur"
authorName
string
(obligatoire)

Nom de l'auteur.

Il peut s'agir d'une personne, d'une entreprise, d'une organisation, etc.
email
chaîne
(facultatif) 		Adresse e-mail de l'auteur.
url
chaîne
(facultatif) 		URL publique permettant d'accéder aux informations sur l'auteur.

API Firebase et Google Cloud

Ces champs spécifient les API Firebase et Google utilisées par l'extension. Lorsqu'ils installent l'extension, les utilisateurs peuvent choisir d'activer automatiquement ces API dans leur projet.

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
Champs d'API
apiName
string
(obligatoire)

Nom de l'API Google

Doit correspondre au champ Nom du service tel qu'il figure sur la page de présentation de chaque API (exemple) dans la bibliothèque d'API Google Cloud.

reason
string
(obligatoire) 		Brève description expliquant pourquoi l'extension doit utiliser cette API

Rôles IAM

Ces champs spécifient les rôles Cloud IAM requis par l'extension. Le compte de service provisionné pour l'extension se voit attribuer ces rôles.

Vous ne pouvez spécifier qu'un seul des rôles acceptés.

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
Champs de rôle
role
string
(obligatoire)

Nom du rôle IAM nécessaire au fonctionnement de l'extension

Doit correspondre à l'un des rôles compatibles

reason
string
(obligatoire) 		Brève description de la raison pour laquelle l'extension a besoin de l'accès accordé par ce rôle
resource
chaîne
(facultatif)

Limitez le champ d'application du rôle à cette ressource.

Si aucune valeur n'est spécifiée, la valeur par défaut est projects/${project_id}. Consultez Réduire le champ d'application des rôles.

Services externes

Ces champs spécifient les services autres que Firebase et Google utilisés par l'extension (généralement des API REST). La plate-forme Firebase Extensions ne permet pas d'activer automatiquement ces services ni d'effectuer l'autorisation.

externalServices:
  - name: Example API
    pricingUri: https://developers.example.com/pricing
  - name: Another Example API
    pricingUri: https://developers.example.com/pricing
Champs des services externes
name
string
(obligatoire) 		Nom du service externe nécessaire au fonctionnement de l'extension
pricingUri
string
(obligatoire) 		URI vers les informations tarifaires du service

Paramètres configurables par l'utilisateur

Ces champs définissent les paramètres que l'extension met à la disposition des utilisateurs pour qu'ils puissent les configurer.

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
Champs de paramètres
param
string
(obligatoire) 		Nom du paramètre. Vous utilisez ce nom pour référencer la valeur du paramètre dans le code.
label
string
(obligatoire) 		Brève description du paramètre. S'affiche pour l'utilisateur lorsqu'il est invité à saisir la valeur du paramètre.
description
chaîne
(facultatif)

Description détaillée du paramètre. S'affiche pour l'utilisateur lorsqu'il est invité à saisir la valeur du paramètre.

Compatible avec Markdown.
example
chaîne
(facultatif) 		Exemple de valeur pour le paramètre.
default
chaîne
(facultatif) 		Valeur par défaut du paramètre si l'utilisateur laisse la valeur du paramètre vide.
validationRegex
chaîne
(facultatif) 		Expression régulière permettant de valider la valeur du paramètre configurée par l'utilisateur. Syntaxe Google RE2
validationErrorMessage
chaîne
(facultatif) 		Message d'erreur à afficher en cas d'échec de la validation de l'expression régulière.
required
boolean
(facultatif) 		Définit si l'utilisateur peut envoyer une chaîne vide lorsqu'il est invité à saisir la valeur du paramètre. La valeur par défaut est true.
immutable
boolean
(facultatif)

Définit si l'utilisateur peut modifier la valeur du paramètre après l'installation (par exemple, s'il reconfigure l'extension). La valeur par défaut est false.

Remarque : Si vous définissez un paramètre "location" pour les fonctions déployées de votre extension, définissez ce champ sur true.
type
chaîne
(facultatif) 		Type de paramètre. Les types de paramètres spéciaux peuvent avoir des exigences supplémentaires ou une présentation différente dans l'UI. Consultez les sections suivantes.

Paramètres sélectionnables et à sélection multiple

Les paramètres sélectionnables et à sélection multiple invitent les utilisateurs à choisir parmi une liste d'options prédéfinies.

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
Champs de paramètres à choix multiples
type
string

select ou multiSelect

Indique que le paramètre peut être une valeur (select) ou plusieurs valeurs (multiSelect) sélectionnées dans un ensemble de choix prédéfinis.
options
liste des options
(obligatoire)

Options parmi lesquelles l'utilisateur peut choisir

Champs d'options
value
string
(obligatoire) 		L'une des valeurs que l'utilisateur peut choisir. Il s'agit de la valeur que vous obtenez lorsque vous lisez la valeur du paramètre dans le code.
label
chaîne
(facultatif) 		Brève description de l'option sélectionnable. Si aucune valeur n'est spécifiée, la valeur par défaut est value.

Paramètres de ressources sélectionnables

Les paramètres de ressources sélectionnables invitent les utilisateurs à sélectionner une ressource (instance de base de données, bucket de stockage, etc.) dans leur projet.

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
Champs de paramètres de ressources
type
string

selectresource

Indique que le paramètre représente une ressource de projet.
resourceType
string
(obligatoire)

Type de ressource que l'utilisateur est invité à sélectionner.

Valeurs correctes :

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

Toutefois, seuls les buckets Cloud Storage disposent actuellement d'une interface utilisateur de sélection (les autres types de ressources sont présentés sous forme de champs de saisie de texte libre).

Paramètres secrets

Les valeurs secrètes fournies par l'utilisateur (telles que les clés API) sont traitées différemment :

  • Les valeurs secrètes sont stockées à l'aide de Cloud Secret Manager. Seuls les clients autorisés (tels qu'une instance installée d'une extension) peuvent accéder à ces valeurs.
  • Lorsque les utilisateurs sont invités à fournir ces valeurs, leurs saisies ne s'affichent pas.
params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What is the secret value?
    type: secret
Champs de paramètres secrets
type
string

secret

Indique que le paramètre est une valeur secrète.

Ressources Cloud Functions

Ces champs déclarent les fonctions Cloud Functions incluses dans une extension. La syntaxe de déclaration des ressources est légèrement différente entre les fonctions de 1re et de 2e génération, qui peuvent coexister dans une extension.

Cloud Functions (1re génération)

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
Champs de ressources
name
string
(obligatoire)

Nom convivial de la fonction exportée.

Si vous ne spécifiez pas la propriété entryPoint (voir ci-dessous), cette valeur doit correspondre au nom de la fonction dans le code source de vos fonctions.

Le nom final de la fonction déployée sera au format suivant : ext-extension-instance-id-name.
type
string
(obligatoire) 		Pour une ressource de fonction de 1re génération : firebaseextensions.v1beta.function
description
string
(obligatoire)

Brève description de la tâche effectuée par la fonction pour l'extension.
properties
(obligatoire)

Propriétés Cloud Functions (1re génération). Les propriétés les plus importantes sont listées ci-dessous, mais vous trouverez la liste complète dans la documentation de référence sur Cloud Functions.

Propriétés
location
(facultatif)

Emplacement où déployer la fonction. La valeur par défaut est us-central1.
entryPoint
(facultatif) 		Nom de la fonction exportée dans le code source de vos fonctions que l'extension doit rechercher. La valeur par défaut est celle de name ci-dessus.
sourceDirectory
(facultatif)

Répertoire contenant votre fichier package.json à sa racine. Le fichier du code source de vos fonctions doit se trouver dans ce répertoire. La valeur par défaut est functions.

Remarque : Le champ main de package.json spécifie le fichier du code source de vos fonctions (comme index.js).
timeout
(facultatif)

Temps d'exécution maximal de la fonction.

  • Valeur par défaut : 60s
  • Valeur maximale : 540s
availableMemoryMb
(facultatif)

Quantité de mémoire (en Mo) disponible pour la fonction.

  • Valeur par défaut : 256
  • Valeurs valides : 128, 256, 512, 1024 et 2048
runtime
(recommandé)

Environnement d'exécution de la fonction.
httpsTrigger
ou
eventTrigger
ou
scheduleTrigger
ou
taskQueueTrigger
(l'un de ces types de déclencheur de fonction est obligatoire) 		Pour en savoir plus sur chaque type de déclencheur, consultez Écrire des fonctions Cloud Functions pour une extension.

Cloud Functions (2nd gen)

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
Champs de ressources
name
string
(obligatoire)

Nom convivial de la fonction exportée.

Si vous ne spécifiez pas la propriété entryPoint (voir ci-dessous), cette valeur doit correspondre au nom de la fonction dans le code source de vos fonctions.

Le nom final de la fonction déployée sera au format suivant : ext-extension-instance-id-name.
type
string
(obligatoire) 		Pour une ressource de fonction de 2e génération : firebaseextensions.v1beta.v2function
description
string
(obligatoire)

Brève description de la tâche effectuée par la fonction pour l'extension.
properties
(obligatoire)

Propriétés Cloud Functions de 2e génération. Les propriétés les plus importantes sont listées ci-dessous, mais vous trouverez la liste complète dans la documentation de référence sur Cloud Functions.

Propriétés
location
(facultatif)

Emplacement où déployer la fonction. La valeur par défaut est us-central1.
sourceDirectory
(facultatif)

Répertoire contenant votre fichier package.json à sa racine. Le fichier du code source de vos fonctions doit se trouver dans ce répertoire. La valeur par défaut est functions.

Remarque : Le champ main de package.json spécifie le fichier du code source de vos fonctions (comme index.js).

Il existe également trois champs de type objet avec leurs propres propriétés :

Propriétés buildConfig
buildConfig.runtime
(recommandé)

Environnement d'exécution de la fonction.
buildConfig.entryPoint
(facultatif) 		Nom de la fonction exportée dans le code source de vos fonctions que l'extension doit rechercher. La valeur par défaut est celle de name ci-dessus.
Propriétés serviceConfig
serviceConfig.timeoutSeconds
(facultatif)

Temps d'exécution maximal de la fonction.

  • Valeur par défaut : 60
  • Valeur maximale : 540
serviceConfig.availableMemory
(facultatif) 		Quantité de mémoire disponible pour une fonction. La valeur par défaut est 256M. Les unités acceptées sont k, M, G, Mi et Gi. Si aucune unité n'est fournie, la valeur est interprétée en octets.
Propriétés eventTrigger
eventTrigger.eventType
(obligatoire) 		Type d'événement à écouter. Pour connaître les types d'événements disponibles pour chaque produit, consultez Écrire des fonctions Cloud Functions pour une extension.
eventTrigger.eventFilters
(facultatif) 		Filtres qui limitent davantage les événements à écouter. Par exemple, vous ne pouvez écouter que les événements correspondant à un modèle de ressource spécifique. Pour savoir comment filtrer chaque type d'événement, consultez Écrire des fonctions Cloud Functions pour une extension.
eventTrigger.channel
(facultatif) 		Nom du canal associé au déclencheur au format projects/{project}/locations/{location}/channels/{channel}. Si vous omettez cette propriété, la fonction écoutera les événements sur le canal par défaut du projet.
eventTrigger.triggerRegion
(facultatif) 		Le déclencheur ne recevra que les événements provenant de cette région. Il peut s'agir de la même région que la fonction, d'une autre région ou d'une région multirégionale, ou encore de la région mondiale. Si aucune valeur n'est fournie, la région par défaut est la même que celle de la fonction.

Événements liés au cycle de vie

Les événements de cycle de vie vous permettent de spécifier des fonctions qui s'exécuteront lorsqu'un utilisateur installe, met à jour ou configure une instance de votre extension. Consultez Gérer les événements de cycle de vie de votre extension.

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
Champs d'événement de cycle de vie
onInstall
(facultatif)

Spécifie une fonction qui s'exécute lorsqu'un utilisateur installe l'extension.

Spécification de la fonction
function
string
(obligatoire)

Nom de la fonction déclenchée par la file d'attente de tâches qui gérera l'événement.

Cette fonction doit être déclarée dans la section resources et avoir taskQueue défini.
processingMessage
string
(obligatoire) 		Message à afficher dans la console Firebase pendant que la tâche est en cours.
onUpdate
(facultatif)

Spécifie une fonction qui s'exécute lorsqu'un utilisateur met à jour l'extension.

Spécification de la fonction
function
string
(obligatoire)

Nom de la fonction déclenchée par la file d'attente de tâches qui gérera l'événement.

Cette fonction doit être déclarée dans la section resources et avoir taskQueue défini.
processingMessage
string
(obligatoire) 		Message à afficher dans la console Firebase pendant que la tâche est en cours.
onConfigure
(facultatif)

Spécifie une fonction qui s'exécute lorsqu'un utilisateur reconfigure l'extension.

Spécification de la fonction
function
string
(obligatoire)

Nom de la fonction déclenchée par la file d'attente de tâches qui gérera l'événement.

Cette fonction doit être déclarée dans la section resources et avoir taskQueue défini.
processingMessage
string
(obligatoire) 		Message à afficher dans la console Firebase pendant que la tâche est en cours.

Événements personnalisés (Eventarc)

Les événements personnalisés sont des événements émis par votre extension pour permettre aux utilisateurs d'insérer leur propre logique dans votre extension. Consultez la section Eventarc dans Ajouter des hooks utilisateur à une extension.

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
Champs d'événement personnalisé
type
string
(obligatoire) 		Identifiant de type de l'événement. Construisez l'identifiant à partir de trois ou quatre champs délimités par des points : les champs "ID d'éditeur", "Nom de l'extension" et "Nom de l'événement" sont obligatoires, et le champ "Version" est recommandé. Choisissez un nom d'événement unique et descriptif pour chaque type d'événement que vous publiez.
description
string
(obligatoire) 		Description de l'événement.