Configurer et utiliser des paramètres dans votre extension

Les paramètres sont le mécanisme par lequel un utilisateur personnalise chaque instance installée d'une extension. Les paramètres sont comme les variables d'environnement d'une extension. Les valeurs des paramètres peuvent être renseignées automatiquement (fournies par Firebase après l'installation) ou configurées par l'utilisateur (spécifiées par l'utilisateur lors de l'installation).

Ces paramètres sont disponibles pour référence dans le code source des fonctions de votre extension, votre fichier extension.yaml et votre fichier POSTINSTALL.md . Voici la syntaxe pour 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 remplit toutes les références de paramètre 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 renseignés automatiquement par défaut fournis par Firebase (reportez-vous au tableau ci-dessous). Ces valeurs de paramètres sont soit les valeurs par défaut du projet Firebase (comme le compartiment de stockage par défaut ), soit elles sont spécifiques à l'extension (comme l'ID d'instance de l'extension).

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

Même si Firebase remplit automatiquement ces valeurs de paramètre 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 .

Paramètres configurés par l'utilisateur

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

Voici 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 :

options:
  - label:
    value:
  - label:
    value:
  - label:
    value:

Validation et message 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 la validation regex appropriée via le champ validationRegex du paramètre.

En outre, pour de nombreuses extensions, une valeur de paramètre couramment 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 la saisie de la valeur du paramètre :

• Si la base de données ou le bucket Cloud Storage spécifié est configuré dans le projet Firebase de l'utilisateur
• Si le chemin de base de données spécifié existe dans la base de données de l'utilisateur

Cependant, lorsque l'extension déploie réellement ses ressources, la console Firebase ou la CLI Firebase affiche un message d'erreur si la base de données référencée ou le bucket Cloud Storage n'est pas encore configuré 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, celle-ci 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. Puisqu'ils sont destinés à contrôler la configuration des ressources, ils ne sont pas accessibles en tant que variables d'environnement à partir de votre code de fonction.

Vous n'avez normalement pas besoin de déclarer quoi que ce soit pour ces paramètres dans extension.yaml . Ils sont automatiquement définis 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 besoins particuliers en ressources, vous pouvez définir des valeurs spécifiques au niveau de chaque ressource dans extension.yaml . Ces paramètres de configuration par ressource remplaceront les paramètres à l'échelle de l'instance de l'extension de l'utilisateur. Par exemple:

resources:
- name: high_memory_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function needs at least 1GB of memory!
  properties:
    httpsTrigger: {}
    runtime: nodejs18
    memory: 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 paramètres sont le mécanisme par lequel un utilisateur personnalise chaque instance installée d'une extension. Les paramètres sont comme les variables d'environnement d'une extension. Les valeurs des paramètres peuvent être renseignées automatiquement (fournies par Firebase après l'installation) ou configurées par l'utilisateur (spécifiées par l'utilisateur lors de l'installation).

Ces paramètres sont disponibles pour référence dans le code source des fonctions de votre extension, votre fichier extension.yaml et votre fichier POSTINSTALL.md . Voici la syntaxe pour 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 remplit toutes les références de paramètre 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 renseignés automatiquement par défaut fournis par Firebase (reportez-vous au tableau ci-dessous). Ces valeurs de paramètres sont soit les valeurs par défaut du projet Firebase (comme le compartiment de stockage par défaut ), soit elles sont spécifiques à l'extension (comme l'ID d'instance de l'extension).

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

Même si Firebase remplit automatiquement ces valeurs de paramètre 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 .

Paramètres configurés par l'utilisateur

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

Voici 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 :

options:
  - label:
    value:
  - label:
    value:
  - label:
    value:

Validation et message 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 la validation regex appropriée via le champ validationRegex du paramètre.

En outre, pour de nombreuses extensions, une valeur de paramètre couramment 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 la saisie de la valeur du paramètre :

• Si la base de données ou le bucket Cloud Storage spécifié est configuré dans le projet Firebase de l'utilisateur
• Si le chemin de base de données spécifié existe dans la base de données de l'utilisateur

Cependant, lorsque l'extension déploie réellement ses ressources, la console Firebase ou la CLI Firebase affiche un message d'erreur si la base de données référencée ou le bucket Cloud Storage n'est pas encore configuré 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, celle-ci 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. Puisqu'ils sont destinés à contrôler la configuration des ressources, ils ne sont pas accessibles en tant que variables d'environnement à partir de votre code de fonction.

Vous n'avez normalement pas besoin de déclarer quoi que ce soit pour ces paramètres dans extension.yaml . Ils sont automatiquement définis 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 besoins particuliers en ressources, vous pouvez définir des valeurs spécifiques au niveau de chaque ressource dans extension.yaml . Ces paramètres de configuration par ressource remplaceront les paramètres à l'échelle de l'instance de l'extension de l'utilisateur. Par exemple:

resources:
- name: high_memory_function
  type: firebaseextensions.v1beta.function
  description: >-
    This function needs at least 1GB of memory!
  properties:
    httpsTrigger: {}
    runtime: nodejs18
    memory: 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 :