Gravar funções do Cloud Run

Esta página apresenta uma introdução sobre como escrever funções do Cloud Run com o Functions Framework.

Ao escrever o código-fonte de funções, use o Functions Framework, uma biblioteca de código aberto para escrever funções do Cloud Run. Com o Functions Framework, você pode escrever funções leves executadas no Cloud Run e em outros ambientes, incluindo sua máquina de desenvolvimento local e ambientes baseados em Knative.

O Functions Framework permite:

  • Invocar uma função do Cloud Run em resposta a uma solicitação.
  • Cancele automaticamente o marshal de eventos em conformidade com a especificação CloudEvents, uma especificação padrão do setor para descrever dados de eventos de maneira comum.
  • Inicie um servidor de desenvolvimento local para realizar testes rápidos.

Escrever funções com o Functions Framework

O Functions Framework oferece uma interface para criar serviços modulares. Para usar o framework de funções no código-fonte, especifique o seguinte:

Ponto de entrada da função

O código-fonte precisa definir um ponto de entrada para a função, que é o código específico executado quando a função do Cloud Run é invocada. Especifique esse ponto de entrada ao implantar a função.

A definição do ponto de entrada depende do ambiente de execução da linguagem usada. Algumas linguagens usam uma função como ponto de entrada, enquanto outras usam uma classe.

Tipo de assinatura

Ao escrever o código-fonte de uma função com o Functions Framework, é necessário especificar um dos dois tipos de assinatura:

  • Funções HTTP: uma função que registra uma função de gerenciador HTTP. Consulte Gravar funções HTTP para mais informações.
  • Funções baseadas em eventos (também chamadas de funções do CloudEvents): uma função que registra uma função de gerenciador do CloudEvents. Consulte Escrever funções orientadas a eventos para mais informações.

Use uma função HTTP quando precisar que a função tenha um endpoint de URL e responda a solicitações HTTP, como para webhooks. Use uma função orientada a eventos quando ela precisar ser acionada diretamente em resposta a eventos no seu Google Cloud projeto, como mensagens em um tópico do Pub/Sub ou alterações em um bucket do Cloud Storage.

Estrutura do diretório de origem

O Functions Framework é compatível com várias linguagens de programação. O ambiente de execução da linguagem que você escolhe e o tipo de função que você quer escrever determinam como estruturar seu código e implementar sua função.

Para que o Cloud Run localize a definição da função, cada ambiente de execução da linguagem tem requisitos para estruturar o código-fonte.

Node.js

A estrutura de diretórios básica para funções Node.js é a seguinte:

.
├── index.js
└── package.json

Por padrão, o Cloud Run tenta carregar o código-fonte de um arquivo chamado index.js na raiz do diretório da função. Para especificar um arquivo principal diferente, use o campo main no seu arquivo package.json.

Seu arquivo package.json também precisa incluir o Functions Framework para Node.js como uma dependência:

{
  "main": "index.js",
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  }
}

O código no arquivo principal precisa definir o ponto de entrada da função e importar outros códigos e módulos do Node.js. O arquivo principal também pode definir vários pontos de entrada de função que podem ser implantados separadamente.

Consulte a visão geral do ambiente de execução do Node.js e o Functions Framework para Node.js para mais detalhes.

Python

A estrutura de diretórios básica para funções Python é a seguinte:

.
├── main.py
└── requirements.txt

O Cloud Run carrega o código-fonte de um arquivo chamado main.py na raiz do diretório de funções. O arquivo principal precisa ser nomeado como main.py.

O arquivo requirements.txt precisa incluir o Functions Framework para Python como uma dependência:

functions-framework==3.*

O código no arquivo main.py precisa definir seu ponto de entrada de função e pode importar outras dependências de código e externas normalmente. O arquivo main.py também pode definir vários pontos de entrada de função que podem ser implantados separadamente.

Consulte a Visão geral do ambiente de execução do Python e o Functions Framework para Python para mais detalhes.

Go

A estrutura de diretórios básica para funções Go é a seguinte:

.
├── myfunction.go
└── go.mod

Sua função deve estar em um pacote Go na raiz do projeto. O pacote e os arquivos de origem dele podem ter qualquer nome, exceto se a função não puder estar em package main. Se você precisar de um pacote main, por exemplo, para testes locais, crie um em um subdiretório:

.
├── myfunction.go
├── go.mod
└── cmd/
  └── main.go

Seu arquivo go.mod precisa incluir o Functions Framework para Go como uma dependência:

