編寫事件導向函式

在 Cloud Run functions 中，如果希望函式因應雲端環境中發生的事件自動叫用，請使用事件導向函式。

實作事件導向函式的方法有兩種。實作方式取決於您選擇的語言執行階段：

  • 如果是 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 適用的 Functions Framework，透過 ICloudEventFunction<T> 介面實作 CloudEvent 處理常式類別。HandleAsync() 方法會接受 CloudEvent 物件和相關聯的 CloudEvent 資料酬載做為引數。

如上例所示，CloudEvent 資料酬載引數的類型 (CloudEventDataType) 必須對應至函式處理的事件類型。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 Events 存放區包含的資源，可用於處理 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 functions 會將下列引數傳遞至處理常式函式：

  • 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 functions 會將下列引數傳遞至處理常式函式：

  • 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 functions 會將下列引數傳遞至處理常式函式：

  • ctx：包含事件中繼資料的 context.Context 物件。您可以使用 cloud.google.com/go/functions/metadata 套件擷取中繼資料。
  • e：代表事件資料酬載的物件。如上例所示，其類型 (EventDataType) 必須是與函式處理的事件類型對應的 struct。事件資料酬載會使用 json.Unmarshal() 解除封送處理至 struct。

函式進入點是匯出的事件處理常式名稱。在這個範例中，進入點為 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 functions (第 1 代) 支援的觸發條件」。

函式終止

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

自動重試

您可以設定事件驅動函式，在呼叫失敗時自動重試。詳情請參閱「重試事件驅動函式」。

後續步驟