Referencia de extension.yaml

El archivo de especificación de tu extensión (extension.yaml) contiene los metadatos de tu extensión, declara los recursos que creó la extensión y las APIs, así como el acceso que requiere la extensión, y define cualquier parámetro configurado por el usuario que proporcionó la extensión.

En las tablas de esta página, se describen los campos disponibles para un archivo extension.yaml.

Información básica y de identificación

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
(obligatoria)

Es el identificador de la extensión.

Solo puede contener letras minúsculas, números y guiones. Tiene un 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 y los recursos específicos de la extensión).

version
cadena
(obligatoria)

Es la versión de la extensión.

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

Es la versión de la especificación de Extensiones de Firebase.

Valor actual: v1beta
license
cadena
(opcional)

Es la licencia de la extensión.

Tu extensión debe tener una licencia Apache-2.0.
billingRequired
booleano
(opcional)

Indica si los servicios que usa la extensión requieren una cuenta de facturación de Firebase de nivel de pago.

Siempre se establece en true.
displayName
cadena
(opcional)

Es el nombre visible y descriptivo de la extensión (de 3 a 5 palabras).

Tiene un límite de 40 caracteres.
description
cadena
(opcional) 		Es una descripción breve de la tarea que realiza tu extensión (aprox. 1 oración).
icon
cadena
(opcional)

Es un archivo que se usa como ícono de la extensión en extensions.dev y Firebase console.

Debe ser un archivo PNG cuadrado de entre 512 × 512 y 1,024 × 1,024 píxeles. Colócalo en el mismo directorio que extension.yaml. No puedes especificar un subdirectorio.

Ten en cuenta los siguientes lineamientos cuando diseñes un ícono para tu extensión:

  • Selecciona los colores de fondo y de material gráfico que sean adecuados para tu marca.
  • Usa colores simples para tus íconos, con solo 2 colores. Usar varios colores puede hacer sobrecargar el aspecto del ícono.
  • Por el mismo motivo, no uses gradientes. Los gradientes son difíciles de distinguir en tamaños pequeños y aumentan la complejidad visual del ícono.
  • Usa imágenes simples y únicas que comuniquen la funcionalidad de la extensión.
  • Si tu empresa crea varias extensiones, no uses tu logotipo como ícono, ya que los usuarios tendrán dificultades para distinguir entre ellas.
  • Haz que el material gráfico sea distinguible. No uses imágenes complejas ni difíciles de reconocer, ya que no se renderizarán bien en tamaños más pequeños.
  • No incluyas palabras que expliquen lo que hace tu extensión. El texto suele ser ilegible en tamaños más pequeños.
tags
lista de cadenas
(opcional) 		Son etiquetas para ayudar a los usuarios a descubrir tu extensión. Las siguientes etiquetas se asignan a las categorías en Extension Hub: marketing, messaging, payments, search, shipping, social, utilities y ai.
sourceUrl
cadena
(opcional) 		Es una URL pública con la que se puede acceder al directorio de la extensión.
releaseNotesUrl
cadena
(opcional) 		Es una URL pública con la que se puede acceder a las notas de la versión de la extensión.
author
un objeto de autor
(opcional)

Es el autor principal y el punto de contacto de la extensión.

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

Es el nombre del autor.

Puede ser una persona, una empresa, una organización, etcétera.
email
cadena
(opcional) 		Es la dirección de correo electrónico del autor.
url
cadena
(opcional) 		Es una URL pública con la que se puede acceder a la información del autor.
contributors
lista de objetos de autor
(opcional)

Incluye cualquier otro autor que contribuya a 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
(obligatoria)

Es el nombre del autor.

Puede ser una persona, una empresa, una organización, etcétera.
email
cadena
(opcional) 		Es la dirección de correo electrónico del autor.
url
cadena
(opcional) 		Es una URL pública con la que se puede acceder a la información del autor.

APIs de Firebase y Google Cloud

Estos campos especifican las APIs de Firebase y Google que usa la extensión. Cuando los usuarios instalan la extensión, pueden habilitar automáticamente estas APIs en tu 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 de la API
apiName
cadena
(obligatoria)

Nombre de la API de Google

Debe corresponder al campo Nombre del servicio que aparece en la página de descripción general de cada API (ejemplo) en la Biblioteca de APIs de Google Cloud.

reason
cadena
(obligatoria) 		Es una descripción breve de por qué la extensión debe usar esta API.

Roles de IAM

Estos campos especifican los roles de Cloud IAM que requiere la extensión. La cuenta de servicio aprovisionada para la extensión recibe estos roles.

Solo puedes 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 roles
role
cadena
(obligatoria)