module example.com/my-module

require (
  github.com/GoogleCloudPlatform/functions-framework-go v1.5.2
)

O código no pacote raiz precisa definir o ponto de entrada de função e importar outros códigos de subpacotes e dependências normalmente. Seu pacote também pode definir vários pontos de entrada de função que podem ser implantados separadamente.

Consulte a Visão geral do ambiente de execução do Go e o Functions Framework para Go para mais detalhes.

Java

A estrutura de diretórios básica para funções Java é a seguinte:

.
├── pom.xml
└── src/
  └── main/
      └── java/
          └── MyFunction.java

Os arquivos de origem Java precisam estar no diretório src/main/java/ e podem ter qualquer nome. Se os arquivos de origem declararem um pacote, adicione um diretório extra em src/main/java com o nome do pacote:

.
├── pom.xml
└── src/
  └── main/
      └── java/
          └── mypackage/
              └── MyFunction.java

Recomendamos colocar os testes associados em um subdiretório src/test/java/.

O arquivo pom.xml precisa incluir o Functions Framework para Java como dependência:

...
    <dependency>
      <groupId>com.google.cloud.functions</groupId>
      <artifactId>functions-framework-api</artifactId>
      <version>1.0.4</version>
    </dependency>
...

O código nos arquivos de origem precisa definir o ponto de entrada de função e importar outros códigos e dependências externas normalmente. Seus arquivos de origem também podem definir vários pontos de entrada de função que podem ser implantados separadamente.

Consulte a Visão geral do ambiente de execução do Java e o Functions Framework para Java para mais detalhes.

.NET

A estrutura de diretórios básica para funções .NET é a seguinte:

.
├── MyFunction.cs
└── MyProject.csproj

Você pode estruturar seus projetos como faria com qualquer outro código-fonte .NET. Seus arquivos de origem podem ter qualquer nome.

O arquivo do projeto precisa incluir o Functions Framework para .NET como uma dependência:

...
    <PackageReference Include="Google.Cloud.Functions.Hosting" Version="1.0.0" />
...

O código nos arquivos de origem precisa definir o ponto de entrada de função e importar outros códigos e dependências externas normalmente. Seus arquivos de origem também podem definir vários pontos de entrada de função que podem ser implantados separadamente.

Consulte a Visão geral do ambiente de execução do.NET e o Functions Framework para .NET para mais detalhes.

Ruby

A estrutura de diretórios básica para funções do Ruby é a seguinte:

.
├── app.rb
├── Gemfile
└── Gemfile.lock

O Cloud Run carrega o código-fonte de um arquivo chamado app.rb na raiz do diretório de funções. O arquivo principal precisa ter o nome app.rb.

O arquivo Gemfile precisa incluir o Functions Framework para Ruby como uma dependência:

source "https://rubygems.org"
gem "functions_framework", "~> 1.0"

O código no arquivo app.rb precisa definir seu ponto de entrada de função e pode importar outras dependências de código e externas normalmente. O arquivo app.rb também pode definir vários pontos de entrada de função que podem ser implantados separadamente.

Consulte a Visão geral do ambiente de execução do Ruby e o Functions Framework para Ruby para mais detalhes.

PHP

A estrutura de diretórios básica para funções PHP é a seguinte:

.
├── index.php
└── composer.json

O Cloud Run carrega o código-fonte de um arquivo chamado index.php na raiz do diretório de funções. O arquivo principal precisa ser nomeado como index.php.

O arquivo composer.json precisa incluir o Functions Framework para PHP como uma dependência:

{
  "require": {
    "google/cloud-functions-framework": "^1.1"
  }
}

O código no arquivo index.php precisa definir o ponto de entrada da função e pode importar outros códigos e dependências externas normalmente. O arquivo index.php também pode definir vários pontos de entrada de função que podem ser implantados separadamente.

Consulte a Visão geral do ambiente de execução do PHP e o Functions Framework para PHP para mais detalhes.

Se você agrupar várias funções em um único projeto, saiba que cada função pode acabar compartilhando o mesmo conjunto de dependências. No entanto, algumas das funções podem não precisar de todas as dependências.

Sempre que possível, recomendamos dividir grandes bases de código multifuncionais e colocar cada função no próprio diretório de nível superior, conforme mostrado nos exemplos anteriores, com os próprios arquivos de configuração de origem e projeto. Essa abordagem minimiza o número de dependências necessárias para uma função específica, o que reduz a quantidade de memória necessária para a função.

A seguir