Escrever funções

Esta página apresenta uma introdução para escrever funções com o Framework de funções.

Ao escrever o código-fonte de funções para o Cloud Run, 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 a máquina de desenvolvimento local e ambientes baseados em Knative.

O Functions Framework permite:

  • Invoque uma função 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 que é 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. Para algumas linguagens, o ponto de entrada é uma função, enquanto em outras, o ponto de entrada é 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 do CloudEvents (também chamadas de funções baseadas em eventos): uma função que registra uma função de gerenciador do CloudEvents. Consulte Escrever funções do CloudEvents 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 do CloudEvents quando ela precisar ser acionada diretamente em resposta a eventos no seu projeto doGoogle Cloud , 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