Es el nombre del rol de IAM que necesita la extensión para funcionar

Debe ser uno de los roles admitidos.

reason
cadena
(obligatoria) 		Es una descripción breve de por qué la extensión necesita el acceso que otorga este rol.
resource
cadena
(opcional)

Limita el permiso del rol a este recurso.

Si se omite, el valor predeterminado es projects/${project_id}. Consulta Reduce el permiso de los roles.

Servicios externos

Estos campos especifican los servicios que no son de Firebase ni de Google que usa la extensión (por lo general, las APIs de REST). La plataforma de Extensiones de Firebase no proporciona ningún medio para habilitar o realizar la 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
(obligatoria) 		Es el nombre del servicio externo necesario para que la extensión funcione.
pricingUri
cadena
(obligatoria) 		Es el URI de 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 su configuración.

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 del parámetro
param
cadena
(obligatoria) 		Es el nombre del parámetro. Úsalo para hacer referencia al valor del parámetro en el código.
label
cadena
(obligatoria) 		Es una descripción breve del parámetro. Se muestra al usuario cuando se le solicita el valor del parámetro.
description
cadena
(opcional)

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

Admite Markdown.
example
cadena
(opcional) 		Es un valor de ejemplo para el parámetro.
default
cadena
(opcional) 		Es el valor predeterminado del parámetro si el usuario lo deja en blanco.
validationRegex
cadena
(opcional) 		Es una expresión regular para validar el valor configurado por el usuario del parámetro. Usa la sintaxis RE2 de Google.
validationErrorMessage
cadena
(opcional) 		Es un mensaje de error para mostrar si falla la validación de la regex.
required
booleano
(opcional) 		Define si el usuario puede enviar una cadena vacía cuando se le solicita el valor del parámetro. La configuración predeterminada 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). La configuración predeterminada es false.

Nota: Si defines un parámetro de “ubicación” para las funciones implementadas de tu extensión, establece este campo en true.
type
cadena
(opcional) 		Es el tipo de parámetro. Los tipos de parámetros especiales pueden tener requisitos adicionales o una presentación de IU diferente. Consulta las siguientes secciones.

Parámetros seleccionables y multiseleccionables

Los parámetros seleccionables y seleccionables permiten a los usuarios elegir 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
(obligatorio)

Son las opciones que puede elegir el usuario.

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

Parámetros de recursos seleccionables

