使用 Functions 框架运行函数

注意：此内容仅适用于 Cloud Run functions（第 1 代），即原 Cloud Functions（第 1 代）。 如需了解本文档的 Cloud Run functions (第 2 代)（原 Cloud Functions [第 2 代]）版本，请参阅使用 Functions 框架运行函数。

Cloud Run 函数使用开源的 Functions 框架库将部署的函数封装在永久性 HTTP 应用中。

Functions 框架还可以在支持语言本身的任何其他平台（包括本地机器、本地服务器、Compute Engine 和 Cloud Run）上运行。

注意：如果您想要构建可在本地运行的容器，请参阅使用 Functions 模拟器。

安装依赖项

在函数的目录中，安装您所用语言的 Cloud Functions 框架库：

如需了解详情，请参阅 Java Functions 框架库。

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

如果您使用的是 Maven，请将以下代码添加到您的 pom.xml 文件中：

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

Gradle

如果您使用的是 Gradle，请将以下代码添加到您的 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#

以下命令使用 .NET 模板以 .NET Functions 框架库作为依赖项创建新的 .NET Cloud Run functions 函数代码库：

# HTTP functions
dotnet new gcf-http

# CloudEvent functions
dotnet new gcf-event

Ruby

在 Ruby 中，Functions 框架必须添加到函数的依赖项中，以便将其部署到 Cloud Run functions：

bundle add functions_framework

PHP

注意：如果您未在函数的依赖项中指定此库，系统会自动包含此库。

composer require google/cloud-functions-framework

配置 Functions 框架

在使用 Functions 框架运行函数之前，您需要先指定要运行的函数的类型和名称。这些特性可指定为命令行界面 (CLI) 标志或环境变量。

支持的函数类型

Functions 框架支持 Cloud Run 函数第 1 代支持的全部三种类型的函数。所有语言运行时都支持 http 以及 event 或 cloudevent 之一。

函数类型	签名类型	说明	支持运行时
HTTP 触发的函数	http	接收和响应 HTTP 请求的函数。	所有运行时
后台函数	event	特定于 Cloud Run 函数的事件格式	Node.js、Python、Go、Java
CloudEvent 函数	cloudevent	业界标准的事件格式	.NET、Ruby、PHP

指定要运行的函数

在使用 Functions 框架运行函数之前，您必须先指定应在代码中运行的函数。对于大多数语言，您可以如下表所示指定目标函数的方法名称来执行此操作。（下面还显示了此规则的例外情况，例如 Java 和 .NET。）

针对每种语言的说明

如需查看每种语言所支持的配置选项列表，请参阅下表。

Node.js

CLI 参数	环境变量	说明
--port	PORT	要侦听请求的端口。（默认值：8080）
--target	FUNCTION_TARGET	要调用的 export 函数的名称。（默认值：function）
--signature-type	FUNCTION_SIGNATURE_TYPE	函数使用的签名类型。可以是 http（默认值）、event 或 cloudevent 之一。

Python

CLI 参数	环境变量	说明
--port	PORT	要侦听请求的端口。（默认值：8080）
--target	FUNCTION_TARGET	要调用的 export 函数的名称。（默认值：function）
--signature-type	FUNCTION_SIGNATURE_TYPE	函数使用的签名类型。可以是 http（默认值）、event 或 cloudevent 之一。

Go

环境变量	说明
PORT	要侦听请求的端口。（默认值：8080）

注意：Go Functions 框架会自动检测函数的签名类型。

Java

参数名称	环境变量	说明
run.port	PORT	要侦听请求的端口。（默认值：8080）
run.functionTarget	FUNCTION_TARGET	要调用的 export 函数的名称。（默认值：function）

注意：Java Functions 框架会自动检测函数的签名类型。

C#

CLI 参数	环境变量	说明
--port	PORT	要侦听请求的端口。（默认值：8080）
--target（或仅参数）	FUNCTION_TARGET	要调用的函数的类名称classname。（默认值：function）

注意：.NET Functions 框架会自动检测函数的签名类型。

Ruby

CLI 参数	环境变量	说明
--port	PORT	要侦听请求的端口。（默认值：8080）
--target	FUNCTION_TARGET	要调用的 export 函数的名称。（默认值：function）

PHP

环境变量	说明
FUNCTION_TARGET	要调用的函数的名称。（默认值：function）
FUNCTION_SIGNATURE_TYPE	函数使用的签名类型。可以是 http（默认值）、event 或 cloudevent 之一。

请按照以下说明配置并运行 Functions 框架：

Node.js

借助 Node.js Functions 框架，您可以将函数的名称和签名类型指定为命令行参数或环境变量。

注意：运行 Node.js Functions 框架时，命令行参数的优先级高于环境变量。

您还可以通过添加带有必需 CLI 参数的 start 脚本，在 package.json 构建文件中指定这些值，如以下示例所示。

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

您也可以使用环境变量执行相同的操作：

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

如上表所示，将 YOUR_FUNCTION_NAME 替换为函数的方法名称，并将 YOUR_SIGNATURE_TYPE（如果适用）替换为函数的签名类型。

Python

借助 Python Functions 框架，您可以将函数的名称和签名类型指定为命令行参数或环境变量。在运行框架时必须指定命令行参数。

注意：运行 Python Functions 框架时，命令行参数的优先级高于环境变量。

Go

Go Functions 框架使用 funcframework.RegisterHTTPFunctionContext 指定函数目标和签名类型。

Java

