Gerenciar funções

Você pode implantar, excluir e modificar funções usando os comandos da CLI do Firebase ou definindo opções de ambiente de execução no código-fonte das suas funções.

Implantar funções

Para implantar funções, execute o seguinte comando da CLI do Firebase:

firebase deploy --only functions

Por padrão, a CLI do Firebase implanta todas as funções dentro da origem ao mesmo tempo. Se o projeto tiver mais de cinco funções, recomendamos que você use a sinalização --only com nomes de função específicos para implantar apenas as funções editadas. Implantar funções específicas dessa forma acelera o procedimento e ajuda a evitar alcançar o limite de cotas de implantação. Por exemplo:

firebase deploy --only functions:addMessage,functions:makeUppercase

Ao implantar um grande número de funções, talvez você exceda a cota padrão e receba mensagens de erro HTTP 429 ou 500. Para resolver esse problema, implante funções em grupos de 10 ou menos.

Consulte a referência da CLI do Firebase para conferir a lista completa de comandos disponíveis.

Por padrão, a CLI do Firebase procura o código-fonte na pasta functions/. Se preferir, organize funções em bases de código ou em vários conjuntos de arquivos.

Excluir funções

Funções implantadas previamente podem ser excluídas:

• explicitamente na CLI do Firebase com functions:delete
• explicitamente no console do Google Cloud.
• implicitamente, ao remover a função da origem antes da implantação.

Em todas as operações é necessário confirmar antes de remover a função da produção.

A exclusão explícita de funções na CLI do Firebase aceita vários argumentos, assim como grupos de funções, e permite especificar uma função executada em uma região específica. Além disso, você pode substituir o prompt de confirmação.

# Delete all functions that match the specified name in all regions.
firebase functions:delete myFunction

# Delete a specified function running in a specific region.
firebase functions:delete myFunction --region us-east-1

# Delete more than one function
firebase functions:delete myFunction myOtherFunction

# Delete a specified functions group.
firebase functions:delete groupA

# Bypass the confirmation prompt.
firebase functions:delete myFunction --force

Com a exclusão implícita de funções, firebase deploy analisa a origem e remove da produção todas as funções que foram removidas do arquivo.

Modificar o nome, a região ou o gatilho de uma função

Se você for renomear ou alterar a região ou o gatilho para funções que lidam com o tráfego de produção, siga as etapas desta seção a fim de evitar a perda de eventos durante a modificação. Antes de prosseguir, verifique se a função é idempotente, já que a versão antiga e a nova serão executadas simultaneamente durante a modificação.

Renomear uma função

Para renomear uma função, crie uma nova versão renomeada da função na origem e execute dois comandos de implantação separados. O primeiro comando implanta a função recém-nomeada e o segundo remove a versão implementada anteriormente. Por exemplo, se você tiver um webhook acionado por HTTP que queira renomear, revise o código da seguinte maneira:

// before
const {onRequest}  = require('firebase-functions/v2/https');

exports.webhook = onRequest((req, res) => {
    res.send("Hello");
});

// after
const {onRequest}  = require('firebase-functions/v2/https');

exports.webhookNew = onRequest((req, res) => {
    res.send("Hello");
});

# before
from firebase_functions import https_fn

@https_fn.on_request()
def webhook(req: https_fn.Request) -> https_fn.Response:
    return https_fn.Response("Hello world!")

# after
from firebase_functions import https_fn

@https_fn.on_request()
def webhook_new(req: https_fn.Request) -> https_fn.Response:
    return https_fn.Response("Hello world!")

Em seguida, execute os seguintes comandos para implantar a nova função:

# Deploy new function
firebase deploy --only functions:webhookNew

# Wait until deployment is done; now both functions are running

# Delete webhook
firebase functions:delete webhook

Alterar a região ou as regiões de uma função

Se você alterar as regiões especificadas de uma função que lida com tráfego de produção, é possível evitar a perda de eventos executando as etapas na ordem a seguir:

1. Renomeie a função e altere a região ou as regiões dela, conforme quiser.
2. Implante a função renomeada, o que resulta na execução temporária do mesmo código nos dois conjuntos de regiões.
3. Exclua a função anterior.

