Implantar uma função do Cloud Run

Observação: este conteúdo se aplica apenas às funções do Cloud Run, anteriormente chamadas de Cloud Functions (2ª geração).

Para a versão de 1ª geração deste documento, consulte Implantar uma função do Cloud Run (1ª geração).

Neste guia, você verá como implantar uma função do Cloud Run a partir do código-fonte.

O processo de implantação recebe o código-fonte e as configurações e cria uma imagem executável que o Cloud Run functions gerencia automaticamente para processar solicitações para a função.

Princípios básicos de implantação

Os usuários que implantam funções do Cloud Run precisam ter o papel do IAM de Desenvolvedor de funções do Cloud Run ou um papel que inclua as mesmas permissões. Consulte também Outras configurações para implantação.

Selecione uma guia para ver instruções sobre como implantar uma função usando a gcloud CLI ou o console do Google Cloud.

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Use o comando gcloud functions deploy para implantar uma função:

   gcloud functions deploy YOUR_FUNCTION_NAME \
   --gen2 \
   --region=YOUR_REGION \
   --runtime=YOUR_RUNTIME \
   --source=YOUR_SOURCE_LOCATION \
   --entry-point=YOUR_CODE_ENTRYPOINT \
   TRIGGER_FLAGS
   

   O primeiro argumento, YOUR_FUNCTION_NAME, é um nome para a função implantada. O nome da função deve começar com uma letra, seguida por até 62 letras, números, hífens e sublinhados, e terminar com uma letra ou um número O nome do serviço do Cloud Run que é criado para a função substitui os sublinhados por hífens, e as letras maiúsculas são convertidas em minúsculas. Por exemplo, Function_1 vai receber o nome function-1 no Cloud Run.

   • A flag --gen2 especifica que você quer implantar nas funções do Cloud Run.

     Observação: execute gcloud config set functions/gen2 true para definir todas as implantações futuras pela primeira vez como funções do Cloud Run.

   • A sinalização --region especifica a região em que a função será implantada. Consulte Locais para ver uma lista de regiões compatíveis com o Cloud Run functions.

   • A sinalização --runtime especifica o ambiente de execução da linguagem que a função usa. O Cloud Run functions aceita vários ambientes de execução. Consulte Tempos de execução para mais informações.

   • A sinalização --source especifica o local do código-fonte da função. Consulte as seções a seguir para mais detalhes:

     • Implantar usando sua máquina local
     • Implantar a partir do Cloud Storage

   • A sinalização --entry-point especifica o ponto de entrada da função no código-fonte. Este é o código que será executado quando a função for executada. O valor dessa sinalização precisa ser um nome de função ou de classe totalmente qualificada no código-fonte. Consulte Ponto de entrada de função para mais informações.

   • Para especificar o acionador da função, as sinalizações adicionais (representadas como TRIGGER_FLAGS acima) são obrigatórias, dependendo do acionador que você quer usar:

   Sinalizações do acionador	Descrição do gatilho
   --trigger-http	Acionar a função com uma solicitação HTTP(S) Consulte Acionadores HTTP para mais informações.
   --trigger-topic=YOUR_PUBSUB_TOPIC	Acionar a função quando uma mensagem for publicada no tópico especificado do Pub/Sub. Consulte Acionadores do Pub/Sub para mais informações.
   --trigger-bucket=YOUR_STORAGE_BUCKET	Acionar a função quando um objeto é criado ou substituído no bucket especificado do Cloud Storage. Consulte Acionadores do Cloud Storage para mais informações.
   --trigger-event-filters=EVENTARC_EVENT_FILTERS	Acione a função com o Eventarc quando um evento ocorrer corresponder aos filtros especificados. Requer que a sinalização --gen2 seja especificada. Consulte Acionadores do Eventarc para ver mais informações e outras opções.

   Também é possível especificar opções adicionais de configuração, rede e segurança ao implantar uma função.

   Para ver uma referência completa sobre o comando de implantação e as sinalizações dele, consulte a documentação gcloud functions deploy.

   Para ver alguns exemplos de comandos de implantação, consulte Exemplos de linha de comando.

Console

1. Acesse a página de visão geral das funções do Cloud Run no console do Google Cloud.

   Acessar as funções do Cloud Run

   Verifique se o projeto do Google Cloud em que você quer implantar o Cloud Run functions está selecionado.

2. Clique em Criar função.

3. No campo Ambiente, selecione Funções do Cloud Run.

4. No campo Nome da função, insira um nome. O nome da função deve começar com uma letra, seguida por até 62 letras, números, hifens ou sublinhados, e terminar com uma letra ou um número. O nome do serviço do Cloud Run criado para sua função vai substituir os sublinhados por hífens, e as letras maiúsculas serão convertidas em minúsculas. Por exemplo, Function_1 vai receber o nome function-1 no Cloud Run.

