Referencia para extension.yaml

El archivo de especificaciones de su extensión ( extension.yaml ) contiene los metadatos de su extensión, declara los recursos creados por la extensión y las API y el acceso requerido por la extensión, y define los parámetros configurados por el usuario proporcionados por la extensión.

Las tablas de esta página describen los campos disponibles para un archivo extension.yaml .

Información básica y identificativa

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/
Campos básicos
name
cadena
(requerido)

Identificador de la extensión.

Sólo puede contener letras minúsculas, números y guiones; Límite de 40 caracteres.

Nota: Este valor se usa para generar el ID de instancia de la extensión (que luego se usa para generar los nombres de la cuenta de servicio de la extensión y los recursos específicos de la extensión).

version
cadena
(requerido)

Versión de la extensión.

Debe seguir el control de versiones de semver (por ejemplo, 1.2.0).

specVersion
cadena
(requerido)

Versión de la especificación de Firebase Extensions.

Valor actual: v1beta

license
cadena
(opcional)

Licencia para la extensión.

Su extensión debe tener una licencia que utilice Apache-2.0 .

billingRequired
booleano
(opcional)

Si los servicios utilizados por la extensión requieren una cuenta de facturación de Firebase de nivel pago.

Siempre establecido en true .

displayName
cadena
(opcional)

Nombre para mostrar descriptivo para la extensión (3-5 palabras).

Límite de 40 caracteres.

description
cadena
(opcional)		 Breve descripción de la tarea que realiza su extensión (~1 oración).
icon
cadena
(opcional)

Archivo para usar como ícono de su extensión en extensions.dev y Firebase console.

Este archivo debe ser un PNG cuadrado de entre 512x512 y 1024x1024 píxeles. Coloque el archivo en el mismo directorio que extension.yaml ; no se puede especificar un subdirectorio.

Tenga en cuenta las siguientes pautas al diseñar un ícono para su extensión:

  • Seleccione colores de fondo y de arte que sean apropiados para su marca.
  • Mantenga los colores de sus íconos simples, usando solo 2 colores. Múltiples colores pueden hacer que tu ícono sea visualmente abrumador.
  • Por la misma razón, no uses degradados en tu ícono. Los degradados son difíciles de discernir en tamaños pequeños y hacen que el ícono sea visualmente complejo.
  • Utilice imágenes simples y únicas que comuniquen la funcionalidad de su extensión.
  • Si su empresa crea varias extensiones, no utilice su logotipo como icono. Los usuarios tendrán dificultades para distinguir entre sus extensiones.
  • Haz que la obra de arte sea gráfica y atrevida. No utilices obras de arte delicadas o elaboradas, que no se reproducirán bien en tamaños más pequeños.
  • No incluya palabras que expliquen lo que hace su extensión. El texto suele ser ilegible en tamaños más pequeños.
tags
lista de cadenas
(opcional)		 Etiquetas para ayudar a los usuarios a descubrir su extensión. Las siguientes etiquetas se asignan a categorías en Extensions Hub: marketing , messaging , payments , search , shipping , social , utilities , ai
sourceUrl
cadena
(opcional)		 URL pública donde se puede acceder al directorio de extensiones.
releaseNotesUrl
cadena
(opcional)		 URL pública donde se puede acceder a las notas de la versión de la extensión.
author
un objeto de autor
(opcional)

Autor principal y punto de contacto para la extensión.

author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/
Campos de autor
authorName
cadena
(requerido)

Nombre del autor.

Puede ser una persona, empresa, organización, etc.

email
cadena
(opcional)		 Dirección de correo electrónico del autor.
url
cadena
(opcional)		 URL pública donde se puede acceder a información sobre el autor.
contributors
lista de objetos de autor
(opcional)

Cualquier autor colaborador adicional para la extensión.

contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: colleague@example.net
    url: https://github.com/their-org/
Campos de autor
authorName
cadena
(requerido)

Nombre del autor.

Puede ser una persona, empresa, organización, etc.

email
cadena
(opcional)		 Dirección de correo electrónico del autor.
url
cadena
(opcional)		 URL pública donde se puede acceder a información sobre el autor.

API de Firebase y Google Cloud