Por exemplo, se você tiver uma função acionada por Cloud Firestore que esteja atualmente na região de funções padrão de us-central1 e quiser migrá-la para asia-northeast1, primeiro será necessário modificar o código-fonte para renomear a função e revisar a região.

// before
exports.firestoreTrigger = onDocumentCreated(
  "my-collection/{docId}",
  (event) => {},
);

// after
exports.firestoreTriggerAsia = onDocumentCreated(
  {
    document: "my-collection/{docId}",
    region: "asia-northeast1",
  },
  (event) => {},
);

# Before
@firestore_fn.on_document_created("my-collection/{docId}")
def firestore_trigger(event):
    pass

# After
@firestore_fn.on_document_created("my-collection/{docId}",
                                  region="asia-northeast1")
def firestore_trigger_asia(event):
    pass

Em seguida, implante executando o comando:

firebase deploy --only functions:firestoreTriggerAsia

Agora, há duas funções idênticas em execução: firestoreTrigger está em execução em us-central1 e firestoreTriggerAsia está em execução em asia-northeast1.

Em seguida, exclua firestoreTrigger:

firebase functions:delete firestoreTrigger

Agora, apenas a função firestoreTriggerAsia está sendo executada em asia-northeast1.

Alterar o tipo de gatilho de uma função

À medida que você desenvolve sua implantação do Cloud Functions for Firebase ao longo do tempo, pode ser necessário alterar o tipo de gatilho de uma função por vários motivos. Por exemplo, é possível mudar de um tipo de evento Firebase Realtime Database ou Cloud Firestore para outro.

Não é possível alterar o tipo de evento de uma função apenas alterando o código-fonte e executando firebase deploy. Para evitar erros, altere o tipo de gatilho de uma função ao seguir este procedimento:

1. Modifique o código-fonte para incluir uma nova função com o tipo de gatilho desejado.
2. Implante a função, o que resulta na execução temporária da função antiga e da nova.
3. Exclua explicitamente a função antiga da produção usando a CLI do Firebase.

Por exemplo, se uma função foi acionada quando um objeto foi excluído, mas você ativou o controle de versão do objeto e quer se inscrever no evento de arquivamento, primeiro deve renomear a função e editá-la para ter o novo tipo de gatilho.

// before
const {onObjectDeleted} = require("firebase-functions/v2/storage");

exports.objectDeleted = onObjectDeleted((event) => {
    // ...
});

// after
const {onObjectArchived} = require("firebase-functions/v2/storage");

exports.objectArchived = onObjectArchived((event) => {
    // ...
});

# before
from firebase_functions import storage_fn

@storage_fn.on_object_deleted()
def object_deleted(event):
  # ...

# after 
from firebase_functions import storage_fn

@storage_fn.on_object_archived()
def object_archived(event):
  # ...

Em seguida, execute os seguintes comandos para criar a nova função primeiro, antes de excluir a função antiga:

# Create new function objectArchived
firebase deploy --only functions:objectArchived

# Wait until deployment is done; now both objectDeleted and objectArchived are running

# Delete objectDeleted
firebase functions:delete objectDeleted

Definir opções do ambiente de execução

Com o Cloud Functions for Firebase, é possível selecionar opções de ambiente de execução, como a versão do ambiente de execução do Node.js, o tempo limite por função, a alocação de memória e a quantidade mínima/máxima de instâncias de função.

É prática recomendada que essas opções, exceto pela versão do Node.js, sejam definidas em um objeto de configuração dentro do código da função. O objeto RuntimeOptions é a fonte de verdade para as opções de ambiente de execução da sua função e vai substituir as opções definidas por qualquer outro método, como o console do Google Cloud ou a CLI gcloud.

Se o seu fluxo de trabalho de desenvolvimento envolver a configuração manual de opções de ambiente de execução usando o Console do Google Cloud ou a CLI gcloud e você não quiser que esses valores sejam substituídos em cada implantação, defina a opção preserveExternalChanges como true. Com essa opção definida como true, o Firebase mescla as opções de ambiente de execução definidas no seu código com as configurações da versão atualmente implantada da função na prioridade a seguir:

1. A opção está definida no código de funções: substituir as alterações externas.
2. A opção está definida como RESET_VALUE no código das funções: substituir as alterações externas pelo valor padrão.
3. A opção não está definida no código de funções, mas está configurada na função implantada atualmente: usar a opção especificada na função implantada.