5. No campo Região, selecione uma região em que a função será implantada.

6. Na seção Acionador, siga as etapas com base no ambiente selecionado:

   1. No campo Tipo de gatilho, selecione o gatilho que você quer usar:
      • Para um gatilho HTTPS, selecione a opção apropriada se você quiser permitir invocações não autenticadas da sua função. Cada função do Cloud Run tem um endpoint para acionadores HTTP(S). Por padrão, a autenticação é obrigatória. Para mais informações, consulte Como autenticar para invocação.
      • Para uma função orientada por eventos, escolha uma destas opções: Cloud Pub/Sub, Cloud Storage, Cloud Firestore ou Outro gatilho. Consulte Gatilhos do Eventarc para mais informações.
      • Depois de preencher os campos obrigatórios, clique em Salvar gatilho.

7. Se quiser, expanda a seção Ambiente de execução, build... no final da página para mais opções de configuração e segurança.

8. Clique em Próximo para acessar a etapa Código.

9. No campo Ambiente de execução, selecione o ambiente de execução da linguagem que a função usa. O Cloud Run functions oferece suporte a vários ambientes de execução. Consulte Tempos de execução para mais informações.

10. No campo Ponto de entrada, insira o ponto de entrada da sua função no código-fonte. Este é o código que será executado quando a função for executada. O valor dessa sinalização precisa ser um nome de função ou de classe totalmente qualificada no código-fonte. Consulte Ponto de entrada de função para mais informações.

11. No campo Código-fonte, selecione a opção adequada para saber como fornecer o código-fonte da função. Consulte as seções a seguir para mais detalhes.

    • Implantar a partir da sua máquina local (upload do ZIP)
    • Implantar a partir do Cloud Storage
    • Implantar usando o editor in-line do console do Google Cloud

12. Clique em Implantar.

Quando a implantação for concluída com êxito, as funções aparecerão com uma marca de seleção verde na página de visão geral do Cloud Run functions no console do Google Cloud:

A implantação inicial de uma função pode levar vários minutos, enquanto a infraestrutura subjacente é provisionada. A reimplantação de uma função existente é mais rápida, e o tráfego de entrada é migrado automaticamente para a versão mais recente.

Observação: as instâncias provisionadas com uma versão anterior de uma função poderão continuar executando e processando tráfego por vários minutos após a conclusão de uma nova implantação. Isso garante que o tráfego enviado à função não seja descartado enquanto uma implantação estiver em andamento. Além disso, quando ocorre uma falha na implantação, se houver uma versão anterior da função, ela continuará disponível na maioria dos casos.

Implante na máquina local

Nesta seção, descrevemos como implantar uma função do código-fonte localizado na máquina local.

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Siga as instruções de implantação acima usando o comando gcloud functions deploy.

   Para a flag --source, especifique um caminho do sistema de arquivos local até o diretório raiz do código-fonte da função. Consulte Estrutura do diretório de origem. O diretório de trabalho atual será usado se esta sinalização for omitida.

   Também é possível usar a sinalização --stage-bucket para especificar um bucket do Cloud Storage para fazer upload do código-fonte como parte da implantação.

   Durante o upload do código-fonte, o Cloud Run functions exclui arquivos desnecessários usando o arquivo .gcloudignore.

Console

1. Siga as instruções de implantação acima usando o console do Google Cloud até chegar ao campo Código-fonte.
2. No campo Código-fonte, selecione Upload do ZIP.
3. No campo Bucket de destino, clique em Procurar para selecionar um bucket do Cloud Storage a fim de fazer upload do código-fonte como parte da implantação.
4. No campo Arquivo ZIP, clique em Procurar para selecionar um arquivo ZIP para fazer upload do seu sistema de arquivos local. Os arquivos de origem da função precisam estar localizados na raiz do arquivo ZIP. Consulte Estrutura do diretório de origem.
5. Clique em Implantar.

Implantar do Cloud Storage

Nesta seção, descrevemos como implantar uma função do código-fonte localizado em um bucket do Cloud Storage. O código-fonte precisa ser empacotado como um arquivo ZIP.

Para que as funções do Cloud Run leiam em um bucket do Cloud Storage, o agente de serviço do Cloud Run functions precisa ter a permissão storage.objects.get. Se o bucket de origem estiver no mesmo projeto que sua função, a permissão será concedida automaticamente. Se o bucket estiver em um projeto diferente, será necessário conceder a permissão ao agente de serviço manualmente.

