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 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: [email protected]
  url: https://example.com/
contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: [email protected]
    url: https://github.com/their-org/

author:
  authorName: Your Company
  email: [email protected]
  url: https://example.com/

contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: [email protected]
    url: https://github.com/their-org/

API Firebase et Google Cloud

Ces champs indiquent les API Firebase et Google que l'extension utilise. 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

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 compatibles.

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

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

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

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

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

Paramètres secrets

Les valeurs de secrets 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

Ressources Cloud Functions

Ces champs déclarent les fonctions Cloud Functions incluses dans une extension. La syntaxe de déclaration de ressources est légèrement différente entre les fonctions de première et de deuxième 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

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

É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

É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