如果您要建立新函式，請參閱 Cloud Run 的控制台快速入門。本頁內容僅適用於使用 Cloud Functions 第 1 版 API 建立的現有舊版函式。

本頁面由 Cloud Translation API 翻譯而成。

編寫事件導向函式

在 Cloud Run 函式中，如果您希望函式能自動叫用，以回應雲端環境中發生的事件，就應使用事件驅動函式。

實作事件驅動函式的做法有兩種。您可以使用哪種方式取決於所選語言的執行階段：

如果是 Node.js、Python、Go 和 Java 執行階段，請使用背景函式。
如果是 .NET、Ruby 和 PHP 執行階段，請使用 CloudEvent 函式。

CloudEvent 函式

CloudEvent 函式是根據 CloudEvents 建立，這是業界標準規格，可用來以常見方式描述事件資料。如要進一步瞭解 CloudEvents 規格，請前往 CloudEvents GitHub 存放區。CloudEvents 專案也提供一組 CloudEvents SDK，協助您在程式碼中使用 CloudEvents 物件。

以下範例顯示每個執行階段的基本 CloudEvent 函式來源檔案。如要瞭解原始碼的位置，請參閱「來源目錄結構」。

C#

using CloudNative.CloudEvents;
using Google.Cloud.Functions.Framework;
using System.Threading;
using System.Threading.Tasks;

namespace MyProject
{
    // Define a class that implements the ICloudEventFunction<T> interface
    public class MyCloudEventFunction : ICloudEventFunction<CloudEventDataType>
    {
        // Implement the HandleAsync() method to handle CloudEvents
        public Task HandleAsync(CloudEvent cloudEvent, CloudEventDataType data, CancellationToken cancellationToken)
        {
            // Your code here
            // The data argument represents the CloudEvent data payload

            // Signal function completion
            return Task.CompletedTask;
        }
    }
}

在 .NET 執行階段中，您可以使用 .NET 專用函式架構，透過 ICloudEventFunction<T> 介面實作 CloudEvent 處理常式類別。HandleAsync() 方法會接受 CloudEvent 物件和相關聯的 CloudEvent 資料酬載做為引數。

上例中顯示為 CloudEventDataType 的 CloudEvent 資料酬載引數類型，必須與函式處理的事件類型相符。Google CloudEvents .NET 程式庫提供 Google 支援的各種事件資料類型。

函式進入點是 CloudEvent 處理常式類別的完整名稱，包括命名空間。在這個範例中，進入點為 MyProject.MyCloudEventFunction。

Ruby

require "functions_framework"

# Register a CloudEvent function with the Functions Framework
FunctionsFramework.cloud_event "my_cloudevent_function" do |cloud_event|
  # Your code here
  # Access the CloudEvent data payload via cloud_event.data
end

在 Ruby 中，您可以使用 Ruby 版 Functions Framework 註冊 CloudEvent 處理常式函式。處理常式函式必須接受 CloudEvents Event 物件做為引數。

函式進入點是處理常式向 Functions Framework 註冊時使用的名稱。在這個範例中，進入點為 my_cloudevent_function。

PHP

<?php

use CloudEvents\V1\CloudEventInterface;
use Google\CloudFunctions\FunctionsFramework;

// Register a CloudEvent function with the Functions Framework
FunctionsFramework::cloudEvent('myCloudEventFunction', 'myCloudEventHandler');

// Define your CloudEvent handler
function myCloudEventHandler(CloudEventInterface $event): void
{
    // Your code here
    // Access the CloudEvent data payload via $event->getData()
}

在 PHP 中，您可以使用 PHP 版 Functions Framework 註冊 CloudEvent 處理常式函式。處理常式函式必須接受符合 CloudEventInterface 介面的引數。

函式進入點是處理常式向 Functions Framework 註冊時使用的名稱。在這個範例中，進入點為 myCloudEventFunction。

針對 CloudEvent 函式，事件資料會以 CloudEvents 格式傳遞至函式，其中 CloudEvent 資料酬載會對應至觸發函式的事件類型。如要瞭解支援的觸發條件、事件類型和相關事件資料格式，請參閱「Cloud Run 函式觸發條件」。

Google 事件存放區包含可用於處理 Google 發出的 CloudEvents 的資源。

背景函式

