Configura y usa parámetros en tu extensión

Los parámetros son el mecanismo a través del cual un usuario personaliza cada instancia instalada de una extensión. Los parámetros son como las variables de entorno de una extensión. Los valores de los parámetros se pueden propagar automáticamente (proporcionados por Firebase) o los puede configurar el usuario (los especifica el usuario durante la instalación).

Estos parámetros están disponibles para que los consultes en el código fuente de las funciones de tu extensión, o en los archivos extension.yaml o POSTINSTALL.md. Esta es la sintaxis para hacer referencia a un parámetro llamado PARAMETER_NAME:

  • Dentro del código fuente de las funciones, usa el módulo params (por ejemplo, params.defineInt("PARAMETER_NAME")) o process.env.PARAMETER_NAME.

  • Dentro de extension.yaml y POSTINSTALL.md, usa ${param:PARAMETER_NAME}.

    Después de la instalación, Firebase console muestra el contenido del archivo POSTINSTALL.md y propaga las referencias de parámetros con los valores reales de la instancia instalada.

Parámetros de propagación automática

Cada instancia instalada de una extensión tiene acceso a varios parámetros de propagación automática que proporciona Firebase (consulta la siguiente tabla). Estos son los valores de parámetros predeterminados del proyecto de Firebase (como el depósito predeterminado de Storage ) o son específicos de la extensión (como el ID de instancia de la extensión).

Todos los valores de parámetros de propagación automática son inmutables. Se establecen en el momento de la creación del proyecto o de la instalación de la extensión.

Aunque Firebase propaga automáticamente estos valores de parámetros para la extensión, Firebase no aprovisiona automáticamente los productos asociados para el usuario durante la instalación. El usuario que instala la extensión debe habilitar los productos asociados y aplicables en su proyecto antes de la instalación. Por ejemplo, si tu extensión involucra Cloud Firestore, el usuario debe configurar Cloud Firestore en su proyecto. Recomendamos notificar a los usuarios sobre estos requisitos en el archivo PREINSTALL.md.

Referencia del parámetro de propagación automática Descripción Valor del parámetro (proporcionado por Firebase)
Parámetros con valores predeterminados del proyecto de Firebase
PROJECT_ID Identificador único para el proyecto de Firebase en el que está instalada la extensión

Formato generalizado:
project-id

Valor de ejemplo:
project-123

DATABASE_URL La URL de la instancia de Realtime Database predeterminada del proyecto de Firebase

Formato generalizado:
https://project-id-default-rtdb.firebaseio.com
(instancias de EE.UU.)
o
https://project-id-default-rtdb.region-code.firebasedatabase.app
(instancias fuera de EE.UU.)

Valor de ejemplo:
https://project-123-default-rtdb.firebaseio.com

DATABASE_INSTANCE

El nombre predeterminado de la instancia de Realtime Database del proyecto de Firebase

Por lo general, este valor es el mismo que el ID del proyecto o termina en -default-rtdb.

Formato generalizado:
project-id

Valor de ejemplo:
project-123

STORAGE_BUCKET El nombre predeterminado del depósito de Cloud Storage del proyecto de Firebase

Formato generalizado:
PROJECT_ID.firebasestorage.app

Valor de ejemplo:
project-123.firebasestorage.app

Parámetro con valor predeterminado de la instalación de la extensión
EXT_INSTANCE_ID

Identificador único para la instancia de extensión instalada

Este valor se genera a partir del campo name especificado en el archivo extension.yaml.

Formato generalizado para la primera instancia instalada (asignada automáticamente por Firebase; el usuario no lo puede modificar durante la instalación):
name-from-extension.yaml

Valor de ejemplo:
my-awesome-extension


Formato generalizado para la segunda instancia instalada y las instancias posteriores (asignado automáticamente por Firebase; el usuario puede modificarlo durante la instalación):
name-from-extension.yaml-4-digit-alphanumeric-hash

Valor de ejemplo:
my-awesome-extension-6m31

