Implantar uma Função do Cloud

Neste guia, você verá como implantar uma função do Cloud 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 Functions gerencia automaticamente para processar solicitações para a função.

Princípios básicos de implantação

Os usuários que implantam o Cloud Functions precisam ter o papel do IAM de Desenvolvedor do Cloud Functions 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

   • A sinalização --gen2 especifica que você quer implantar no Cloud Functions (2a geração). Essa sinalização é necessária para a implantação inicial de uma função de segunda geração. Consulte Comparação de versões do Cloud Functions para ver uma comparação entre o Cloud Functions (1a geração) e o Cloud Functions (2a geração).

     Observação: é possível usar o comando gcloud config set functions/gen2 true para definir todas as implantações futuras pela primeira vez como a segunda geração.

   • 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 Functions.

   • A sinalização --runtime especifica o ambiente de execução da linguagem que a função usa. O Cloud 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
     • Implantar a partir de um repositório de origem

   • 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	(Somente segunda geração) Acionar 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.
   --trigger-event=EVENT_TYPE [--trigger-resource=RESOURCE]	(Apenas na 1a geração) Acionar a função quando ocorrer o evento especificado. É necessário especificar um recurso para alguns tipos de evento. Para mais informações, consulte Acionadores compatíveis com o Cloud Functions (1a geração).

   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 do Cloud Functions no console do Google Cloud:

   Acessar o Cloud Functions

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

2. Clique em Criar função.

3. No campo Ambiente, selecione primeira geração ou segunda geração. Consulte Comparação de versões do Cloud Functions para ver uma comparação entre o Cloud Functions (1a geração) e o Cloud Functions (2a geração).

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.

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ª geração
     1. Na seção Autenticação HTTPS, selecione a opção adequada se você quiser permitir invocações não autenticadas da sua função. Por padrão, a autenticação é obrigatória. Para mais informações, consulte Como autenticar para invocação.
     2. No campo Tipo de acionador, selecione um tipo. Para mais detalhes, consulte Acionadores compatíveis com o Cloud Functions (1a geração).
     3. Preencha os outros campos de acordo com o tipo de acionador selecionado.
     4. Clique em Save.
   • 2ª geração
     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 de segunda geração 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 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 a partir de um repositório de origem
    • 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 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 do Cloud, 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 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 o Cloud Functions leia a partir de um bucket do Cloud Storage, verifique se o agente de implantação tem a permissão storage.objects.get:

• No Cloud Functions (1st gen), é preciso conceder essa permissão à conta que executa a implantação.
• No Cloud Functions (2nd gen), o agente de serviço do Cloud Functions precisa dessa permissão. Se o bucket de origem estiver no mesmo projeto que sua função, ele será concedido automaticamente. Se o bucket estiver em um projeto diferente, será necessário concedê-lo manualmente ao agente de serviço.

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 de um repositório de origem

Nesta seção, descrevemos como implantar uma função do código-fonte localizado no Cloud Source Repositories. A implantação do Cloud Source Repositories também permite implantar código hospedado em um repositório do GitHub ou do Bitbucket.

Observação: a implantação de funções do Cloud Source Repositories só é compatível com o Cloud Functions (1ª geração).

Antes de implantar o código do Cloud Source Repositories, é necessário configurar um repositório e, opcionalmente, conectá-lo ao seu repositório do GitHub ou do Bitbucket.

Para que o Cloud Functions leia de um repositório de origem, o agente de serviço do Cloud Functions precisa do papel do IAM de Leitor de repositório de origem (roles/source.reader) no repositório. Se o repositório de origem estiver no mesmo projeto que sua função, essa permissão será incluída automaticamente. Se o repositório de origem estiver em um projeto diferente, será preciso conceder a permissão manualmente.

Em seguida, implante uma função do repositório:

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 uma referência do repositório de origem para a localização do código-fonte da função. Consulte Estrutura do diretório de origem. A referência mais básica do Cloud Source Repositories tem o seguinte formato:

   https://source.developers.google.com/projects/PROJECT_ID/repos/REPOSITORY_NAME
   

   No caminho anterior, PROJECT_ID é o ID do projeto do Google Cloud, e REPOSITORY_NAME é o nome do repositório de origem. Nesse caminho, o código-fonte do diretório raiz do repositório na revisão master será usado.

   Para implantar de uma revisão diferente de master, anexe uma das seguintes opções ao caminho:

   • /revisions/REVISION_NAME
   • /moveable-aliases/MOVEABLE_ALIAS
   • /fixed-aliases/FIXED_ALIAS

   Para implantar o código-fonte de um diretório que não seja a raiz do repositório, especifique uma revisão, um alias móvel ou um alias fixo e anexe /paths/PATH_TO_YOUR_SOURCE_DIRECTORY ao caminho.

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 Cloud Source Repository.
3. No campo Repositório, digite o nome do repositório de origem.
4. No campo Ramificação/tag, selecione Ramificação ou Tag, dependendo de onde você quer implantar.
5. Insira o nome da ramificação ou da tag quando indicado.
6. No campo Diretório com código-fonte, insira o caminho para o diretório no repositório que contém o código-fonte da função. Consulte Estrutura do diretório de origem.
7. 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 ver detalhes sobre os diferentes acionadores compatíveis com o Cloud Functions, consulte Acionadores do Cloud Functions.

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

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

• A função usa o Node.js 16.
• 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 no Cloud Functions (2a geraçã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=nodejs16 \
  --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 o Python 3.9.
• 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 no Cloud Functions (2a geração) com o nome my-pubsub-function na região europe-west1 e 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=python39 \
  --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 o Java 11.
• 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 no Cloud Functions (2a geraçã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, você: use o seguinte comando:

gcloud functions deploy my-storage-function \
  --gen2 \
  --region=asia-northeast1 \
  --runtime=java11 \
  --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 acionadores do Cloud Functions.
• Saiba mais sobre o processo de compilação do Cloud Functions.
• Explore outras opções de configuração do Cloud Functions.
• Saiba mais sobre como proteger o Cloud Functions.
• Consulte Tutoriais para ver exemplos de casos de uso específicos do Cloud Functions.