Executar funções com o Functions Framework

O Cloud Functions usa as bibliotecas de código aberto Functions Framework para unir as funções implantadas em um aplicativo HTTP persistente.

O Functions Framework também pode ser executado em qualquer outra plataforma compatível com a linguagem, incluindo sua máquina local, servidores no local, o Compute Engine e o Cloud Run.

Instalar dependências

No diretório da função, instale a biblioteca do Functions Framework para sua linguagem:

Consulte a biblioteca do Java Functions Framework para mais informações.

Node.js

npm install --save-dev @google-cloud/functions-framework

Python

pip install functions-framework

Go

go install github.com/GoogleCloudPlatform/functions-framework-go/funcframework

Java

Maven

Se você estiver usando o Maven, adicione o seguinte ao arquivo pom.xml:

<dependency>
  <groupId>com.google.cloud.functions</groupId>
  <artifactId>functions-framework-api</artifactId>
  <version>1.1.0</version>
  <scope>provided</scope>
</dependency>

Gradle

Se você estiver usando o Gradle, adicione o seguinte ao arquivo build.gradle:

dependencies {
  // Every function needs this dependency to get the Functions Framework API.
  compileOnly 'com.google.cloud.functions:functions-framework-api:1.1.0'

  // To run function locally using Functions Framework's local invoker
  invoker 'com.google.cloud.functions.invoker:java-function-invoker:1.3.1'
}

C#

Os comandos abaixo usam modelos .NET para criar uma nova base de código do .NET para Cloud Functions com a biblioteca do .NET para Functions Framework como dependência.

# HTTP functions
dotnet new gcf-http

# CloudEvent functions
dotnet new gcf-event

Ruby

No Ruby, o framework de funções precisa ser adicionado às dependências da função para implantá-lo no Cloud Functions:

bundle add functions_framework

PHP

composer require google/cloud-functions-framework

Configurar o Functions Framework

Antes de executar uma função usando o Functions Framework, primeiro é necessário especificar o tipo e o nome da função que você quer executar. Esses atributos podem ser especificados como sinalizações da interface de linha de comando (CLI) ou como variáveis de ambiente.

Tipos de função compatíveis

Coletivamente, o Functions Framework é compatível com os três tipos de funções compatíveis com o Cloud Functions. Todos os ambientes de execução de linguagem são compatíveis com http e event ou cloudevent.

Tipo de função Tipo de assinatura Descrição Ambientes de execução compatíveis
Funções acionadas por HTTP http Funções que recebem e respondem a solicitações HTTP. Todos os ambientes de execução
Funções em segundo plano event Formato de evento específico do Cloud Functions Somente 1ª geração: Node.js, Python, Go, Java
Funções do CloudEvents cloudevent Formato de evento padrão do setor 2ª geração: todos os ambientes de execução
1ª geração: .NET, Ruby, PHP

Especificar qual função será executada

Antes de executar uma função com o Functions Framework, primeiro é preciso especificar qual função do código será executada. Para a maioria das linguagens, é possível especificar o nome do método da função de destino, conforme mostrado nas tabelas abaixo. As exceções a essa regra, como Java e .NET, também são mostradas abaixo.

Instruções por linguagem

Consulte a tabela abaixo para ver uma lista de opções de configuração compatíveis com cada linguagem.

Node.js

Argumento da CLI Variável de ambiente Descrição
--port PORT A porta para detectar solicitações. Padrão: 8080.
--target FUNCTION_TARGET O nome da função export que será invocada. (Padrão: function)
--signature-type FUNCTION_SIGNATURE_TYPE O tipo de assinatura usado pela função. Pode ser http (padrão), event ou cloudevent.

Python

Argumento da CLI Variável de ambiente Descrição
--port PORT A porta para detectar solicitações. Padrão: 8080.
--target FUNCTION_TARGET O nome da função export que será invocada. (Padrão: function)
--signature-type FUNCTION_SIGNATURE_TYPE O tipo de assinatura usado pela função. Pode ser http (padrão), event ou cloudevent.

Go

Variável de ambiente Descrição
PORT A porta para detectar solicitações. Padrão: 8080.

