编写函数

预览 — Cloud Run functions

此功能须遵守服务专用条款的“通用服务条款”部分中的“非正式版产品条款”。 非正式版功能“按原样”提供，可能只能获得有限的支持。 如需了解详情，请参阅发布阶段说明。

本页介绍了如何使用 Functions 框架编写函数。

为 Cloud Run 编写函数源代码时，您必须使用 Functions Framework，这是一个用于编写 Cloud Run 函数的开源库。借助 Functions 框架，您可以编写在 Cloud Run 和其他环境（包括本地开发机和基于 Knative 的环境）中运行的轻量级函数。

借助 Functions 框架，您可以：

• 调用函数以响应请求。
• 自动取消封送符合 CloudEvents 规范的事件，后者是一种以通用方式描述事件数据的行业标准规范。
• 启动本地开发服务器以实现快速测试。

使用 Functions 框架编写函数

Functions 框架提供了用于构建模块化服务的接口。如需在源代码中使用 Functions 框架，请指定以下内容：

• 入口点
• 签名类型

函数入口点

源代码必须为函数定义入口点，这是调用 Cloud Run 函数时执行的特定代码。您可以在部署函数时指定此入口点。

如何定义入口点取决于您使用的语言运行时。对于某些语言，入口点是函数，而对于另一些语言，入口点是类。

签名类型

使用 Functions 框架编写函数的源代码时，您必须指定以下两种签名类型之一：

• HTTP 函数：用于注册 HTTP 处理程序函数的函数。如需了解详情，请参阅编写 HTTP 函数。
• CloudEvents 函数（也称为事件驱动型函数）：用于注册 CloudEvents 处理程序函数的函数。如需了解详情，请参阅编写 CloudEvents 函数。

如果您需要函数具有网址端点并响应 HTTP 请求（例如针对 webhook），可使用 HTTP 函数。如果函数应直接触发以响应Google Cloud 项目中的事件（例如 Pub/Sub 主题中收到消息或 Cloud Storage 存储桶发生更改），可使用 CloudEvents 函数。

源目录结构

多种编程语言都支持 Functions 框架。您选择的语言运行时和您要编写的函数类型决定了如何设计代码结构并实现函数。

为了让 Cloud Run 能够找到函数定义，每个语言运行时都对构建源代码有一定的要求。

Node.js

Node.js 函数的基本目录结构如下：

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

默认情况下，Cloud Run 会尝试从函数目录的根目录中名为 index.js 的文件加载源代码。如需指定其他主源文件，请使用 package.json 文件中的 main 字段。

package.json 文件还必须包含 Node.js 版 Functions 框架作为依赖项：

{
  "main": "index.js",
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0"
  }
}

注意：您可以通过运行 npm install @google-cloud/functions-framework 来使用 npm 添加 Functions 框架依赖项。

主文件中的代码必须定义函数入口点，并且可以导入其他代码和 Node.js 模块。主文件还可以定义多个函数入口点，可单独进行部署。

如需了解详情，请参阅 Node.js 运行时概览和 适用于 Node.js 的 Functions 框架。

Python

Python 函数的基本目录结构如下：

.
├── main.py
└── requirements.txt

Cloud Run 会从函数目录的根目录中名为 main.py 的文件加载源代码。您必须将主文件命名为 main.py。

requirements.txt 文件必须包含 Python 版 Functions 框架作为依赖项：

functions-framework==3.*

main.py 文件中的代码必须定义函数入口点，并且可以照常导入其他代码和外部依赖项。main.py 文件还可以定义多个函数入口点，可单独进行部署。

如需了解详情，请参阅 Python 运行时概览和 适用于 Python 的 Functions 框架。

Go

Go 函数的基本目录结构如下：

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

您的函数必须位于项目根目录下的 Go 软件包中，软件包及其源文件可以采用任何名称，但函数不能位于 package main 中。如果您需要 main 软件包（例如用于本地测试），则可以在子目录中创建一个软件包：

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

go.mod 文件必须包含 Go 版 Functions 框架作为依赖项：

module example.com/my-module

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

注意：您可以通过运行 go get github.com/GoogleCloudPlatform/functions-framework-go 来添加 Functions 框架依赖项。

