Executar funções com o Functions Framework

Observação: este conteúdo se aplica apenas às funções do Cloud Run (1a geração), anteriormente Cloud Functions (1a geração). Consulte Executar funções com o Functions Framework do Cloud Run fuctions (anteriormente versão Cloud Functions (2ª geração)) deste documento.

O Cloud Run 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.

Observação: se você estiver interessado em criar contêineres que podem ser executados localmente, consulte Como usar o emulador do Functions.

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

Observação: essa biblioteca será incluída automaticamente ao implantar a função se você não a especificar nas dependências da função.

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

Python

Observação: essa biblioteca será incluída automaticamente ao implantar a função se você não a especificar nas dependências da função.

pip install functions-framework

Go

Observação: essa biblioteca será incluída automaticamente ao implantar a função se você não a especificar nas dependências da função.

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

Java

Observação: essa biblioteca será incluída automaticamente ao implantar a função se você não a especificar nas dependências da função.

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 Run 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 Functions Framework deve ser adicionado às dependências da função para implantá-lo no Cloud Run functions:

bundle add functions_framework

PHP

Observação: essa biblioteca será incluída automaticamente ao implantar a função se você não a especificar nas dependências da função.

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

O Functions Framework oferece aceita os três tipos de funções do Cloud Run functions de 1a geração. Todos os ambientes de execução da 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 Run functions	Node.js, Python, Go, Java
Funções do CloudEvent	cloudevent	Formato de evento padrão do setor	.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.

Observação: o Functions Framework para Go detecta automaticamente o tipo de assinatura da função.

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)

Observação: o Java Functions Framework detecta automaticamente o tipo de assinatura da função.

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)

Observação: o Functions Framework para .NET detecta automaticamente o tipo de assinatura da função.

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.

Observação: os argumentos de linha de comando têm precedência sobre as variáveis de ambiente ao executar o Function Frameworks para Node.js.

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]"
}

Faça o mesmo usando variáveis de ambiente:

"scripts": {
  "start": "FUNCTION_TARGET=YOUR_FUNCTION_NAME FUNCTION_SIGNATURE_TYPE=YOUR_SIGNATURE_TYPE npx functions-framework"
}

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.

Observação: os argumentos de linha de comando têm precedência sobre as variáveis de ambiente ao executar o Function Frameworks para Python.

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.

Observação: os argumentos de linha de comando têm precedência sobre as variáveis de ambiente ao executar o Function Frameworks para Ruby.

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

Como usar argumentos de linha de comando:

functions-framework --target=YOUR_FUNCTION_NAME

Como usar variáveis de ambiente:

FUNCTION_TARGET=YOUR_FUNCTION_NAME functions-framework

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

Go

Observação: primeiro crie um arquivo cmd/main.go conforme descrito no site do Framework do Functions para Go.

cd cmd
go build
./cmd

Como usar variáveis de ambiente:

cd cmd
go build
PORT=8080 ./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

Use o seguinte comando para executar uma função especificada como uma variável de ambiente:

FUNCTION_TARGET=YOUR_FUNCTION_NAME mvn function:run

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

Use o seguinte comando para executar uma função especificada como uma variável de ambiente:

FUNCTION_TARGET=YOUR_FUNCTION_NAME ./gradlew runFunction

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

Observação: o ambiente de execução do .NET detecta funções pesquisando classes que implementam uma das interfaces do Functions Framework (IHttpFunction ou ICloudEventFunction).

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.

Como usar argumentos de linha de comando:

dotnet run --target YOUR_FUNCTION_CLASSNAME --port 8080

Como usar variáveis de ambiente:

FUNCTION_TARGET=YOUR_FUNCTION_CLASSNAME PORT=8080 dotnet run

Ruby

Como usar argumentos de linha de comando:

bundle exec functions-framework-ruby --target YOUR_FUNCTION_NAME

Como usar variáveis de ambiente:

FUNCTION_TARGET=YOUR_FUNCTION_NAME bundle exec functions-framework-ruby

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.