Parámetros configurados por el usuario

Para permitir que un usuario personalice cada instancia instalada de una extensión, puedes pedirle que especifique valores de parámetros durante la instalación. Para solicitar estos valores, configura los mensajes en la sección params del archivo extension.yaml.

A continuación, se muestra una sección params de ejemplo, seguida de una tabla que describe todos los campos de parámetros 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

En la sección params del archivo extension.yaml, usa los siguientes campos para definir un parámetro configurado por el usuario:

Campo Tipo Descripción
param
(obligatorio) 		string Nombre del parámetro
label
(obligatorio) 		string

Descripción breve del parámetro

Se muestra al usuario cuando se le solicita el valor del parámetro.
description
(opcional) 		string

Descripción detallada del parámetro

Se muestra al usuario cuando se le solicita el valor del parámetro.

Admite Markdown

type
(opcional) 		string

Mecanismo de entrada del método que debe utilizar el usuario para establecer el valor del parámetro (por ejemplo, ingresar texto directamente o seleccionar un valor de una lista desplegable)

Los valores válidos incluyen lo siguiente:

  • string: Permite la entrada de texto de formato libre (como lo limita tu validationRegex).
  • select: Permite seleccionar una entrada de una lista predefinida de opciones. Si especificas este valor, también debes definir el campo options.
  • multiSelect: Permite seleccionar una o más entradas de una lista predefinida de opciones. Si especificas este valor, también debes definir el campo options.
  • selectResource: Permite seleccionar un tipo específico de recurso de Firebase (como un bucket de Cloud Storage) del proyecto del usuario.

    Cuando especifiques un parámetro de este tipo, los usuarios obtendrán un widget de selección más fácil de usar en la IU de instalación. Por este motivo, usa parámetros selectResource siempre que sea posible.

    Si especificas este valor, también debes definir el campo resourceType.

  • secret: Permite el almacenamiento de cadenas sensibles, como claves de API para servicios de terceros. Estos valores se almacenarán en Cloud Secret Manager.

    Cloud Secret Manager es un servicio pagado cuyo uso podría generar cargos para los usuarios que instalen tu extensión. Si usas el tipo de parámetro secret, asegúrate de documentar en tu archivo PREINSTALL que tu extensión usa Cloud Secret Manager.

Si se omite este campo, el parámetro predeterminado es type de string.

options
(obligatorio si el parámetro type es select o multiSelect) 		list

Lista de valores que el usuario puede seleccionar

Incluye los campos label y value en el campo options:

  • label (string): descripción breve de la opción seleccionable
  • value (string): valor real de la opción seleccionable

El campo value es obligatorio para el campo options.
Si se omite label, la opción de lista muestra value de forma predeterminada.
resourceType
(obligatorio si el parámetro type es selectResource) 		string

Es el tipo de recurso de Firebase que se le pide seleccionar al usuario. Actualmente, solo los buckets de Cloud Storage admiten selectores de recursos:

Tipo de recurso ID de tipo
Cloud Storage bucket storage.googleapis.com/Bucket

Se pasarán por alto los valores resourceType desconocidos y la IU renderizará el parámetro como un campo de entrada string de formato libre.
example
(opcional) 		string

Valor de ejemplo para el parámetro
validationRegex
(opcional)
(solo aplicable cuando el parámetro type es string)		 string

String de regex para la validación del valor configurado por el usuario para el parámetro

La regex se compila con la biblioteca de Go: RE2

Para obtener detalles sobre la validación, consulta la página sobre validación y mensajes de error a continuación.

validationErrorMessage
(opcional) 		string

Mensaje de error para mostrar si validationRegex falla

Para obtener más información sobre los mensajes de error, consulta la página sobre validación y mensajes de error a continuación.

default
(opcional) 		string

Valor predeterminado del parámetro si el usuario lo deja en blanco

Si corresponde, puedes especificar un valor del parámetro propagado automáticamente para el valor default (por ejemplo, consulta el parámetro IMG_BUCKET de la extensión Resize Images).