Java

Nome do argumento Variável de ambiente Descrição
run.port PORT A porta para detectar solicitações. Padrão: 8080.
run.functionTarget FUNCTION_TARGET O nome da função export que será invocada. (Padrão: function)

C#

Argumento da CLI Variável de ambiente Descrição
--port PORT A porta para detectar solicitações. Padrão: 8080.
--target (ou apenas argumento) FUNCTION_TARGET O classname da função a ser invocada. (Padrão: function)

Ruby

Argumento da CLI Variável de ambiente Descrição
--port PORT A porta para detectar solicitações. Padrão: 8080.
--target FUNCTION_TARGET O nome da função export que será invocada. (Padrão: function)

PHP

Variável de ambiente Descrição
FUNCTION_TARGET O nome da função que será invocada. (Padrão: function)
FUNCTION_SIGNATURE_TYPE O tipo de assinatura usado pela função. Pode ser http (padrão), event ou cloudevent.

Siga as instruções abaixo para configurar e executar o Functions Framework:

Node.js

Com o Functions Framework para Node.js, é possível especificar o tipo de assinatura e de nome da função como argumentos de linha de comando ou variáveis de ambiente.

Também é possível especificar esses valores no arquivo de build package.json adicionando um script start com os argumentos da CLI necessários, como mostrado no exemplo abaixo.

"scripts": {
  "start": "npx functions-framework --target=YOUR_FUNCTION_NAME [--signature-type=YOUR_SIGNATURE_TYPE]"
}

Substitua YOUR_FUNCTION_NAME pelo nome do método da função e YOUR_SIGNATURE_TYPE (se aplicável) pelo tipo de assinatura da função, conforme mostrado na tabela acima.

Python

Com o Functions Framework para Python, é possível especificar o tipo de assinatura e de nome da função como argumentos de linha de comando ou variáveis de ambiente. Os argumentos de linha de comando precisam ser especificados ao executar o framework.

Go

O Functions Framework para Go usa funcframework.RegisterHTTPFunctionContext para especificar o destino e o tipo de assinatura da função.

Java

O Functions Framework para Java aceita dados de configuração de três fontes diferentes, na seguinte ordem de prioridade (do mais específico para o menos específico):

  • Argumentos de linha de comando
  • Arquivos de build
  • Variáveis de ambiente

Argumentos de linha de comando

Maven

É possível especificar a função que você quer executar adicionando a seguinte sinalização de interface de linha de comando (CLI, na sigla em inglês) aos comandos mvn:

-Drun.functionTarget=YOUR_FUNCTION_NAME

Também é possível especificar a porta de destino adicionando a seguinte sinalização CLI de maneira semelhante:

-Drun.port=12345

Gradle

As sinalizações da CLI do Gradle são quase idênticas às do Maven. A única mudança que o Gradle faz é trocar o -D inicial em cada sinalização por um -P, conforme mostrado no exemplo abaixo.

# Maven version
-Drun.functionTarget=...

# Gradle version
-Prun.functionTarget=...

Arquivos de build

Também é possível especificar a função que você quer executar no arquivo de build do projeto. Embora o Maven e o Gradle tenham sinalizações de CLI semelhantes, as cláusulas de arquivo de build são significativamente diferentes.

Maven

Os arquivos de build do Maven são chamados pom.xml. Adicione a seguinte cláusula a esse arquivo para especificar uma função de destino:

<plugin>
  <groupId>com.google.cloud.functions</groupId>
  <artifactId>function-maven-plugin</artifactId>
  <version>0.11.0</version>
  <configuration>
    <functionTarget>functions.HelloWorld</functionTarget>
  </configuration>
</plugin>

Substitua <functionTarget> pelo nome de classe da função. (Por exemplo, uma função no pacote functions com o nome de classe HelloCloudFunctions teria um nome de classe functions.HelloCloudFunctions. Ele é relativo ao arquivo de build pai pom.xml ou build.gradle).

Gradle

Os arquivos de build do Gradle são chamados de build.gradle. Adicione a cláusula a seguir a esse arquivo para especificar uma função de destino:

