編寫 Cloud Run 函式

本頁面將介紹如何使用 Functions Framework 編寫 Cloud Run 函式。

編寫函式原始碼時，您必須使用 Functions Framework，這是用於編寫 Cloud Run 函式的開放原始碼程式庫。透過 Functions Framework，您可以編寫簡易函式，並在 Cloud Run 和其他環境中執行，包括本機開發機器和以 Knative 為基礎的環境。

Functions Framework 可讓您執行下列操作：

• 呼叫 Cloud Run 函式以回應要求。
• 自動將符合 CloudEvents 規格的事件解除封送，這是一種業界標準規格，可用於以常用方式描述事件資料。
• 啟動本機開發伺服器以快速進行測試。

使用 Functions Framework 編寫函式

Functions 架構提供建構模組化服務的介面。如要在原始碼中使用函式架構，請指定下列項目：

• 進入點
• 簽章類型

函式進入點

原始碼必須定義函式的進入點，也就是在叫用 Cloud Run 函式時執行的特定程式碼。您可以在部署函式時指定這個進入點。

定義進入點的方式取決於您使用的語言執行階段。有些語言會使用函式做為進入點，有些則會使用類別。

簽章類型

使用函式架構編寫函式的原始碼時，您必須指定下列兩種簽名類型之一：

• HTTP 函式：註冊 HTTP 處理常式函式的函式。詳情請參閱「編寫 HTTP 函式」。
• 事件導向函式 (也稱為 CloudEvents 函式)：用於註冊 CloudEvents 處理常式函式的函式。詳情請參閱「編寫事件導向函式」。

當您需要函式具備網址端點，並回應 HTTP 要求 (例如 webhook) 時，請使用 HTTP 函式。當函式應直接觸發，以回應 Google Cloud 專案中的事件 (例如 Pub/Sub 主題上的訊息或 Cloud Storage 值區中的變更) 時，請使用事件驅動函式。

來源目錄結構

多種程式設計語言都支援 Functions 架構。您選擇的語言執行階段和要編寫的函式類型，會決定程式碼的結構和函式實作方式。

為了讓 Cloud Run 找出函式定義，每個語言執行階段都對原始碼的結構有相關規定。

Node.js

Node.js 函式的基本目錄結構如下：

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

根據預設，Cloud Run 會嘗試從函式目錄根目錄中名為 index.js 的檔案載入原始碼。如要指定不同的主要來源檔案，請在 package.json 檔案中使用 main 欄位。

package.json 檔案也必須將 Node.js 的 Functions Framework 納入依附元件：

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

注意： 您可以執行 npm install @google-cloud/functions-framework，透過 npm 新增 Functions Framework 依附元件。

主檔案中的程式碼必須定義函式進入點，並可匯入其他程式碼和 Node.js 模組。主檔案也可以定義多個可個別部署的函式進入點。

詳情請參閱 Node.js 執行階段總覽和 Node.js 專用 Functions Framework。

Python

Python 函式的目錄結構如下：

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

Cloud Run 會從函式目錄根目錄中名為 main.py 的檔案載入原始碼。您必須將主要檔案命名為 main.py。

requirements.txt 檔案必須將 Python 的 Functions Framework 納入依附元件：

functions-framework==3.*

main.py 檔案中的程式碼必須定義函式進入點，並能正常匯入其他程式碼和外部依附元件。main.py 檔案也可以定義多個可個別部署的函式進入點。

詳情請參閱 Python 執行階段總覽和 Python 的函式架構。

Go

Go 函式的目錄結構如下：

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

您的函式必須位於專案根目錄中的 Go 套件中。套件及其來源檔案可以有任何名稱，但函式不得位於 package main 中。如果您需要 main 套件 (例如用於本機測試)，可以在子目錄中建立一個：

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

go.mod 檔案必須將 Go 的 Functions Framework 納入依附元件：

module example.com/my-module

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

注意： 您可以執行 go get github.com/GoogleCloudPlatform/functions-framework-go 來新增 Functions Framework 依附元件。

根套件中的程式碼必須定義函式進入點，並能正常匯入子套件和依附元件的其他程式碼。您的套件也可以定義多個可個別部署的函式進入點。

注意： 如需在 Go 中設定基本 Cloud Run 專案的範例，請參閱 GitHub 上的 Go 適用的 Functions Framework 快速入門。

詳情請參閱 Go 執行階段總覽和 Go 函式架構。

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 Framework 納入依附元件：

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

原始檔案中的程式碼必須定義函式進入點，並能正常匯入其他程式碼和外部依附元件。來源檔案也可以定義多個可個別部署的函式進入點。

詳情請參閱 Java 執行階段總覽和 Java 專用函式架構。

.NET

.NET 函式的基本目錄結構如下：

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

您可以按照任何其他 .NET 原始碼的做法來建構專案。來源檔案可以使用任何名稱。

注意： 如果您使用 F# 或 Visual Basic，但使用適當的檔案副檔名 (.fs 和 .fsproj 適用於 F#，.vb 和 .vbproj 適用於 Visual Basic)，則適用相同的模式。

專案檔案必須納入 .NET 的 Functions Framework 做為依附元件：

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

原始檔案中的程式碼必須定義函式進入點，並能正常匯入其他程式碼和外部依附元件。來源檔案也可以定義多個可個別部署的函式進入點。

注意： 如要瞭解與使用多個本機 .NET 專案的函式相關的檔案結構，請參閱「部署具有本機專案依附元件的函式」。

詳情請參閱 .NET 執行階段總覽和 .NET 的函式架構。

Ruby

Ruby 函式的基本目錄結構如下：

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

Cloud Run 會從函式目錄根目錄中名為 app.rb 的檔案載入原始碼。主要檔案必須命名為 app.rb。

Gemfile 檔案必須將 Functions Framework for Ruby 納入依附元件：

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

注意： 您可以執行 bundle add functions_framework，透過Bundler 新增 Functions Framework 依附元件。

app.rb 檔案中的程式碼必須定義函式進入點，並能正常匯入其他程式碼和外部依附元件。app.rb 檔案也可以定義多個可個別部署的函式進入點。

詳情請參閱 Ruby 執行階段總覽和 Ruby 的 Functions 架構。

PHP

PHP 函式的基本目錄結構如下：

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

Cloud Run 會從函式目錄根目錄中名為 index.php 的檔案載入原始碼。您必須將主要檔案命名為 index.php。

composer.json 檔案必須將 PHP 的函式架構設為依附元件：

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

注意： 您可以執行 composer require google/cloud-functions-framework，藉由Composer 新增 Functions Framework 依附元件。

index.php 檔案中的程式碼必須定義函式進入點，並能正常匯入其他程式碼和外部依附元件。index.php 檔案也可以定義多個可個別部署的函式進入點。

詳情請參閱 PHP 執行階段總覽和 PHP 函式架構。

如果將多個函式分組至單一專案，請注意，每個函式可能都會共用相同的依附元件組合。不過，部分函式可能不需要所有依附元件。

建議您盡可能分割大型多函式程式碼集，並將每個函式放在各自的頂層目錄中，如上述範例所示，並搭配各自的原始碼和專案設定檔。這種做法可盡量減少特定函式所需的依附元件數量，進而減少函式所需的記憶體量。

後續步驟

• 實作 HTTP 函式
• 實作事件導向函式
• 瞭解 Functions Framework 合約