Los parámetros de recursos seleccionables requieren que los usuarios seleccionen un recurso (instancia de base de datos, bucket 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 del parámetro de recurso
type
cadena

selectresource

Especifica que el parámetro representa un recurso del proyecto.
resourceType
cadena
(obligatoria)

Es el tipo de recurso que se le pide seleccionar al usuario.

Valores válidos:

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

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

Parámetros secretos

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

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

secret

Especifica que el parámetro es un valor secreto

Recursos de Cloud Function

Estos campos declaran las funciones de Cloud Functions incluidas en una extensión. La sintaxis de la declaración de recursos se ve un poco diferente entre las funciones de 1ª y 2ª gen., que pueden coexistir en una extensión.

Cloud Functions de 1ª gen.

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
(obligatoria)

Es un nombre fácil de usar para la función exportada.

Si no especificas el campo entryPoint (consulta a continuación), este valor debe coincidir con el nombre de la función en el código fuente.

El nombre final de la función implementada tendrá el siguiente formato: ext-extension-instance-id-name.
type
cadena
(obligatoria) 		Para un recurso de función de 1ª gen.: firebaseextensions.v1beta.function
description
cadena
(obligatoria)

Es una descripción breve de la tarea que realiza la función para la extensión.
properties
(obligatorio)

Son propiedades de Cloud Functions de 1ª gen. Las más importantes se enumeran a continuación, pero puedes encontrar la lista completa en la referencia de Cloud Functions.

Propiedades
location
(opcional)

Es la ubicación donde se implementará la función. La configuración predeterminada es us-central1.
entryPoint
(opcional) 		Es el nombre de la función exportada dentro del código fuente de las funciones que debe buscar la extensión. El valor predeterminado es name, arriba.
sourceDirectory
(opcional)

Es el directorio que contiene tu package.json en su raíz. El archivo del código fuente de las funciones debe estar en este directorio. La configuración predeterminada es functions.

Nota: El campo main de package.json especifica el archivo del código fuente de tus funciones (como index.js).
timeout
(opcional)

Es el tiempo máximo de ejecución de la función.

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

Es la cantidad de memoria en MB disponible para la función.

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

Es el entorno de ejecución de la función.
httpsTrigger
o
eventTrigger
o
scheduleTrigger
o
taskQueueTrigger
(es obligatorio incluir uno de estos tipos de activadores de función) 		Consulta Escribe Cloud Functions para una extensión si necesitas información específica sobre cada tipo de activador.

Cloud Functions de 2ª 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
Campos de recursos
name
cadena
(obligatoria)

Es un nombre fácil de usar para la función exportada.

Si no especificas el campo entryPoint (consulta a continuación), este valor debe coincidir con el nombre de la función en el código fuente.

El nombre final de la función implementada tendrá el siguiente formato: ext-extension-instance-id-name.
type
cadena
(obligatoria) 		Para un recurso de función de 2ª gen.: firebaseextensions.v1beta.v2function
description
cadena
(obligatoria)

Es una descripción breve de la tarea que realiza la función para la extensión.
properties
(obligatorio)

Son propiedades de Cloud Functions de 2ª gen. Las más importantes se enumeran a continuación, pero puedes encontrar la lista completa en la referencia de Cloud Functions.

Propiedades
location
(opcional)

Es la ubicación donde se implementará la función. La configuración predeterminada es us-central1.
sourceDirectory
(opcional)

Es el directorio que contiene tu package.json en su raíz. El archivo del código fuente de las funciones debe estar en este directorio. La configuración predeterminada es functions.

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

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

buildConfig properties
buildConfig.runtime
(recomendado)

Es el entorno de ejecución de la función.
buildConfig.entryPoint
(opcional) 		Es el nombre de la función exportada dentro del código fuente de las funciones que debe buscar la extensión. El valor predeterminado es name, arriba.
serviceConfig properties
serviceConfig.timeoutSeconds
(opcional)

Es el tiempo máximo de ejecución de la función.

  • Valor predeterminado: 60
  • Valor máximo: 540
serviceConfig.availableMemory
(opcional) 		Es la cantidad de memoria disponible para una función. La configuración predeterminada es 256M. Las unidades admitidas son k, M, G, Mi y Gi. Si no se proporciona ninguna unidad, el valor se interpreta como bytes.
Propiedades de eventTrigger
eventTrigger.eventType
(obligatorio) 		Es el tipo de evento que se debe escuchar: Consulta Escribe Cloud Functions para una extensión si quieres conocer los tipos de eventos disponibles para cada producto.
eventTrigger.eventFilters
(opcional) 		Son filtros que limitan aún más los eventos que se escucharán. Por ejemplo, solo podrías escuchar eventos que coincidan con un patrón de recursos específico. Consulta Escribe Cloud Functions para una extensión si necesitas información para filtrar cada tipo de evento.
eventTrigger.channel
(opcional) 		Es el nombre del canal asociado al activador en formato projects/{project}/locations/{location}/channels/{channel}. Si omites esta propiedad, la función escuchará los 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 te permiten especificar funciones que se ejecutarán cuando un usuario instale, actualice o configure una instancia de tu extensión. Consulta la sección Controla los eventos del ciclo de vida de tu 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 la función
function
cadena
(obligatoria)

Es el nombre de la función activada por la lista de tareas en cola que controlará el evento.

Esta función debe declararse en la sección resources y tener definida una taskQueue.
processingMessage
cadena
(obligatoria) 		Es el mensaje que se mostrará en Firebase console mientras la tarea esté en curso.
onUpdate
(opcional)

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

Especificación de la función
function
cadena
(obligatoria)

Es el nombre de la función activada por la lista de tareas en cola que controlará el evento.

Esta función debe declararse en la sección resources y tener definida una taskQueue.
processingMessage
cadena
(obligatoria) 		Es el mensaje que se mostrará en Firebase console mientras la tarea esté en curso.
onConfigure
(opcional)

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

Especificación de la función
function
cadena
(obligatoria)

Es el nombre de la función activada por la lista de tareas en cola que controlará el evento.

Esta función debe declararse en la sección resources y tener definida una taskQueue.
processingMessage
cadena
(obligatoria) 		Es el mensaje que se mostrará en Firebase console mientras la tarea esté en curso.

Eventos personalizados (Eventarc)

Los eventos personalizados son aquellos que emite tu extensión para permitir que los usuarios inserten su propia lógica en ella. Consulta la sección de Eventarc en Agrega hooks 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 evento personalizados
type
cadena
(obligatoria) 		Es el identificador de tipo del evento. Crea el identificador a partir de 3 o 4 campos delimitados por puntos: los campos ID de publicador, nombre de la extensión y nombre del evento son obligatorios. Se recomienda el campo de versión. Elige un nombre de evento único y descriptivo para cada tipo de evento que publiques.
description
cadena
(obligatoria) 		Es la descripción del evento.