Estos campos especifican las API de Firebase y Google que utiliza la extensión. Cuando los usuarios instalan la extensión, pueden optar por habilitar automáticamente estas API en su proyecto.

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
Campos API
apiName
cadena
(requerido)

Nombre de la API de Google

Debe corresponder al campo Nombre del servicio tal como se indica en la página de descripción general de cada API ( ejemplo ) en la biblioteca de API de Google Cloud.

reason
cadena
(requerido)		 Breve descripción de por qué la extensión necesita utilizar esta API

Funciones de IAM

Estos campos especifican las funciones de Cloud IAM que requiere la extensión. A la cuenta de servicio aprovisionada para la extensión se le otorgan estas funciones.

Sólo puede especificar uno de los roles admitidos .

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
Campos de rol
role
cadena
(requerido)

Nombre del rol de IAM necesario para que funcione la extensión

Debe ser uno de los roles admitidos.

reason
cadena
(requerido)		 Breve descripción de por qué la extensión necesita el acceso otorgado por este rol
resource
cadena
(opcional)

Limite el alcance del rol a este recurso.

Si se omite, el valor predeterminado es projects/${project_id} . Consulte Reducir el alcance de los roles .

Servicios externos

Estos campos especifican los servicios que no son de Firebase ni de Google que utiliza la extensión (normalmente API REST). La plataforma Firebase Extensions no proporciona ningún medio para habilitar o realizar autorización automáticamente para estos servicios.

externalServices:
  - name: Example API
    pricingUri: https://developers.example.com/pricing
  - name: Another Example API
    pricingUri: https://developers.example.com/pricing
Campos de servicios externos
name
cadena
(requerido)		 Nombre del servicio externo necesario para que funcione la extensión
pricingUri
cadena
(requerido)		 URI a la información de precios del servicio.

Parámetros configurables por el usuario

Estos campos definen los parámetros que la extensión pone a disposición de los usuarios para que los configuren.

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
Campos de parámetros
param
cadena
(requerido)		 Nombre del parámetro. Utilice este nombre para hacer referencia al valor del parámetro en el código.
label
cadena
(requerido)		 Breve descripción del parámetro. Se muestra al usuario cuando se le solicita el valor del parámetro.
description
cadena
(opcional)

Descripción detallada del parámetro. Se muestra al usuario cuando se le solicita el valor del parámetro.

Admite rebajas.

example
cadena
(opcional)		 Valor de ejemplo para el parámetro.
default
cadena
(opcional)		 Valor predeterminado para el parámetro si el usuario deja el valor del parámetro en blanco.
validationRegex
cadena
(opcional)		 Expresión regular para la validación del valor configurado por el usuario del parámetro. Sintaxis de Google RE2 .
validationErrorMessage
cadena
(opcional)		 Mensaje de error que se mostrará si falla la validación de expresiones regulares.
required
booleano
(opcional)		 Define si el usuario puede enviar una cadena vacía cuando se le solicita el valor del parámetro. El valor predeterminado es true .
immutable
booleano
(opcional)

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

Nota: Si define un parámetro de "ubicación" para las funciones implementadas de su extensión, establezca este campo en true .

type
cadena
(opcional)		 El tipo de parámetro. Los tipos de parámetros especiales pueden tener requisitos adicionales o una presentación de interfaz de usuario diferente. Consulte las siguientes secciones.

Parámetros seleccionables y multiseleccionables.

Los parámetros seleccionables y multiseleccionables solicitan a los usuarios que elijan de una lista de opciones predefinidas.

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
Campos de parámetros de opción múltiple
type
cadena

select o multiselect

Especifica que el parámetro puede ser un valor ( select ) o varios valores ( multiselect ) seleccionados de un conjunto de opciones predefinidas

options
lista de opciones
(requerido)

Las opciones entre las que el usuario puede elegir

Campos de opción
value
cadena
(requerido)		 Uno de los valores que el usuario puede elegir. Este es el valor que obtienes cuando lees el valor del parámetro en el código.
label
cadena
(opcional)		 Breve descripción de la opción seleccionable. Si se omite, el valor predeterminado es value .

Parámetros de recursos seleccionables

