Fique por dentro dos destaques do Firebase no Google I/O 2023. Saiba mais

Referência de extension.yaml

O arquivo de especificação da extensão (extension.yaml) contém os metadados dela, declara os recursos criados pela extensão e as APIs e o acesso exigido pela extensão e define os parâmetros configurados pelo usuário fornecidos pela extensão.

Confira nas tabelas desta página a descrição dos campos disponíveis para um arquivo extension.yaml.

Informações básicas e de identificação

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
string
(obrigatório)

Identificador da extensão.

Só pode conter letras minúsculas, números e traços. Limite de 40 caracteres.

Observação: esse valor é usado para gerar o ID da instância da extensão (que é usado para gerar os nomes da conta de serviço da extensão e dos recursos específicos dela).

version
string
(obrigatório)

Versão da extensão.

Precisa seguir o controle de versão semver (por exemplo, 1.2.0).

specVersion
string
(obrigatório)

Versão da especificação das Extensões do Firebase.

Valor atual: v1beta

license
string
(opcional)

Licença da extensão.

Sua extensão precisa ser licenciada usando Apache-2.0.

billingRequired
booleano
(opcional)

Se os serviços usados pela extensão exigem uma conta de faturamento do nível pago do Firebase.

Sempre defina como true.

displayName
string
(opcional)

Nome de exibição compatível com a extensão (de 3 a 5 palavras).

Limite de 40 caracteres.

description
string
(opcional) Breve descrição da tarefa que sua extensão realiza (aproximadamente uma frase).

icon
string
(opcional)

Arquivo a ser usado como o ícone da extensão no extensions.dev e no Console do Firebase.

Esse arquivo precisa ser um PNG quadrado entre 512 x 512 e 1024 x 1024 pixels. Coloque o arquivo no mesmo diretório que extension.yaml. Não é possível especificar um subdiretório.

Lembre-se das seguintes diretrizes ao criar um ícone para sua extensão:

Selecione as cores do plano de fundo e da arte gráfica adequadas para sua marca.
Mantenha as cores do ícone simples, usando apenas duas cores. Usar mais de uma cor pode deixar o ícone visualmente atraente.
Pelo mesmo motivo, não use gradientes no seu ícone. Os gradientes são difíceis de distinguir em tamanhos pequenos e tornam o ícone visualmente complexo.
Use imagens simples e exclusivas que comunicam a funcionalidade da sua extensão.
Se sua empresa cria várias extensões, não use o logotipo como ícone. Os usuários terão dificuldade para distinguir entre suas extensões.
Deixe a arte gráfica e em negrito. Não use arte delicada ou elaborada, que não será bem renderizada em tamanhos menores.
Não inclua palavras que expliquem o que sua extensão faz. Geralmente, não é possível ler o texto em tamanhos menores.

tags
lista de strings
(opcional) Tags para ajudar os usuários a descobrir sua extensão. As seguintes tags são associadas a categorias no Hub de extensões: marketing, messaging, payments, search, shipping, social, utilities e ai

sourceUrl
string
(opcional) URL público em que o diretório de extensão pode ser acessado.

releaseNotesUrl
string
(opcional) URL público em que as notas da versão da extensão podem ser acessadas.

author
um objeto de autor
(opcional)

Autor principal e ponto de contato da extensão.

author:
  authorName: Your Company
  email: extensions@example.com
  url: https://example.com/

Campos de autor

authorName
string
(obrigatório)

Nome do autor.

Pode ser uma pessoa, empresa, organização etc.

email
string
(opcional) O endereço de e-mail do autor.

url
string
(opcional) URL público onde as informações sobre o autor podem ser acessadas.

contributors
lista de objetos de autor
(opcional)

Quaisquer autores colaboradores adicionais para a extensão.

contributors:
  - authorName: Your Name
  - authorName: Another Contributor
    email: colleague@example.net
    url: https://github.com/their-org/

Campos de autor

authorName
string
(obrigatório)

Nome do autor.

Pode ser uma pessoa, empresa, organização etc.

email
string
(opcional) O endereço de e-mail do autor.

url
string
(opcional) URL público onde as informações sobre o autor podem ser acessadas.

APIs do Firebase e do Google Cloud

Esses campos especificam as APIs do Firebase e do Google que a extensão usa. Quando os usuários instalam a extensão, eles podem ativar automaticamente essas APIs no projeto.

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 da API
`apiName` string (obrigatório)	Nome da API do Google Precisa corresponder ao campo Nome do serviço conforme listado na página de visão geral de cada API (exemplo) na Biblioteca de APIs do Google Cloud
`reason` string (obrigatório)	Breve descrição do motivo pelo qual a extensão precisa usar essa API