O uso da opção preserveExternalChanges: true não é recomendado na maioria dos casos, porque o código deixa de ser a fonte de verdade completa das opções de ambiente de execução para suas funções. Se for usar essa opção, verifique o console do Google Cloud ou use a CLI gcloud para consultar a configuração completa de uma função.

Definir a versão do Node.js

O SDK do Firebase para Cloud Functions permite selecionar o ambiente de execução do Node.js. É possível executar exclusivamente todas as funções em um projeto apenas no ambiente de execução correspondente a uma dessas versões do Node.js com suporte:

• Node.js 22 (pré-lançamento)
• Node.js 20
• Node.js 18

As versões 14 e 16 do Node.js foram descontinuadas e serão desativadas no início de 2025. A implantação com essas versões descontinuadas está desativada.

Para definir a versão do Node.js, faça o seguinte:

É possível definir a versão no campo engines no arquivo package.json que foi criado no diretório functions/ durante a inicialização. Por exemplo, para usar apenas a versão 18, edite esta linha em package.json:

  "engines": {"node": "20"}

Ao usar o gerenciador de pacotes Yarn ou ter outros requisitos específicos para o campo engines, há a alternativa de definir o ambiente de execução do SDK do Firebase para Cloud Functions em firebase.json:

  {
    "functions": {
      "runtime": "nodejs18" // or nodejs20
    }
  }

A CLI usa o valor definido em firebase.json em vez de qualquer valor ou intervalo definido separadamente em package.json.

Fazer upgrade do ambiente de execução do Node.js

Para fazer upgrade do ambiente de execução do Node.js, siga as etapas a seguir:

1. Verifique se o projeto está no plano de preços Blaze.
2. Verifique se você está usando a CLI do Firebase v11.18.0 ou mais recente.
3. Altere o valor engines no arquivo package.json criado no diretório functions/ durante a inicialização. Por exemplo, ao fazer upgrade da versão 18 para a versão 20, a entrada será semelhante ao seguinte: "engines": {"node": "20"}
4. Também é possível testar suas alterações usando o Firebase Local Emulator Suite.
5. Reimplante todas as funções.

Definir versão do Python

Com o SDK do Firebase para Cloud Functions 12.0.0 e versões mais recentes, é possível selecionar o ambiente de execução do Python. Configure a versão do ambiente de execução em firebase.json, conforme mostrado:

  {
    "functions": {
      "runtime": "python310" // or python311
    }
  }

Controlar o comportamento de escalonamento

Por padrão, o Cloud Functions for Firebase escalona o número de instâncias em execução com base no número de solicitações recebidas. Isso pode reduzir até zero a quantidade de instâncias em períodos de tráfego menor. No entanto, se o app exigir latência reduzida, e você quiser limitar o número de inicializações a frio, altere esse comportamento padrão especificando um número mínimo de instâncias de contêiner a serem mantidas em modo de espera e prontas para exibir solicitações.

Da mesma forma, é possível definir um número máximo para limitar o escalonamento de instâncias em resposta a solicitações recebidas. Use essa configuração como uma maneira de controlar seus custos ou de limitar o número de conexões com um serviço de apoio, como um banco de dados.

Usando essas configurações com a configuração de simultaneidade por instância (nova na 2ª geração), é possível controlar e ajustar o comportamento de escalonamento das funções. A natureza do aplicativo e da função determina quais configurações são mais econômicas e resulta no melhor desempenho.

Para alguns apps com pouco tráfego, uma opção de CPU mais baixa sem várias simultaneidades é ideal. Para outras em que as inicializações a frio são um problema crítico, a definição de alta simultaneidade e instâncias mínimas significa que um conjunto de instâncias é sempre mantido aquecido para lidar com grandes picos de tráfego.

Para apps de menor escala que recebem muito pouco tráfego, definir instâncias máximas baixas com alta simultaneidade significa que o app pode lidar com bursts de tráfego sem gerar custos excessivos. No entanto, lembre-se de que, quando o número máximo de instâncias é muito baixo, as solicitações podem ser descartadas quando o limite máximo for atingido.

Permitir solicitações simultâneas