// Register a "runFunction" task to run the function locally
tasks.register("runFunction", JavaExec) {
  main = 'com.google.cloud.functions.invoker.runner.Invoker'
  classpath(configurations.invoker)
  inputs.files(configurations.runtimeClasspath, sourceSets.main.output)
  args(
    '--target', project.findProperty('run.functionTarget') ?: '',
    '--port', project.findProperty('run.port') ?: 8080
  )
  doFirst {
    args('--classpath', files(configurations.runtimeClasspath, sourceSets.main.output).asPath)
  }
}

C#

Se você criar um projeto usando dotnet new e um dos modelos especificados acima, o Function Frameworks para .NET detectará automaticamente a função.

Se o projeto tiver várias funções, consulte a seção Como executar o framework para informações sobre como executar uma função específica.

Ruby

Com o Functions Framework para Ruby, é possível especificar o tipo de assinatura e de nome da função como argumentos de linha de comando ou variáveis de ambiente. Os argumentos de linha de comando precisam ser especificados ao executar o framework.

PHP

Com o framework de funções do PHP, você pode especificar variáveis de ambiente como argumentos de linha de comando.

Também é possível especificar esses valores no arquivo de build composer.json adicionando um script start, como mostrado no exemplo abaixo.

"scripts": {
   "start": [
       "Composer\\Config::disableProcessTimeout",
       "FUNCTION_TARGET=YOUR_FUNCTION_NAME php -S localhost:${PORT:-8080} vendor/bin/router.php"
    ]
}

Substitua YOUR_FUNCTION_NAME pelo nome da função e YOUR_SIGNATURE_TYPE (se aplicável) pelo tipo de assinatura da função, conforme mostrado na tabela acima.

Executar o Functions Framework

Use o comando a seguir para executar a função com o Functions Framework. Por padrão, a função estará acessível em localhost:8080, a menos que você especifique explicitamente um valor PORT.

Node.js

npm start

Python

functions-framework --target=YOUR_FUNCTION_NAME

Substitua YOUR_FUNCTION_NAME pelo nome de método da função.

Go

cd cmd
go build
./cmd

Java

Maven

Use o seguinte comando para executar uma função especificada em pom.xml:

mvn function:run

Use o seguinte comando para executar uma função especificada em um argumento da linha de comando:

mvn function:run -Drun.functionTarget=YOUR_FUNCTION_NAME

Substitua YOUR_FUNCTION_NAME pelo nome de classe da função.

Gradle

Use o seguinte comando para executar uma função especificada em build.gradle:

./gradlew runFunction

Use o seguinte comando para executar uma função especificada em um argumento da linha de comando:

./gradlew runFunction -Prun.functionTarget=YOUR_FUNCTION_NAME

Substitua YOUR_FUNCTION_NAME pelo nome de classe da função.

C#

Use o seguinte comando para executar a função quando exatamente uma função estiver presente no projeto atual do .NET. Essa é a estrutura padrão para projetos criados por modelos.

dotnet run

Caso o projeto .NET contenha várias funções, use o seguinte comando para executar uma função específica. Substitua YOUR_FUNCTION_CLASSNAME pelo nome de classe da função, incluindo o namespace.

dotnet run YOUR_FUNCTION_CLASSNAME

Se você quiser executar várias funções simultaneamente, precisará executar várias instâncias do Functions Framework. Para evitar conflitos entre instâncias de framework em execução, cada instância precisa usar um valor PORT diferente. O comando a seguir mostra como executar uma função com um valor PORT de 8080.

dotnet run --target YOUR_FUNCTION_CLASSNAME --port 8080

Ruby

bundle exec functions-framework-ruby --target YOUR_FUNCTION_NAME

Substitua YOUR_FUNCTION_NAME pelo nome de método da função.

PHP

export FUNCTION_TARGET=YOUR_FUNCTION_NAME
php -S localhost:8080 vendor/bin/router.php

Substitua YOUR_FUNCTION_NAME pelo nome da função.

Chamar sua função

Consulte a página Como chamar funções locais para saber como interagir com a função executada localmente.

Limpar

Quando terminar de executar a função, interrompa a instância do framework em execução pressionando Control+C.