Campos da API

apiName
string
(obrigatório)

Nome da API do Google

Precisa corresponder ao campo Nome do serviço conforme listado na página de visão geral de cada API (exemplo) na Biblioteca de APIs do Google Cloud

reason
string
(obrigatório) Breve descrição do motivo pelo qual a extensão precisa usar essa API

Papéis do IAM

Esses campos especificam os papéis do Cloud IAM exigidos pela extensão. A conta de serviço provisionada para a extensão recebe esses papéis.

Só é possível especificar um dos papéis compatíveis.

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 da função
`role` string (obrigatório)	Nome do papel do IAM exigido pela extensão para funcionar Precisa ser um dos papéis compatíveis.
`reason` string (obrigatório)	Breve descrição do motivo pelo qual a extensão precisa do acesso concedido por essa função
`resource` string (opcional)	Limite o escopo do papel a este recurso. Se omitido, o padrão é `projects/${project_id}`. Consulte Reduzir o escopo dos papéis.

Campos da função

role
string
(obrigatório)

Nome do papel do IAM exigido pela extensão para funcionar

Precisa ser um dos papéis compatíveis.

reason
string
(obrigatório) Breve descrição do motivo pelo qual a extensão precisa do acesso concedido por essa função

resource
string
(opcional)

Limite o escopo do papel a este recurso.

Se omitido, o padrão é projects/${project_id}. Consulte Reduzir o escopo dos papéis.

Serviços externos

Esses campos especificam os serviços que não são do Firebase e do Google usados pela extensão (geralmente APIs REST). A plataforma Extensões do Firebase não fornece meios de ativar ou executar automaticamente a autorização para esses serviços.

externalServices:
  - name: Example API
    pricingUri: https://developers.example.com/pricing
  - name: Another Example API
    pricingUri: https://developers.example.com/pricing

Campos de serviços externos
`name` string (obrigatório)	Nome do serviço externo necessário para a extensão funcionar
`pricingUri` string (obrigatório)	URI para informações sobre preços do serviço

Parâmetros configuráveis pelo usuário

Esses campos definem os parâmetros que a extensão disponibiliza para os usuários configurarem.

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âmetro
`param` string (obrigatório)	Nome do parâmetro. Use esse nome para fazer referência ao valor do parâmetro no código.
`label` string (obrigatório)	Breve descrição do parâmetro. Exibida ao usuário quando for solicitado o valor do parâmetro.
`description` string (opcional)	Descrição detalhada do parâmetro. Exibida ao usuário quando o valor do parâmetro for solicitado. Compatível com a marcação.
`example` string (opcional)	Exemplo de valor para o parâmetro.
`default` string (opcional)	Valor padrão do parâmetro se o usuário deixar o valor do parâmetro em branco.
`validationRegex` string (opcional)	Expressão regular para validação do valor configurado pelo usuário do parâmetro. Sintaxe do Google RE2.
`validationErrorMessage` string (opcional)	Mensagem de erro a ser exibida se a validação da regex falhar.
`required` booleano (opcional)	Define se o usuário pode enviar uma string vazia quando o valor do parâmetro for solicitado. O valor padrão é `true`.
`immutable` booleano (opcional)	Define se o usuário pode alterar o valor do parâmetro após a instalação (por exemplo, se ele reconfigurar a extensão). O padrão é `false`. Observação: se você definir um parâmetro "location" para as funções implantadas da extensão, defina esse campo como `true`.
`type` string (opcional)	Tipo de parâmetro. Tipos de parâmetros especiais podem ter requisitos adicionais ou diferentes apresentações de IU. Consulte as seções a seguir para saber como fazer isso.

Parâmetros selecionáveis e multiselecionáveis

Os parâmetros selecionáveis e de seleção múltipla solicitam que os usuários escolham de uma lista de opções 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âmetro de múltipla escolha

type
string

select ou multiselect

Especifica que o parâmetro pode ser um valor (select) ou vários valores (multiselect) selecionados de um conjunto de opções predefinidas

options
lista de opções
(obrigatório)

As opções que o usuário pode escolher

Campos de opção
`value` string (obrigatório)	Um dos valores que o usuário pode escolher. Esse é o valor recebido quando você lê o valor do parâmetro no código.
`label` string (opcional)	Breve descrição da opção selecionável. Se omitido, o padrão é `value`.

Parâmetros de recursos selecionáveis