No Cloud Functions for Firebase (1ª geração), cada instância processa uma solicitação por vez. Portanto, o comportamento de escalonamento foi definido apenas com as configurações mínima e máxima de instâncias. No Cloud Functions for Firebase (2ª geração), além de controlar o número de instâncias, é possível controlar o número de solicitações que cada instância pode disponibilizar ao mesmo tempo usando a opção concurrency. O valor padrão de simultaneidade é 80, mas é possível defini-lo como qualquer número inteiro entre 1 e 1.000.

As funções com configurações de simultaneidade mais altas podem absorver picos de tráfego sem inicialização a frio, porque cada instância provavelmente tem alguma margem. Se uma instância estiver configurada para processar até 50 solicitações simultâneas, mas no momento gerencia apenas 25, ela poderá processar um pico de 25 solicitações extras sem exigir que uma nova instância inicie a frio. Por outro lado, com uma configuração de simultaneidade de apenas 1, esse pico nas solicitações pode levar a 25 inicializações a frio.

Neste cenário simplificado, demonstramos os ganhos de eficiência potenciais da simultaneidade. Na verdade, o comportamento de escalonamento para otimizar a eficiência e reduzir as inicializações a frio com simultaneidade é mais complexo. A simultaneidade no Cloud Functions for Firebase de 2ª geração é fornecida pelo Cloud Run e segue as regras de escalonamento automático de instâncias de contêiner do Cloud Run.

Ao testar configurações de simultaneidade mais altas no Cloud Functions for Firebase (2ª geração), lembre-se do seguinte:

• Configurações de simultaneidade mais altas podem exigir mais CPU e RAM para um desempenho ideal até atingir um limite prático. Uma função com processamento de vídeo ou imagem intenso, por exemplo, pode não ter os recursos para lidar com 1.000 solicitações simultâneas, mesmo quando as configurações de CPU e RAM são maximizadas.
• Como o Cloud Functions for Firebase (2ª geração) usa o Cloud Run, também é possível consultar as orientações do Google Cloud para otimização da simultaneidade.
• Teste várias vezes a simultaneidade em um ambiente de teste antes de mudar para a simultaneidade na produção.

Manter um número mínimo de instâncias em modo de espera

É possível definir um número mínimo de instâncias para uma função no código-fonte. Por exemplo, esta função define um mínimo de cinco instâncias que devem ser mantidas quentes:

const { onCall } = require("firebase-functions/v2/https");

exports.getAutocompleteResponse = onCall(
  {
    // Keep 5 instances warm for this latency-critical function
    minInstances: 5,
  },
  (event) => {
    // Autocomplete user’s search term
  }
);

@https_fn.on_call(min_instances=5)
def get_autocomplete_response(event: https_fn.CallableRequest) -> https_fn.Response:

Veja alguns pontos a serem considerados ao definir um valor mínimo de instâncias:

• Se o Cloud Functions for Firebase escalonar o app acima da configuração, uma inicialização a frio será feita para cada instância acima desse limite.
• Inicializações a frio afetam de forma mais grave os apps que têm aumento de tráfego. Se o app apresentar picos de tráfego e um valor alto o suficiente for definido para que as inicializações a frio sejam reduzidas a cada aumento, você vai notar que a latência vai ser bem menor. Para apps com tráfego constante, inicializações a frio não afetam muito o desempenho.

• Definir um limite de instâncias mínimas é uma boa ideia para ambientes de produção, mas isso geralmente deve ser evitado em ambientes de teste. Para reduzir a escala a zero no projeto de teste e seguir diminuindo as inicializações a frio no projeto de produção, defina um valor mínimo de instâncias na configuração parametrizada:

  Node.js

  const functions = require('firebase-functions/v1');
  const { defineInt, defineString } = require('firebase-functions/params');
  
  // Define some parameters
  const minInstancesConfig = defineInt('HELLO_WORLD_MININSTANCES');
  const welcomeMessage = defineString('WELCOME_MESSAGE');
  
  // To use configured parameters inside the config for a function, provide them 
  // directly. To use them at runtime, call .value() on them.
  export const helloWorld = functions.runWith({ minInstances: minInstancesConfig}).https.onRequest(
    (req, res) => {
      res.send(`${welcomeMessage.value()}! I am a function.`);
    }
  );
  

  Python

  MIN_INSTANCES = params.IntParam("HELLO_WORLD_MININSTANCES")
  WELCOME_MESSAGE = params.StringParam("WELCOME_MESSAGE")
  
  @https_fn.on_request(min_instances=MIN_INSTANCES.value())
  def get_autocomplete_response(event: https_fn.Request) -> https_fn.Response:
      return https_fn.Response(f"{WELCOME_MESSAGE.value()} I'm a function.")
  