Los parámetros de recursos seleccionables solicitan a los usuarios que seleccionen un recurso (instancia de base de datos, depósito de almacenamiento, etc.) de su proyecto.

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
Campos de parámetros de recursos
type
cadena

selectresource

Especifica que el parámetro representa un recurso del proyecto.

resourceType
cadena
(requerido)

El tipo de recurso que se solicitará al usuario que seleccione.

Valores válidos:

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

Sin embargo, actualmente solo los depósitos de Cloud Storage tienen una interfaz de usuario de selección (otros tipos de recursos se presentan como campos de entrada de texto de formato libre).

Parámetros secretos

Los valores secretos proporcionados por el usuario (como las claves API) se manejan de manera diferente:

  • Los valores secretos se almacenan mediante Cloud Secret Manager. Sólo los clientes autorizados (como una instancia instalada de una extensión) pueden acceder a estos valores.
  • Cuando se solicita a los usuarios que proporcionen estos valores, su entrada no se muestra.
params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What is the secret value?
    type: secret
Campos de parámetros secretos
type
cadena

secret

Especifica que el parámetro es un valor secreto.

Recursos de funciones en la nube

Estos campos declaran las Cloud Functions incluidas en una extensión. La sintaxis de declaración de recursos se ve un poco diferente entre las funciones de primera y segunda generación, que pueden coexistir en una extensión.

Funciones de nube de primera generación

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
Campos de recursos
name
cadena
(requerido)

Nombre fácil de usar para la función exportada.

Si no especifica la propiedad entryPoint (ver más abajo), este valor debe coincidir con el nombre de la función en el código fuente de sus funciones.

El nombre final de la función implementada tendrá el siguiente formato: ext- extension-instance-id - name .

type
cadena
(requerido)		 Para un recurso de función de primera generación: firebaseextensions.v1beta.function
description
cadena
(requerido)

Breve descripción de qué tarea realiza la función para la extensión.

properties
(requerido)

Propiedades de Cloud Functions de primera generación. Las propiedades más importantes se enumeran a continuación, pero puede encontrar la lista completa en la referencia de Cloud Functions .

Propiedades
location
(opcional)

Ubicación en la que implementar la función. El valor predeterminado es us-central1

entryPoint
(opcional)		 Nombre de la función exportada dentro del código fuente de sus funciones que la extensión debe buscar. El valor predeterminado es el valor de name , arriba.
sourceDirectory
(opcional)

Directorio que contiene su package.json en su raíz. El archivo del código fuente de sus funciones debe estar en este directorio. Valores predeterminados de functions

Nota: El campo main de package.json especifica el archivo para el código fuente de sus funciones (como index.js ).

timeout
(opcional)

El tiempo máximo de ejecución de la función.

  • Predeterminado: 60s
  • Valor máximo: 540s
availableMemoryMb
(opcional)

Cantidad de memoria en MB disponible para la función.

  • Predeterminado: 256
  • Valores válidos: 128 , 256 , 512 , 1024 y 2048
runtime
(recomendado)

Entorno de ejecución de la función.

httpsTrigger
o
eventTrigger
o
scheduleTrigger
o
taskQueueTrigger
(Se requiere uno de estos tipos de activación de función)		 Consulte Escribir funciones en la nube para obtener una extensión para obtener información específica sobre cada tipo de activador.

Funciones de nube de segunda generación

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
Campos de recursos
name
cadena
(requerido)

Nombre fácil de usar para la función exportada.

Si no especifica la propiedad entryPoint (ver más abajo), este valor debe coincidir con el nombre de la función en el código fuente de sus funciones.

El nombre final de la función implementada tendrá el siguiente formato: ext- extension-instance-id - name .

type
cadena
(requerido)		 Para un recurso de función de segunda generación: firebaseextensions.v1beta.v2function
description
cadena
(requerido)

Breve descripción de qué tarea realiza la función para la extensión.

properties
(requerido)

Propiedades de Cloud Functions de segunda generación. Las propiedades más importantes se enumeran a continuación, pero puede encontrar la lista completa en la referencia de Cloud Functions .

Propiedades
location
(opcional)

Ubicación en la que implementar la función. El valor predeterminado es us-central1

sourceDirectory
(opcional)