Os parâmetros de recursos selecionáveis solicitam que os usuários selecionem um recurso (instância de banco de dados, bucket de armazenamento etc.) do projeto.

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` string	`selectresource` Especifica que o parâmetro representa um recurso do projeto
`resourceType` string (obrigatório)	O tipo de recurso a ser solicitado pelo usuário para selecionar. Valores válidos: `storage.googleapis.com/Bucket` `firestore.googleapis.com/Database` `firebasedatabase.googleapis.com/DatabaseInstance` No entanto, somente os buckets do Cloud Storage atualmente têm uma IU de seleção. Outros tipos de recursos são apresentados como campos de entrada de texto de formato livre.

Campos de parâmetros de recursos

type
string

selectresource

Especifica que o parâmetro representa um recurso do projeto

resourceType
string
(obrigatório)

O tipo de recurso a ser solicitado pelo usuário para selecionar.

Valores válidos:

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

No entanto, somente os buckets do Cloud Storage atualmente têm uma IU de seleção. Outros tipos de recursos são apresentados como campos de entrada de texto de formato livre.

Parâmetros do secret

Os valores secretos fornecidos pelo usuário (como chaves de API) são tratados de forma diferente:

Os valores do secret são armazenados usando o Cloud Secret Manager. Somente clientes autorizados, como uma instância instalada de uma extensão, podem acessar esses valores.
Quando os usuários são solicitados a fornecer esses valores, a entrada deles não é exibida.

params:
  - param: PARAM_ID
    label: Short description of the parameter
    description: >-
      What is the secret value?
    type: secret

Campos de parâmetro secreto
`type` string	`secret` Especifica que o parâmetro é um valor secreto

Campos de parâmetro secreto

type
string

secret

Especifica que o parâmetro é um valor secreto

Recursos da função do Cloud

Esses campos declaram o Cloud Functions incluído em uma extensão. A sintaxe da declaração de recursos é um pouco diferente entre as funções de 1ª e 2ª geração, que podem coexistir em uma extensão.

Cloud Functions da 1ª geração

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
string
(obrigatório)

Nome simples para a função exportada.

Se você não especificar o campo entryPoint (confira abaixo), esse valor precisará corresponder ao nome da função no código-fonte das funções.

O nome final da função implantada estará no seguinte formato: ext-extension-instance-id-name.

type
string
(obrigatório) Para um recurso de função de 1ª geração: firebaseextensions.v1beta.function

description
string
(obrigatório)

Breve descrição da tarefa que a função executa para a extensão.

properties
(obrigatório)

Propriedades do Cloud Functions de 1ª geração. As propriedades mais importantes estão listadas abaixo, mas você pode encontrar a lista completa na referência do Cloud Functions.

Propriedades
`location` (opcional)	Local em que a função será implantada. O padrão é `us-central1`.
`entryPoint` (opcional)	Nome da função exportada no código-fonte das funções que a extensão deve procurar. O padrão é o valor de `name` acima.
`sourceDirectory` (opcional)	Diretório que contém o `package.json` na raiz. O arquivo do código-fonte das funções precisa estar nesse diretório. O padrão é `functions` Observação: o campo `main` de `package.json` especifica o arquivo para o código-fonte das funções (como `index.js`).
`timeout` (opcional)	O tempo máximo de execução da função. Padrão: `60s` Valor máximo: `540s`
`availableMemoryMb` (opcional)	Quantidade de memória em MB disponível para a função. Padrão: `256` Valores válidos: `128`, `256`, `512`, `1024` e `2048`
`runtime` (recomendado)	Ambiente de execução da função. Assume o padrão da versão mais recente do Node.js atualmente compatível com o Cloud Functions. Valores válidos: `nodejs14`, `nodejs16`, `nodejs18`
`httpsTrigger` ou `eventTrigger` ou `scheduleTrigger` ou `taskQueueTrigger` (um desses tipos de acionador de função é obrigatório)	Consulte Gravar o Cloud Functions para uma extensão para informações específicas sobre cada tipo de acionador.

Cloud Functions de 2ª geração

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
string
(obrigatório)

Nome simples para a função exportada.

Se você não especificar o campo entryPoint (confira abaixo), esse valor precisará corresponder ao nome da função no código-fonte das funções.

O nome final da função implantada estará no seguinte formato: ext-extension-instance-id-name.

type
string
(obrigatório) Para um recurso de função de 2ª geração: firebaseextensions.v1beta.v2function

description
string
(obrigatório)

Breve descrição da tarefa que a função executa para a extensão.

properties
(obrigatório)

Propriedades do Cloud Functions de 2ª geração. As propriedades mais importantes estão listadas abaixo, mas você pode encontrar a lista completa na referência do Cloud Functions.

Propriedades

location
(opcional)

Local em que a função será implantada. O padrão é us-central1.

sourceDirectory
(opcional)

Diretório que contém o package.json na raiz. O arquivo do código-fonte das funções precisa estar nesse diretório. O padrão é functions

Observação: o campo main de package.json especifica o arquivo para o código-fonte das funções (como index.js).

Há também três campos de tipo de objeto com as próprias propriedades:

Propriedades de buildConfig

buildConfig.runtime
(recomendado)

Ambiente de execução da função.

Assume o padrão da versão mais recente do Node.js atualmente compatível com o Cloud Functions.
Valores válidos: nodejs14, nodejs16, nodejs18

buildConfig.entryPoint
(opcional) Nome da função exportada no código-fonte das funções que a extensão deve procurar. O padrão é o valor de name acima.

Propriedades de serviceConfig

serviceConfig.timeoutSeconds
(opcional)

O tempo máximo de execução da função.

Padrão: 60
Valor máximo: 540

serviceConfig.availableMemory
(opcional) A quantidade de memória disponível para uma função. O padrão é 256M. As unidades aceitas são k, M, G, Mi e Gi. Se nenhuma unidade for fornecida, o valor será interpretado como bytes.

Propriedades de eventTrigger
`eventTrigger.eventType` (obrigatório)	O tipo de evento a ser detectado. Consulte Gravar funções do Cloud em uma extensão para conferir os tipos de eventos disponíveis para cada produto.
`eventTrigger.eventFilters` (opcional)	Filtros que limitam ainda mais os eventos a serem detectados. Por exemplo, só é possível detectar eventos que correspondam a um padrão de recurso específico. Consulte Gravar funções do Cloud em uma extensão para informações sobre como filtrar cada tipo de evento.
`eventTrigger.channel` (opcional)	O nome do canal associado ao acionador no formato `projects/{project}/locations/{location}/channels/{channel}`. Se você omitir essa propriedade, a função detectará eventos no canal padrão do projeto.
`eventTrigger.triggerRegion` (opcional)	O acionador só receberá eventos originados nesta região. Pode ser a mesma região da função, uma região ou multirregião diferente ou a região global. Se não for fornecido, o padrão será a mesma região da função.

Eventos de ciclo de vida

Os eventos de ciclo de vida permitem especificar funções que serão executadas quando um usuário instalar, atualizar ou configurar uma instância da sua extensão. Consulte Gerenciar os eventos de ciclo de vida da extensão.

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 evento do ciclo de vida

onInstall
(opcional)

Especifica uma função que é executada quando um usuário instala a extensão.

Especificação da função

function
string
(obrigatório)

Nome da função acionada pela fila de tarefas que manipulará o evento.

Essa função precisa ser declarada na seção resources e ter a taskQueue definida.

processingMessage
string
(obrigatório) Mensagem a ser exibida no Console do Firebase enquanto a tarefa está em andamento.

onUpdate
(opcional)

Especifica uma função que é executada quando um usuário atualiza a extensão.

Especificação da função

function
string
(obrigatório)

Nome da função acionada pela fila de tarefas que manipulará o evento.

Essa função precisa ser declarada na seção resources e ter a taskQueue definida.

processingMessage
string
(obrigatório) Mensagem a ser exibida no Console do Firebase enquanto a tarefa está em andamento.

onConfigure
(opcional)

Especifica uma função que é executada quando um usuário reconfigura a extensão.

Especificação da função

function
string
(obrigatório)

Nome da função acionada pela fila de tarefas que manipulará o evento.

Essa função precisa ser declarada na seção resources e ter a taskQueue definida.

processingMessage
string
(obrigatório) Mensagem a ser exibida no Console do Firebase enquanto a tarefa está em andamento.

Eventos personalizados (Eventarc)

Eventos personalizados são emitidos pela sua extensão para permitir que os usuários insiram sua própria lógica na extensão. Consulte a seção do Eventarc em Adicionar hooks de usuário a uma extensão.

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` string (obrigatório)	O identificador de tipo do evento. Crie o identificador com três ou quatro campos delimitados por pontos: os campos "ID do editor", "nome da extensão" e "nome do evento" são obrigatórios. o campo de versão é recomendado. Escolha um nome de evento exclusivo e descritivo para cada tipo de evento publicado.
`description` string (obrigatório)	Descrição do evento.