Node.js、Python、Go 和 Java 執行階段中的事件驅動函式會預期 CloudEvent 函式提供不同的引數。這種較舊的事件驅動函式類型稱為背景函式。

以下範例顯示每個執行階段的基本背景函式來源檔案。如要瞭解原始碼的位置，請參閱「來源目錄結構」。

Node.js

// Define and export an event handler
exports.myBackgroundFunction = (eventData, context, callback) => {
  // Your code here
  // The eventData argument represents the event data payload

  // Optionally signal function completion:
  callback();
};

在 Node.js 中，您會定義並匯出處理事件資料的函式。Cloud Run 函式會將下列引數傳遞至處理常式：

eventData：代表事件資料酬載的物件。格式取決於事件類型。
context：物件，其中包含事件的中繼資料。
callback：您可以呼叫的選用函式，用於表示完成。這個回呼的第一個引數會解讀為信號錯誤。傳遞無引數或 null 第一個引數，以表示成功。

函式進入點是匯出事件處理常式的名稱。在這個範例中，進入點為 myBackgroundFunction。

Python

# Define an event handler
def my_background_function(event_data, context):
  # Your code here
  # The event_data argument represents the event data payload

在 Python 中，您會定義處理事件資料的函式。Cloud Run 函式會將下列引數傳遞至處理常式：

event_data：代表事件資料酬載的字典。格式取決於事件類型。
context：物件，其中包含事件的中繼資料。

函式進入點是處理常式函式的名稱。在這個範例中，進入點為 my_background_function。

Go

package mybackgroundfunction

import (
    "context"
)

// Function MyBackgroundFunction accepts and handles event data
func MyBackgroundFunction(ctx context.Context, e EventDataType) error {
    // Your code here
    // The argument e represents the event data payload

    // Return nil if no error occurred
    return nil
}

在 Go 中，您可以定義匯出的函式，用來處理事件資料。Cloud Run 函式會將下列引數傳遞至處理常式：

ctx：包含事件中繼資料的 context.Context 物件。您可以使用 cloud.google.com/go/functions/metadata 套件擷取中繼資料。
e：代表事件資料酬載的物件。其類型 (在上述範例中為 EventDataType) 必須是函式處理的事件類型對應的結構體。事件資料酬載會使用 json.Unmarshal() 解組至結構體。

函式進入點是匯出事件處理常式的名稱。在這個範例中，進入點為 MyBackgroundFunction。

Java

package mybackgroundfunction;

import com.google.cloud.functions.BackgroundFunction;
import com.google.cloud.functions.Context;

// Define a class that implements the BackgroundFunction<T> interface
public class MyBackgroundFunction implements BackgroundFunction<EventDataType> {
  // Implement the accept() method to handle events
  @Override
  public void accept(EventDataType eventData, Context context) {
    // Your code here
    // The eventData argument represents the event data payload
  }
}

在 Java 中，您可以使用 Functions Framework Java API 實作使用 BackgroundFunction<T> 介面的事件處理常式類別。accept() 方法會接受事件資料酬載和 Context 物件做為引數，其中包含事件的中繼資料。

事件資料酬載引數的類型 (上例中為 EventDataType)，必須與函式處理的事件類型相符。事件資料酬載會使用 Gson.fromJson() 反序列化為此類別的例項。

函式進入點是事件處理常式類別的完整名稱，包括套件名稱。在這個範例中，進入點為 mybackgroundfunction.MyBackgroundFunction。

對於背景函式，事件資料酬載會以與觸發函式的事件類型相對應的格式，直接傳遞至函式。如要瞭解支援的觸發條件、事件類型和相關聯的事件資料格式，請參閱「Cloud Run 函式 (第 1 代) 支援的觸發條件」。

函式終止

Cloud Run 函式會在函式傳回時，將事件驅動函式視為已完成執行。如果函式建立背景工作 (例如使用執行緒、未來、JavaScript Promise 物件、回呼或系統程序)，您必須先終止或以其他方式解決這些工作，才能從函式返回。在函式傳回之前，未終止的任何工作可能不會完成，並可能導致未定義的行為。

自動重試

事件驅動函式可設定為自動重試失敗的叫用作業。詳情請參閱「重試事件驅動函式」。

後續步驟

瞭解 Cloud Run 函式觸發條件。
瞭解如何部署 Cloud Run 函式。