Escreva funções do Cloud Run

Esta página apresenta uma introdução à escrita de funções do Cloud Run com o Functions Framework.

Quando escreve o código fonte das funções, tem de usar o Functions Framework, uma biblioteca de código aberto para escrever funções do Cloud Run. Com o Functions Framework, pode escrever funções simples que são executadas no Cloud Run e noutros ambientes, incluindo a sua máquina de desenvolvimento local e ambientes baseados no Knative.

O Functions Framework permite-lhe:

  • Invocar uma função do Cloud Run em resposta a um pedido.
  • Desorganiza automaticamente eventos em conformidade com a especificação CloudEvents, uma especificação da indústria para descrever dados de eventos de forma comum.
  • Inicie um servidor de desenvolvimento local para testes rápidos.

Escreva funções com o Functions Framework

O Functions Framework fornece uma interface para criar serviços modulares. Para usar o Functions Framework no seu código-fonte, especifique o seguinte:

Ponto de entrada da função

O código-fonte tem de definir um ponto de entrada para a função, que é o código específico executado quando a função do Cloud Run é invocada. Especifica este ponto de entrada quando implementa a sua função.

A forma como define o ponto de entrada depende do tempo de execução da linguagem que usa. Algumas linguagens usam uma função como ponto de entrada, enquanto outras usam uma classe.

Tipo de assinatura

Quando escreve o código fonte de uma função com o Functions Framework, tem de especificar um dos dois tipos de assinatura:

  • Funções HTTP: uma função que regista uma função de controlador HTTP. Consulte o artigo Escreva funções HTTP para mais informações.
  • Funções acionadas por eventos (também denominadas funções CloudEvents): uma função que regista uma função de controlador CloudEvents. Consulte o artigo Escreva funções orientadas por eventos para mais informações.

Use uma função HTTP quando precisar que a sua função tenha um ponto final de URL e responda a pedidos HTTP, como para webhooks. Use uma função orientada por eventos quando a função deve ser acionada diretamente em resposta a eventos no seu projeto, como mensagens num tópico do Pub/Sub ou alterações num contentor do Cloud Storage. Google Cloud

Estrutura do diretório de origem

O Functions Framework é suportado em vários idiomas de programação. O tempo de execução da linguagem que escolher e o tipo de função que quer escrever determinam como estruturar o código e implementar a função.

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

Node.js

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

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

Por predefinição, o Cloud Run tenta carregar o código-fonte a partir de um ficheiro com o nome index.js na raiz do diretório da função. Para especificar um ficheiro de origem principal diferente, use o campo main no ficheiro package.json.

O seu ficheiro package.json também tem de 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 ficheiro principal tem de definir o ponto de entrada da função e pode importar outro código e módulos Node.js. O ficheiro principal também pode definir vários pontos de entrada de funções que podem ser implementados separadamente.

Consulte a vista geral do tempo de execução do Node.js e a estrutura de funções para Node.js para ver 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 ficheiro denominado main.py na raiz do diretório da função. Tem de atribuir o nome main.py ao ficheiro principal.

O seu ficheiro requirements.txt tem de incluir o Functions Framework para Python como uma dependência:

functions-framework==3.*

O código no seu ficheiro main.py tem de definir o ponto de entrada da função e pode importar outro código e dependências externas normalmente. O ficheiro main.py também pode definir vários pontos de entrada de funções que podem ser implementados separadamente.

Consulte a descrição geral do tempo de execução do Python e o Functions Framework para Python para ver mais detalhes.

Ir

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

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

A sua função tem de estar num pacote Go na raiz do seu projeto. O pacote e os respetivos ficheiros de origem podem ter qualquer nome, exceto que a função não pode estar em package main. Se precisar de um main pacote, por exemplo, para testes locais, pode criar um num subdiretório:

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

O seu ficheiro go.mod tem de incluir o Functions Framework para Go como dependência:

module example.com/my-module

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

O código no pacote raiz tem de definir o ponto de entrada da função e pode importar outro código de subpacotes e dependências normalmente. O seu pacote também pode definir vários pontos de entrada de funções que podem ser implementados separadamente.

Consulte a descrição geral do tempo de execução do Go e a estrutura de funções para Go para ver mais detalhes.

Java

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

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

Os seus ficheiros de origem Java têm de estar no diretório src/main/java/ e podem ter qualquer nome. Se os seus ficheiros de origem declararem um pacote, adicione um diretório adicional em src/main/java com o nome do pacote:

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

Recomendamos que coloque os testes associados num subdiretório src/test/java/.

O seu ficheiro pom.xml tem de incluir o Functions Framework for 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 ficheiros de origem tem de definir o ponto de entrada da função e pode importar outro código e dependências externas normalmente. Os ficheiros de origem também podem definir vários pontos de entrada de funções que podem ser implementados separadamente.

Consulte a descrição geral do tempo de execução Java e o Functions Framework para Java para ver mais detalhes.

.NET

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

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

Pode estruturar os seus projetos como faria com qualquer outro código-fonte .NET. Os ficheiros de origem podem ter qualquer nome.

O ficheiro de projeto tem de incluir o Functions Framework para .NET como uma dependência:

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

O código nos ficheiros de origem tem de definir o ponto de entrada da função e pode importar outro código e dependências externas normalmente. Os ficheiros de origem também podem definir vários pontos de entrada de funções que podem ser implementados separadamente.

Consulte a descrição geral do tempo de execução do.NET e a estrutura de funções para .NET para mais detalhes.

Ruby

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

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

O Cloud Run carrega o código-fonte de um ficheiro denominado app.rb na raiz do diretório da função. O ficheiro principal tem de ter o nome app.rb.

O seu ficheiro Gemfile tem de incluir o Functions Framework para Ruby como uma dependência:

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

O código no seu ficheiro app.rb tem de definir o ponto de entrada da função e pode importar outro código e dependências externas normalmente. O ficheiro app.rb também pode definir vários pontos de entrada de funções que podem ser implementados separadamente.

Consulte a descrição geral do tempo de execução do Ruby e a estrutura de funções para Ruby para ver 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 ficheiro denominado index.php na raiz do diretório da função. Tem de atribuir o nome index.php ao ficheiro principal.

O seu ficheiro composer.json tem de incluir o Functions Framework para PHP como uma dependência:

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

O código no ficheiro index.php tem de definir o ponto de entrada da função e pode importar outro código e dependências externas normalmente. O ficheiro index.php também pode definir vários pontos de entrada de funções que podem ser implementados separadamente.

Consulte a vista geral do tempo de execução do PHP e a estrutura de funções para PHP para ver mais detalhes.

Se agrupar várias funções num único projeto, tenha em atenção que cada função pode acabar por partilhar 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 que divida grandes bases de código multifuncionais e coloque cada função no seu próprio diretório de nível superior, conforme mostrado nos exemplos anteriores, com os seus próprios ficheiros de configuração de origem e de projeto. Esta abordagem minimiza o número de dependências necessárias para uma função específica, o que, por sua vez, reduz a quantidade de memória de que a função precisa.

O que se segue?