required
(opcional) 		booleano

Define si el usuario puede enviar una string vacía cuando se le solicita el valor del parámetro.

Si se omite required, el valor predeterminado es true (es decir, un parámetro obligatorio).
immutable
(opcional) 		booleano

Define si el usuario puede cambiar el valor del parámetro después de la instalación (por ejemplo, si reconfigura la extensión).

Si se omite immutable, el valor predeterminado es false.

Nota: Si defines un parámetro “location” para las funciones implementadas de tu extensión, debes incluir este campo immutable en su objeto param.

Validación y mensajes de error para los valores configurados por el usuario

Cuando configuras un parámetro con el type de string, debes definir la validación de regex adecuada a través del campo validationRegex del parámetro.

Además, para muchas extensiones, un valor de parámetro solicitado con frecuencia es una ruta de base de datos o un bucket de Cloud Storage. Ten en cuenta que, durante la instalación, reconfiguración o actualización, el servicio de Extensions no valida lo siguiente cuando se ingresa el valor del parámetro:

  • Si la base de datos o el bucket de Cloud Storage especificados están configurados dentro del proyecto de Firebase del usuario
  • Si la ruta de la base de datos especificada existe dentro de la base de datos del usuario

Sin embargo, cuando la extensión implementa sus recursos, Firebase console o Firebase CLI mostrarán un mensaje de error si la base de datos o el bucket de Cloud Storage referenciados aún no están configurados en el proyecto.

Recomendamos encarecidamente que notifiques a los usuarios acerca de estos requisitos en el archivo PREINSTALL para que cuando instalen la extensión, el proceso y la funcionalidad sean los esperados.

Parámetros del sistema

Los parámetros del sistema controlan la configuración básica de los recursos de una extensión. Como están destinados a controlar la configuración de recursos, no se puede acceder a ellos como variables de entorno desde el código de tu función.

Por lo general, no es necesario declarar nada para estos parámetros en extension.yaml. Se definen automáticamente para cada instancia de extensión, y los usuarios tienen la oportunidad de configurar valores personalizados cuando la instalan.

Sin embargo, si la extensión tiene requisitos de recursos especiales, puedes establecer valores específicos a nivel de cada recurso en extension.yaml. Esta configuración por recurso anulará la configuración para toda la instancia de la extensión del usuario. Por ejemplo:

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

Estos son los parámetros disponibles del sistema:

Nombre Etiqueta (legible por humanos) Campo correspondiente en properties Descripción
firebaseextensions.v1beta.function/location Ubicación location ¿En qué región se debe implementar Cloud Functions?
firebaseextensions.v1beta.function/memory Memoria de la función memory ¿Cuántos megabytes de memoria se deben asignar a cada función?
firebaseextensions.v1beta.function/timeoutSeconds Tiempo de espera de la función timeout ¿Cuántos segundos deben ejecutarse las funciones antes de que se agote el tiempo de espera?
firebaseextensions.v1beta.function/vpcConnectorEgressSettings Salida del conector de VPC vpcConnectorEgressSettings Controla el tráfico saliente cuando se configura un conector de VPC.
firebaseextensions.v1beta.function/vpcConnector Conector de VPC vpcConnector Conecta Cloud Functions al conector de VPC especificado.
firebaseextensions.v1beta.function/minInstances La cantidad mínima de instancias de función. minInstances La cantidad mínima de instancias de esta función que se ejecutarán a la vez.
firebaseextensions.v1beta.function/maxInstances Cantidad máxima de instancias maxInstances La cantidad máxima de instancias de esta función que se ejecutarán a la vez.
firebaseextensions.v1beta.function/ingressSettings Configuración de entrada ingressSettings Controla desde dónde se acepta el tráfico entrante.
firebaseextensions.v1beta.function/labels Etiquetas labels Las etiquetas que se aplicarán a todos los recursos de la extensión.