Consulte Usar permissões do IAM na documentação do Cloud Storage para ver informações sobre como controlar o acesso aos buckets.

Com essa permissão, é possível implantar uma função do Cloud Storage:

gcloud

1. In the Google Cloud console, activate Cloud Shell.

   Activate Cloud Shell

   At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

2. Siga as instruções de implantação acima usando o comando gcloud functions deploy.

   Para a sinalização --source, especifique um caminho do Cloud Storage, começando com gs://. O objeto no caminho precisa ser um arquivo ZIP com o código-fonte da função. Os arquivos de origem da função precisam estar localizados na raiz do arquivo ZIP. Consulte Estrutura do diretório de origem.

Console

1. Siga as instruções de implantação acima usando o console do Google Cloud até chegar ao campo Código-fonte.
2. No campo Código-fonte, selecione ZIP do Cloud Storage.
3. No campo Local do Cloud Storage, clique em Procurar para selecionar um arquivo ZIP do Cloud Storage. Os arquivos de origem da função precisam estar localizados na raiz do arquivo ZIP. Consulte Estrutura do diretório de origem.
4. Clique em Implantar.

Implantar usando o editor in-line do console do Google Cloud

Nesta seção, descrevemos como escrever e implantar uma função diretamente do console do Google Cloud usando o editor in-line fornecido.

1. Siga as instruções de implantação acima usando o console do Google Cloud até chegar ao campo Código-fonte.
2. No campo Código-fonte, selecione Editor in-line.
3. Use o editor fornecido para criar ou editar arquivos de origem, conforme necessário. Consulte Estrutura do diretório de origem.
   • O painel esquerdo lista seus arquivos de origem e permite criar, renomear e excluir arquivos.
   • O painel à direita é um editor de texto que permite editar o conteúdo do arquivo.
4. Clique em Implantar.

Exemplos de linha de comando

Nesta seção, mostramos os comandos de implantação para alguns exemplos de cenários de implantação.

Para saber mais sobre os diferentes gatilhos compatíveis com as funções do Cloud Run, consulte Gatilhos do Cloud Run functions.

Função HTTP do código-fonte local

Suponha que você tenha uma função HTTP da seguinte maneira:

• A função usa nodejs22.
• O código-fonte está no diretório de trabalho atual (.).
• O ponto de entrada no código é chamado de myHttpFunction.

Para implantar a função com o nome my-http-function na região us-central1, use o seguinte comando:

gcloud functions deploy my-http-function \
  --gen2 \
  --region=us-central1 \
  --runtime=nodejs22 \
  --source=. \
  --entry-point=myHttpFunction \
  --trigger-http

Função Pub/Sub do código-fonte no Cloud Storage

Suponha que você tenha uma função orientada a eventos da seguinte maneira:

• A função gerencia eventos de publicação de mensagens do Pub/Sub.
• A função usa python312.
• O código-fonte está no Cloud Storage no caminho. gs://my-bucket/my_function_source.zip.
• O ponto de entrada no código é chamado de pubsub_handler.

Para implantar a função com o nome my-pubsub-function na região europe-west1 e fazer com que a função seja acionada por mensagens no tópico do Pub/Sub my-topic, use o seguinte comando:

gcloud functions deploy my-pubsub-function \
  --gen2 \
  --region=europe-west1 \
  --runtime=python312 \
  --source=gs://my-bucket/my_function_source.zip \
  --entry-point=pubsub_handler \
  --trigger-topic=my-topic

Função do Cloud Storage pelo código-fonte local

Suponha que você tenha uma função orientada a eventos da seguinte maneira:

• A função gerencia eventos de exclusão de objetos do Cloud Storage.
• A função usa java21.
• O código-fonte está localizado localmente no caminho ./functions/storage-function.
• O ponto de entrada no código é chamado de myproject.StorageFunction.

Para implantar a função com o nome my-storage-function na região asia-northeast1 e fazer com que a função seja acionada por eventos no bucket do Cloud Storage my-bucket, use o seguinte comando:

gcloud functions deploy my-storage-function \
  --gen2 \
  --region=asia-northeast1 \
  --runtime=java21 \
  --source=./functions/storage-function \
  --entry-point=myproject.StorageFunction \
  --trigger-event-filters="type=google.cloud.storage.object.v1.deleted" \
  --trigger-event-filters="bucket=my-bucket"

Próximas etapas

• Veja detalhes sobre gatilhos do Cloud Run functions.
• Saiba mais sobre o processo de build do Cloud Run functions.
• Conheça outras opções de configuração do Cloud Run functions.
• Saiba como proteger o Cloud Run functions.
• Consulte Tutoriais para ver exemplos de casos de uso específicos do Cloud Run functions.