Configurer et utiliser des paramètres dans votre extension

Les paramètres permettent à un utilisateur de personnaliser chaque instance installée d'une extension. Les paramètres sont comme les variables d'environnement pour une extension. Les valeurs des paramètres peuvent être préremplies (fournies par Firebase après l'installation) ou configurées par l'utilisateur (spécifiées par l'utilisateur lors de l'installation).

Vous pouvez référencer ces paramètres dans le code source des fonctions de votre extension, dans votre fichier extension.yaml et dans votre fichier POSTINSTALL.md. Voici la syntaxe permettant de référencer un paramètre appelé PARAMETER_NAME :

  • Dans le code source de vos fonctions, utilisez le module params (par exemple, params.defineInt("PARAMETER_NAME")) ou process.env.PARAMETER_NAME.

  • Dans extension.yaml et POSTINSTALL.md, utilisez ${param:PARAMETER_NAME}.

    Après l'installation, la console Firebase affiche le contenu du fichier POSTINSTALL.md et renseigne les références de paramètres avec les valeurs réelles de l'instance installée.

Paramètres renseignés automatiquement

Chaque instance installée d'une extension a automatiquement accès à plusieurs paramètres par défaut renseignés automatiquement fournis par Firebase (voir le tableau ci-dessous). Ces valeurs de paramètre sont soit les valeurs par défaut du projet Firebase (comme le bucket Storage par défaut), soit spécifiques à l'extension (comme l'ID d'instance de l'extension).

Toutes les valeurs de paramètres renseignées automatiquement sont immuables. Elles sont définies au moment de la création du projet ou de l'installation de l'extension.

Même si Firebase renseigne automatiquement les valeurs de ces paramètres pour l'extension, Firebase ne provisionne pas automatiquement les produits associés pour l'utilisateur lors de l'installation. L'utilisateur qui installe l'extension doit activer le ou les produits associés et applicables dans son projet avant l'installation. Par exemple, si votre extension implique Cloud Firestore, l'utilisateur doit configurer Cloud Firestore dans son projet. Nous vous recommandons d'informer vos utilisateurs de ces exigences dans le fichier PREINSTALL.md.

Référence pour le paramètre renseigné automatiquement Description Valeur du paramètre (fournie par Firebase)
Paramètres avec des valeurs par défaut provenant du projet Firebase
PROJECT_ID Identifiant unique du projet Firebase dans lequel l'extension est installée

Format généralisé :
project-id

Exemple de valeur :
project-123

DATABASE_URL URL de l'instance par défaut Realtime Database du projet Firebase

Format généralisé :
https://project-id-default-rtdb.firebaseio.com
(instances aux États-Unis)
ou
https://project-id-default-rtdb.region-code.firebasedatabase.app
(instances hors États-Unis)

Exemple de valeur :
https://project-123-default-rtdb.firebaseio.com

DATABASE_INSTANCE

Nom de l'instance par défaut Realtime Database du projet Firebase

En général, cette valeur est identique à l'ID du projet ou se termine par -default-rtdb.

Format généralisé :
project-id

Exemple de valeur :
project-123

STORAGE_BUCKET Nom du bucket Cloud Storage par défaut du projet Firebase

Format généralisé :
PROJECT_ID.firebasestorage.app

Exemple de valeur :
project-123.firebasestorage.app

Paramètre avec une valeur par défaut provenant de l'installation de l'extension
EXT_INSTANCE_ID

Identifiant unique de l'instance d'extension installée

Cette valeur est générée à partir du champ name spécifié dans le fichier extension.yaml.

Format généralisé pour la première instance installée (attribuée automatiquement par Firebase ; ne peut pas être modifié par l'utilisateur lors de l'installation) :
name-from-extension.yaml

Exemple de valeur :
my-awesome-extension


Format généralisé pour la deuxième instance installée et les suivantes (attribué automatiquement par Firebase, peut être modifié par l'utilisateur lors de l'installation) :
name-from-extension.yaml-4-digit-alphanumeric-hash

Exemple de valeur :
my-awesome-extension-6m31

Paramètres configurés par l'utilisateur

Pour permettre à un utilisateur de personnaliser chaque instance installée d'une extension, vous pouvez lui demander de spécifier des valeurs de paramètres lors de l'installation. Pour demander ces valeurs, vous devez configurer les invites dans la section params de votre fichier extension.yaml.

Vous trouverez ci-dessous un exemple de section params, suivi d'un tableau décrivant tous les champs de paramètres disponibles.

# extension.yaml
...

# Parameters (environment variables) for which the user specifies values during installation
params:
  - param: DB_PATH
    label: Realtime Database path
    description: >-
      What is the Realtime Database path where you will write new text
      for sentiment analysis?
    type: string
    validationRegex: ^\S+$
    validationErrorMessage: Realtime Database path cannot contain spaces.
    example: path/to/posts
    required: true

  - param: TEXT_KEY
    label: Key for text
    description: What is the name of the key that will contain text to be analyzed?
    type: string
    default: textToAnalyze
    required: true

Dans la section params de votre fichier extension.yaml, utilisez les champs suivants pour définir un paramètre configuré par l'utilisateur :

Champ Type Description
param
(obligatoire) 		chaîne Nom du paramètre
label
(obligatoire) 		chaîne

Brève description du paramètre

Affiché à l'utilisateur lorsqu'il est invité à saisir la valeur du paramètre

description
(facultatif) 		chaîne

Description détaillée du paramètre

Affiché à l'utilisateur lorsqu'il est invité à saisir la valeur du paramètre

Compatible avec Markdown

type
(facultatif) 		chaîne

Mécanisme de saisie permettant à l'utilisateur de définir la valeur du paramètre (par exemple, saisir du texte directement ou sélectionner une valeur dans une liste déroulante)

Les valeurs valides sont les suivantes:

  • string : permet la saisie de texte libre (dans la limite de votre validationRegex)
  • select : permet de sélectionner une entrée dans une liste d'options prédéfinie. Si vous spécifiez cette valeur, vous devez également définir le champ options.
  • multiSelect : permet de sélectionner une ou plusieurs entrées dans une liste d'options prédéfinie. Si vous spécifiez cette valeur, vous devez également définir le champ options.
  • selectResource : permet de sélectionner un type spécifique de ressource Firebase (tel qu'un bucket Cloud Storage) à partir du projet de l'utilisateur.

    Lorsque vous spécifiez un paramètre de ce type, les utilisateurs obtiennent un widget de sélection plus convivial dans l'UI d'installation. Pour cette raison, utilisez des paramètres selectResource chaque fois que possible.

    Si vous spécifiez cette valeur, vous devez également définir le champ resourceType.

  • secret : permet de stocker des chaînes sensibles, telles que des clés API pour des services tiers. Ces valeurs seront stockées dans Cloud Secret Manager.

    Cloud Secret Manager est un service payant dont l'utilisation peut entraîner des frais pour les utilisateurs qui installent votre extension. Si vous utilisez le type de paramètre secret, veillez à indiquer dans votre fichier PREINSTALL que votre extension utilise Cloud Secret Manager.

Si ce champ est omis, le paramètre est défini par défaut sur type sur string.

options
(obligatoire si le paramètre type est défini sur select ou multiSelect) 		list

Liste des valeurs parmi lesquelles l'utilisateur peut choisir

Incluez les champs label et value dans le champ options :

  • label (chaîne) : brève description de l'option sélectionnable
  • value (chaîne) : valeur réelle de l'option sélectionnable

Le champ value est obligatoire pour le champ options.
Si label est omis, l'option de liste est définie par défaut sur l'affichage value.
resourceType
(obligatoire si le paramètre type est défini sur selectResource) 		chaîne

Type de ressource Firebase que l'utilisateur est invité à sélectionner. Actuellement, seuls les buckets Cloud Storage sont compatibles avec les sélecteurs de ressources :

Type de ressource ID du type
Cloud Storage bucket storage.googleapis.com/Bucket

Les valeurs resourceType inconnues seront ignorées et l'UI affichera le paramètre sous la forme d'un champ de saisie string de forme libre.
example
(facultatif) 		chaîne

Exemple de valeur pour le paramètre
validationRegex
(facultatif)
(ne s'applique que lorsque le paramètre type est défini sur string) 		chaîne

Chaîne d'expression régulière pour valider la valeur configurée par l'utilisateur pour le paramètre

L'expression régulière est compilée à l'aide de la bibliothèque Go : RE2

Pour en savoir plus sur la validation, consultez la section Validation et messages d'erreur ci-dessous.

validationErrorMessage
(facultatif) 		chaîne

Message d'erreur à afficher si validationRegex échoue

Pour en savoir plus sur les messages d'erreur, consultez la section Messages de validation et d'erreur ci-dessous.

default
(facultatif) 		chaîne

Valeur par défaut du paramètre si l'utilisateur laisse la valeur du paramètre vide

Le cas échéant, vous pouvez spécifier une valeur de paramètre préremplie pour la valeur default (pour obtenir un exemple, consultez le paramètre IMG_BUCKET de l'extension Redimensionner les images).

required
(facultatif) 		booléen

Définit si l'utilisateur peut envoyer une chaîne vide lorsqu'il est invité à saisir la valeur du paramètre.

Si required est omis, la valeur par défaut est true (c'est-à-dire un paramètre obligatoire).

immutable
(facultatif) 		booléen

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

Si immutable est omis, 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, vous devez inclure ce champ immutable dans son objet de paramètre.

Validation et messages d'erreur pour les valeurs configurées par l'utilisateur

Lorsque vous configurez un paramètre avec le type de string, vous devez définir une validation regex appropriée via le champ validationRegex du paramètre.

De plus, pour de nombreuses extensions, une valeur de paramètre fréquemment demandée est un chemin d'accès à la base de données ou un bucket Cloud Storage. Sachez que lors de l'installation, de la reconfiguration ou de la mise à jour, le service Extensions ne valide pas les éléments suivants au moment de l'saisie de la valeur du paramètre :

  • Indique si la base de données ou le bucket Cloud Storage spécifiés sont configurés dans le projet Firebase de l'utilisateur.
  • Indique si le chemin d'accès à la base de données spécifié existe dans la base de données de l'utilisateur.

Toutefois, lorsque l'extension déploie réellement ses ressources, la console Firebase ou la CLI Firebase affichent un message d'erreur si la base de données ou le bucket Cloud Storage référencés ne sont pas encore configurés dans le projet.

Nous vous recommandons vivement d'informer les utilisateurs dans le fichier PREINSTALL de ces exigences afin que, lorsqu'ils installent votre extension, elle s'installe correctement et fonctionne comme prévu.

Paramètres système

Les paramètres système contrôlent la configuration de base des ressources d'une extension. Comme elles sont destinées à contrôler la configuration des ressources, elles ne sont pas accessibles en tant que variables d'environnement depuis le code de votre fonction.

En règle générale, vous n'avez rien à déclarer pour ces paramètres dans extension.yaml. Elles sont définies automatiquement pour chaque instance d'extension, et les utilisateurs ont la possibilité de définir des valeurs personnalisées lorsqu'ils installent votre extension.

Toutefois, si votre extension a des exigences particulières en termes de ressources, vous pouvez définir des valeurs spécifiques pour chaque ressource dans extension.yaml. Ces paramètres de configuration par ressource remplaceront les paramètres de l'utilisateur pour l'ensemble de l'instance d'extension. Exemple :

resources:
- name: high_memory_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function needs at least 1GB of memory!
  properties:
    httpsTrigger: {}
    runtime: nodejs18
    availableMemoryMb: 1024
- name: normal_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function has no special memory requirements. It will use the
    default value, or the value of `firebaseextension.v1beta.function/memory`
  properties:
    httpsTrigger: {}
    runtime: nodejs18

Les paramètres système disponibles sont les suivants :

Nom Libellé (lisible par l'utilisateur) Champ correspondant dans properties Description
firebaseextensions.v1beta.function/location Emplacement location Dans quelle région Cloud Functions doit-il être déployé ?
firebaseextensions.v1beta.function/memory Mémoire de la fonction memory Combien de mégaoctets de mémoire doivent être alloués à chaque fonction ?
firebaseextensions.v1beta.function/timeoutSeconds Délai avant expiration de la fonction timeout Combien de secondes les fonctions doivent-elles s'exécuter avant d'expirer ?
firebaseextensions.v1beta.function/vpcConnectorEgressSettings Sortie du connecteur VPC vpcConnectorEgressSettings Contrôle le trafic sortant lorsqu'un connecteur VPC est configuré
firebaseextensions.v1beta.function/vpcConnector Connecteur VPC vpcConnector Connecte Cloud Functions au connecteur VPC spécifié.
firebaseextensions.v1beta.function/minInstances Nombre minimal d'instances de fonction minInstances Nombre minimal d'instances de cette fonction à exécuter simultanément
firebaseextensions.v1beta.function/maxInstances Nombre maximum d'instances de fonction maxInstances Nombre maximal d'instances de cette fonction à exécuter simultanément
firebaseextensions.v1beta.function/ingressSettings Paramètres d'entrée ingressSettings Contrôle les sources à partir desquelles le trafic entrant est accepté
firebaseextensions.v1beta.function/labels Étiquettes labels Libellés à appliquer à toutes les ressources de l'extension