Java Functions 框架按以下优先级顺序（从最具体到最宽泛）接受来自三种不同来源的配置数据：

• 命令行参数
• 构建文件
• 环境变量

命令行参数

Maven

您可以通过向 mvn 命令添加以下命令行界面 (CLI) 标志来指定要运行的函数：

-Drun.functionTarget=YOUR_FUNCTION_NAME

您还可以通过类似方式添加以下 CLI 标志来指定目标端口：

-Drun.port=12345

Gradle

Gradle 的 CLI 标志与 Maven 的 CLI 标志几乎完全相同。Gradle 唯一所做的更改是将每个标志中的前导 -D 替换为 -P，如以下示例所示：

# Maven version
-Drun.functionTarget=...

# Gradle version
-Prun.functionTarget=...

构建文件

您还可以指定要在项目的构建文件中运行的函数。虽然 Maven 和 Gradle 的 CLI 标志类似，但其构建文件子句有显著的区别。

Maven

Maven 构建文件命名为 pom.xml。将以下子句添加到该文件可指定目标函数：

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

将 <functionTarget> 替换为函数的类名称。（例如，functions 包中类名称为 HelloCloudFunctions 的函数将有一个类名称 functions.HelloCloudFunctions。它相对于父级构建文件 - pom.xml 或 build.gradle。）

Gradle

Gradle 构建文件命名为 build.gradle。将以下子句添加到该文件可指定目标函数：

// 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#

如果您使用 dotnet new 和上面指定的模板之一创建项目，则 .NET Functions 框架将自动检测函数。

如果您的项目包含多个函数，请参阅运行框架部分，了解如何运行特定函数。

Ruby

借助 Ruby Cloud Functions 框架，您可以将函数的名称和签名类型指定为命令行参数或环境变量。在运行框架时必须指定命令行参数。

注意：运行 Ruby Cloud Functions 框架时，命令行参数的优先级高于环境变量。

PHP

PHP Cloud Functions 框架允许您将环境变量指定为命令行参数。

您还可以通过添加 start 脚本在 composer.json 构建文件中指定这些值，如以下示例所示。

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

将 YOUR_FUNCTION_NAME 替换为您的函数名称，并将 YOUR_SIGNATURE_TYPE（如果适用）替换为您的函数的签名类型，如上表所示。

运行 Functions 框架

使用以下命令可以通过 Functions 框架运行函数。默认情况下，除非您明确指定 PORT 值，否则可通过 localhost:8080 访问函数。

Node.js

npm start

Python

使用命令行参数：

functions-framework --target=YOUR_FUNCTION_NAME

使用环境变量：

FUNCTION_TARGET=YOUR_FUNCTION_NAME functions-framework

将 YOUR_FUNCTION_NAME 替换为函数的方法名称。

Go

注意：请先按照 Go 版 Functions 框架网站中的说明创建 cmd/main.go 文件。

cd cmd
go build
./cmd

使用环境变量：

cd cmd
go build
PORT=8080 ./cmd

Java

Maven

使用以下命令可运行 pom.xml 中指定的函数：

mvn function:run

使用以下命令可运行命令行参数中指定的函数：

mvn function:run -Drun.functionTarget=YOUR_FUNCTION_NAME

使用以下命令运行作为环境变量指定的函数：

FUNCTION_TARGET=YOUR_FUNCTION_NAME mvn function:run

将 YOUR_FUNCTION_NAME 替换为函数的类名称。

Gradle

使用以下命令可运行 build.gradle 中指定的函数：

./gradlew runFunction

使用以下命令可运行命令行参数中指定的函数：

./gradlew runFunction -Prun.functionTarget=YOUR_FUNCTION_NAME

使用以下命令运行作为环境变量指定的函数：

FUNCTION_TARGET=YOUR_FUNCTION_NAME ./gradlew runFunction

将 YOUR_FUNCTION_NAME 替换为函数的类名称。

C#

如果当前 .NET 项目中只存在一个函数，则使用以下命令可运行函数。（这是使用模板创建的项目的默认结构。）

dotnet run

注意：.NET 运行时通过搜索实现其中一个 Functions 框架接口（IHttpFunction 或 ICloudEventFunction）的类来检测函数。

如果 .NET 项目包含多个函数，请使用以下命令运行特定函数。将 YOUR_FUNCTION_CLASSNAME 替换为函数的类名称，包括命名空间。

dotnet run YOUR_FUNCTION_CLASSNAME

如果您要同时运行多个函数，则需要运行多个 Functions 框架实例。为避免正在运行的框架实例之间发生冲突，每个实例应使用不同的 PORT 值。以下命令展示了如何使用值为 8080 的 PORT 运行函数。

使用命令行参数：

dotnet run --target YOUR_FUNCTION_CLASSNAME --port 8080

使用环境变量：

FUNCTION_TARGET=YOUR_FUNCTION_CLASSNAME PORT=8080 dotnet run

Ruby

使用命令行参数：

bundle exec functions-framework-ruby --target YOUR_FUNCTION_NAME

使用环境变量：

FUNCTION_TARGET=YOUR_FUNCTION_NAME bundle exec functions-framework-ruby

将 YOUR_FUNCTION_NAME 替换为函数的方法名称。

PHP

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

将 YOUR_FUNCTION_NAME 替换为函数的名称。

调用函数

如需了解如何与本地运行的函数进行交互，请参阅调用本地函数页面。

清理

函数运行完毕后，可以按 Ctrl+C 停止正在运行的框架实例。