Directorio que contiene su package.json en su raíz. El archivo del código fuente de sus funciones debe estar en este directorio. Valores predeterminados de functions

Nota: El campo main de package.json especifica el archivo para el código fuente de sus funciones (como index.js ).

También hay tres campos de tipo objeto con sus propias propiedades:

propiedades de configuración de compilación
buildConfig.runtime
(recomendado)

Entorno de ejecución de la función.

buildConfig.entryPoint
(opcional)		 Nombre de la función exportada dentro del código fuente de sus funciones que la extensión debe buscar. El valor predeterminado es el valor de name , arriba.
propiedades de configuración de servicio
serviceConfig.timeoutSeconds
(opcional)

El tiempo máximo de ejecución de la función.

  • Predeterminado: 60
  • Valor máximo: 540
serviceConfig.availableMemory
(opcional)		 La cantidad de memoria disponible para una función. El valor predeterminado es 256M . Las unidades admitidas son k , M , G , Mi , Gi . Si no se proporciona ninguna unidad, el valor se interpreta como bytes.
propiedades de eventTrigger
eventTrigger.eventType
(requerido)		 El tipo de evento a escuchar. Consulte Write Cloud Functions para obtener una extensión de los tipos de eventos disponibles para cada producto.
eventTrigger.eventFilters
(opcional)		 Filtros que limitan aún más los eventos a escuchar. Por ejemplo, solo podría escuchar eventos que coincidan con un patrón de recurso específico. Consulte Write Cloud Functions para obtener una extensión y obtener información sobre cómo filtrar cada tipo de evento.
eventTrigger.channel
(opcional)		 El nombre del canal asociado con el activador en formato projects/{project}/locations/{location}/channels/{channel} . Si omite esta propiedad, la función escuchará eventos en el canal predeterminado del proyecto.
eventTrigger.triggerRegion
(opcional)		 El activador solo recibirá eventos que se originen en esta región. Puede ser la misma región que la función, una región o multirregión diferente o la región global. Si no se proporciona, el valor predeterminado es la misma región que la función.

Eventos del ciclo de vida

Los eventos del ciclo de vida le permiten especificar funciones que se ejecutarán cuando un usuario instale, actualice o configure una instancia de su extensión. Consulte Manejar los eventos del ciclo de vida de su extensión .

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
Campos de eventos del ciclo de vida
onInstall
(opcional)

Especifica una función que se ejecuta cuando un usuario instala la extensión.

Especificación de función
function
cadena
(requerido)

Nombre de la función activada por la cola de tareas que controlará el evento.

Esta función debe estar declarada en la sección resources y tener taskQueue definido.

processingMessage
cadena
(requerido)		 Mensaje que se mostrará en Firebase console mientras la tarea está en progreso.
onUpdate
(opcional)

Especifica una función que se ejecuta cuando un usuario actualiza la extensión.

Especificación de función
function
cadena
(requerido)

Nombre de la función activada por la cola de tareas que controlará el evento.

Esta función debe estar declarada en la sección resources y tener taskQueue definido.

processingMessage
cadena
(requerido)		 Mensaje que se mostrará en Firebase console mientras la tarea está en progreso.
onConfigure
(opcional)

Especifica una función que se ejecuta cuando un usuario reconfigura la extensión.

Especificación de función
function
cadena
(requerido)

Nombre de la función activada por la cola de tareas que controlará el evento.

Esta función debe estar declarada en la sección resources y tener taskQueue definido.

processingMessage
cadena
(requerido)		 Mensaje que se mostrará en Firebase console mientras la tarea está en progreso.

Eventos personalizados (Eventarc)

Los eventos personalizados son eventos que su extensión emite para permitir a los usuarios insertar su propia lógica en su extensión. Consulte la sección Eventarc en Agregar enlaces de usuario a una extensión .

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
Campos de eventos personalizados
type
cadena
(requerido)		 El identificador de tipo del evento. Construya el identificador a partir de 3 o 4 campos delimitados por puntos: los campos de ID del editor, nombre de la extensión y nombre del evento son obligatorios; Se recomienda el campo de versión. Elija un nombre de evento único y descriptivo para cada tipo de evento que publique.
description
cadena
(requerido)		 Descripción del evento.