Documentation de référence sur 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 ainsi que 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
chaîne
(obligatoire)

Identifiant de l'extension.

Il ne peut contenir que des lettres minuscules, des chiffres et des tirets. La limite est de 40 caractères.

Remarque:Cette valeur permet de 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
chaîne
(obligatoire)

Version de l'extension.

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

Version de la spécification des extensions Firebase.

Valeur actuelle : v1beta
license
chaîne
(facultatif)

Licence pour l'extension.

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

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

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

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

Limite de 40 caractères.
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 dans la console Firebase.

Ce fichier doit être un fichier 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.

Tenez compte des consignes suivantes lorsque vous concevez une icône pour votre extension:

  • Sélectionnez les couleurs d'arrière-plan et d'illustration appropriées pour votre marque.
  • Utilisez des couleurs d'icône simples, en n'utilisant que deux couleurs. En multipliant les couleurs, l'icône peut être visuellement irréprochable.
  • Pour la même raison, n'utilisez pas de dégradés dans votre icône. Les dégradés sont difficiles à discerner à petite échelle et rendent l'icône visuellement complexe.
  • Utilisez des images simples et uniques qui communiquent les fonctionnalités 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.
  • Faites en sorte que l'illustration soit graphique et audacieuse. N'utilisez pas d'illustrations délicates ou élaborées qui ne donneront pas un résultat satisfaisant dans des tailles plus petites.
  • N'incluez pas de mots qui expliquent le fonctionnement de votre extension. Le texte est souvent illisible dans des tailles plus petites.
tags
liste de chaînes
(facultatif) 		Tags pour aider les utilisateurs à découvrir votre extension Les balises suivantes correspondent à des catégories dans le hub Extensions : marketing, messaging, payments, search, shipping, social, utilities, ai
sourceUrl
chaîne
(facultatif) 		URL publique permettant d'accéder au répertoire de l'extension.
releaseNotesUrl
chaîne
(facultatif) 		URL publique permettant d'accéder aux notes de version de l'extension.
author
1 objet auteur
(facultatif)

Auteur principal et point de contact de l'extension.

author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/
Champs "Auteur"
authorName
chaîne
(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 des objets auteurs
(facultatif)

Tout autre auteur ayant contribué à l'extension.

contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: colleague@example.net
    url: https://github.com/their-org/
Champs "Auteur"
authorName
chaîne
(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. Lorsque les utilisateurs installent l'extension, ils 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 de l'API
apiName
chaîne
(obligatoire)

Nom de l'API Google

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

reason
chaîne
(obligatoire) 		Brève description des raisons pour lesquelles 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
chaîne
(obligatoire)

Nom du rôle IAM requis pour que l'extension fonctionne

Doit correspondre à l'un des rôles compatibles

reason
chaîne
(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 la portée 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 fournit aucun moyen 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
chaîne
(obligatoire) 		Nom du service externe nécessaire au fonctionnement de l'extension
pricingUri
chaîne
(obligatoire) 		URI des 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 afin de 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ètre
param
chaîne
(obligatoire) 		Nom du paramètre. Vous utiliserez ce nom pour faire référence à la valeur du paramètre dans le code.
label
chaîne
(obligatoire) 		Brève description du paramètre. est affiché lorsque l'utilisateur 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 vide.
validationRegex
chaîne
(facultatif) 		Expression régulière pour la validation de la valeur configurée par l'utilisateur du paramètre. Syntaxe Google RE2
validationErrorMessage
chaîne
(facultatif) 		Message d'erreur à afficher en cas d'échec de la validation par expression régulière.
required
booléen
(facultatif) 		Définit si l'utilisateur peut envoyer une chaîne vide lorsqu'il est invité à indiquer la valeur du paramètre. La valeur par défaut est true.
immutable
booléen
(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 présenter des exigences supplémentaires ou une présentation différente de l'interface utilisateur. 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
Chaîne

select ou multiselect

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

Options parmi lesquelles l'utilisateur peut choisir

Champs d'options
value
chaîne
(obligatoire) 		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
Chaîne

selectresource

Indique que le paramètre représente une ressource de projet
resourceType
chaîne
(obligatoire)

Type de ressource que l'utilisateur doit sélectionner.

Valeurs correctes :

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

Cependant, seuls les buckets Cloud Storage disposent actuellement d'une UI 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 du secret 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, leur entrée n'est pas affichée.
params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What is the secret value?
    type: secret
Champs de paramètres des secrets
type
Chaîne

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 de 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
chaîne
(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
chaîne
(obligatoire) 		Pour une ressource de fonction de 1re génération : firebaseextensions.v1beta.function
description
chaîne
(obligatoire)

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

Propriétés Cloud Functions de 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 name, ci-dessus.
sourceDirectory
(facultatif)

Répertoire contenant votre package.json à la 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 contenant le 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éclencheurs 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
chaîne
(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
chaîne
(obligatoire) 		Pour une ressource de fonction de 2e génération : firebaseextensions.v1beta.v2function
description
chaîne
(obligatoire)

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

Propriétés Cloud Functions (2e génération) Les propriétés les plus importantes sont répertoriées ci-dessous, mais vous trouverez la liste complète dans la documentation de référence de 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 package.json à la 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 contenant le code source de vos fonctions (comme index.js).

Il existe également trois champs de type d'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 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 spécifiée, la valeur est interprétée comme des 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 la section É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 en savoir plus sur le filtrage de chaque type d'événement, consultez la section É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 de la région globale. Si aucune valeur n'est spécifiée, la valeur par défaut est la même région que la fonction.

Événements liés au cycle de vie

Les événements de cycle de vie vous permettent de spécifier les fonctions qui s'exécutent 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énements 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
chaîne
(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 taskQueue doit être défini.
processingMessage
chaîne
(obligatoire) 		Message à afficher dans la console Firebase pendant l'exécution de la tâche.
onUpdate
(facultatif)

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

Spécification de la fonction
function
chaîne
(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 taskQueue doit être défini.
processingMessage
chaîne
(obligatoire) 		Message à afficher dans la console Firebase pendant l'exécution de la tâche.
onConfigure
(facultatif)

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

Spécification de la fonction
function
chaîne
(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 taskQueue doit être défini.
processingMessage
chaîne
(obligatoire) 		Message à afficher dans la console Firebase pendant l'exécution de la tâche.

É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és
type
chaîne
(obligatoire) 		Identifiant de type de l'événement. Créez l'identifiant à partir de trois à quatre champs séparés par des points : les champs "ID de l'é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
chaîne
(obligatoire) 		Description de l'événement.