Limitar o número máximo de instâncias para uma função

É possível definir um valor para o número máximo de instâncias no código-fonte da função. Por exemplo, esta função define um limite de 100 instâncias para não sobrecarregar um banco de dados legado hipotético:

const { onMessagePublished } = require("firebase-functions/v2/pubsub");

exports.mirrorevents = onMessagePublished(
  { topic: "topic-name", maxInstances: 100 },
  (event) => {
    // Connect to legacy database
  }
);

@pubsub_fn.on_message_published(topic="topic-name", max_instances=100)
def mirrorevents(event: pubsub_fn.CloudEvent):
#  Connect to legacy database

Se uma função HTTP for escalonada até o limite máximo de instâncias, as novas solicitações vão ser enfileiradas por 30 segundos e rejeitadas com um código de resposta 429 Too Many Requests se nenhuma instância estiver disponível depois desse tempo.

Para saber mais sobre as práticas recomendadas para o uso das configurações de instâncias máximas, confira estas práticas recomendadas para definir o número máximo de instâncias.

Definir o tempo limite e a alocação de memória

Em alguns casos, suas funções podem ter requisitos especiais para um valor de tempo limite longo ou uma grande alocação de memória. Você pode definir esses valores no console do Google Cloud ou no código-fonte da função (somente no Firebase).

Para definir a alocação de memória e o tempo limite no código-fonte das funções, use as opções globais de memória e tempo limite em segundos para personalizar a máquina virtual que executa suas funções. Por exemplo, essa função do Cloud Storage usa 1 GiB de memória e expira após 300 segundos:

exports.convertLargeFile = onObjectFinalized({
  timeoutSeconds: 300,
  memory: "1GiB",
}, (event) => {
  // Do some complicated things that take a lot of memory and time
});

@storage_fn.on_object_finalized(timeout_sec=300, memory=options.MemoryOption.GB_1)
def convert_large_file(event: storage_fn.CloudEvent):
# Do some complicated things that take a lot of memory and time.

O valor máximo para o tempo limite em segundos é 540, ou 9 minutos.

Para definir a alocação de memória e o tempo limite no console do Google Cloud:

1. No console do Google Cloud, selecione Cloud Functions for Firebase no menu à esquerda.
2. Clique no nome de uma função para selecioná-la em uma lista de funções.
3. Clique no ícone Editar no menu na parte superior.
4. Selecione uma alocação de memória no menu suspenso Memória alocada.
5. Clique em Mais para exibir as opções avançadas e insira um número de segundos na caixa de texto Tempo limite.
6. Clique em Salvar para atualizar a função.

Substituir os padrões da CPU

Para até 2 GB de memória alocada, cada função no Cloud Functions for Firebase (2ª geração) tem como padrão uma CPU. Esse valor aumenta para duas CPUs no caso de 4 e 8 GB. Observe que isso é significativamente diferente do comportamento padrão da 1ª geração de maneiras que podem levar a custos um pouco mais altos para funções de pouca memória, conforme mostrado nesta tabela:

Se preferir o comportamento da 1ª geração para suas funções da 2ª, defina os padrões da 1ª geração como uma opção global:

// Turn off Firebase defaults
setGlobalOptions({ cpu: 'gcf_gen1' });

# Use 1st gen behavior
set_global_options(cpu="gcf_gen1")

Para funções com uso intensivo da CPU, a 2ª geração oferece a flexibilidade de configurar mais CPUs. É possível aumentar a CPU por função, como mostrado abaixo:

// Boost CPU in a function:
export const analyzeImage = onObjectFinalized({ cpu: 2 }, (event) => {
  // computer vision goes here
});

# Boost CPU in a function:
@storage_fn.on_object_finalized(cpu=2)
def analyze_image(event: storage_fn.CloudEvent):
# computer vision goes here