根软件包中的代码必须定义函数入口点，并且可以照常从子软件包和依赖项导入其他代码。软件包还可以定义多个函数入口点，可单独进行部署。

注意 ：如需查看如何在 Go 中设置基本 Cloud Run 项目的示例，请参阅 GitHub 上的 Go 版 Functions 框架快速入门。

如需了解详情，请参阅 Go 运行时概览和 适用于 Go 的 Functions 框架。

Java

Java 函数的基本目录结构如下：

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

Java 源文件必须位于 src/main/java/ 目录下，并且可以采用任何名称。如果源文件声明了软件包，请在 src/main/java 下添加一个额外的目录，其中包含软件包的名称：

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

我们建议将关联测试放在 src/test/java/ 子目录下。

注意：如果您要使用其他 JVM 语言（例如 Groovy、Kotlin 或 Scala），请将 java 目录重命名为相应语言的值（例如 groovy、kotlin 或 scala）。

pom.xml 文件必须包含 Java 版 Functions 框架作为依赖项：

...
    <dependency>
      <groupId>com.google.cloud.functions</groupId>
      <artifactId>functions-framework-api</artifactId>
      <version>1.0.4</version>
    </dependency>
...

源文件中的代码必须定义函数入口点，并且可以照常导入其他代码和外部依赖项。源文件还可以定义多个函数入口点，可单独进行部署。

如需了解详情，请参阅 Java 运行时概览和 适用于 Java 的 Functions 框架。

.NET

.NET 函数的基本目录结构如下：

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

您可以像设计任何其他 .NET 源代码结构一样设计您的项目的结构。源文件可以采用任何名称。

注意：如果您使用 F# 或 Visual Basic，则遵循相同的模式，但添加相应的文件扩展名（对于 F# 为 .fs 和 .fsproj，对于 Visual Basic 为 .vb 和 .vbproj）。

您的项目文件必须包含 .NET 版 Functions 框架作为依赖项：

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

源文件中的代码必须定义函数入口点，并且可以照常导入其他代码和外部依赖项。源文件还可以定义多个函数入口点，可单独进行部署。

注意 ：如需了解与使用多个本地 .NET 项目的函数相关的文件结构，请参阅部署具有本地项目依赖项的函数。

如需了解详情，请参阅 .NET 运行时概览和 适用于 .NET 的 Functions 框架。

Ruby

Ruby 函数的基本目录结构如下：

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

Cloud Run 会从函数目录的根目录中名为 app.rb 的文件加载源代码。主文件必须命名为 app.rb。

Gemfile 文件必须包含 Ruby 版 Functions 框架作为依赖项：

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

注意：您可以通过运行 bundle add functions_framework 来使用 Bundler 添加 Functions 框架依赖项。

app.rb 文件中的代码必须定义函数入口点，并且可以照常导入其他代码和外部依赖项。app.rb 文件还可以定义多个函数入口点，可单独进行部署。

如需了解详情，请参阅 Ruby 运行时概览和 适用于 Ruby 的 Functions 框架。

PHP

PHP 函数的基本目录结构如下：

.
├── index.php
└── composer.json

Cloud Run 会从函数目录的根目录中名为 index.php 的文件加载源代码。您必须将主文件命名为 index.php。

composer.json 文件必须包含 PHP 版 Functions 框架作为依赖项：

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

注意：您可以通过运行 composer require google/cloud-functions-framework 来使用 Composer 添加 Functions 框架依赖项。

index.php 文件中的代码必须定义函数入口点，并且可以照常导入其他代码和外部依赖项。index.php 文件还可以定义多个函数入口点，可单独进行部署。

如需了解详情，请参阅 PHP 运行时概览和 PHP 版 Functions 框架。

如果您将多个函数分组到单个项目中，请注意每个函数最终可能共享同一组依赖项。但是，某些函数可能并不需要所有依赖项。

我们建议您尽可能拆分大型多函数代码库，并将每个函数放入各自的顶层目录中（如前面的示例所示），其中包含各自的源文件和项目配置文件。此方法可最大限度地减少特定函数所需的依赖项数量，进而减少函数所需的内存量。

后续步骤

• 实现 HTTP 函数
• 实现 CloudEvents 函数
• 了解 Functions 框架合同