Menulis fungsi berbasis peristiwa

Di Cloud Run Functions, Anda menggunakan fungsi berbasis peristiwa saat Anda ingin fungsi dipanggil secara otomatis sebagai respons terhadap peristiwa yang terjadi di lingkungan cloud Anda.

Ada dua cara untuk menerapkan fungsi berbasis peristiwa. Cara yang Anda gunakan bergantung pada runtime bahasa yang dipilih:

Fungsi CloudEvent

Fungsi CloudEvent didasarkan pada CloudEvent, yaitu sebuah spesifikasi standar industri untuk mendeskripsikan data peristiwa dengan cara yang umum. Anda dapat mempelajari spesifikasi CloudEvents lebih lanjut di repositori GitHub CloudEvents. Project CloudEvents juga menyediakan sekumpulan CloudEvents SDK untuk membantu menangani objek CloudEvents dalam kode Anda.

Contoh berikut menunjukkan file sumber fungsi CloudEvent dasar untuk setiap runtime. Lihat Struktur direktori sumber untuk mengetahui informasi tentang lokasi kode sumber.

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;
        }
    }
}

Pada runtime .NET, Anda menggunakan Functions Framework untuk .NET untuk menerapkan class handler CloudEvent dengan antarmuka ICloudEventFunction<T>. Metode HandleAsync() menerima objek CloudEvent dan payload data CloudEvent terkait sebagai argumen.

Jenis argumen payload data CloudEvent, yang ditunjukkan dalam contoh di atas sebagai CloudEventDataType, harus sesuai dengan jenis peristiwa yang ditangani fungsi. Library .NET Google CloudEvents menyediakan jenis data untuk berbagai peristiwa yang didukung oleh Google.

Titik entri fungsi adalah nama yang sepenuhnya memenuhi syarat untuk class handler CloudEvent, termasuk namespace. Dalam contoh ini, titik entrinya adalah 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

Di Ruby, Anda mendaftarkan fungsi handler CloudEvent dengan Functions Framework untuk Ruby. Fungsi handler Anda harus menerima objek Event CloudEvent sebagai argumen.

Titik entri fungsi adalah nama yang digunakan handler untuk mendaftar pada Functions Framework. Dalam contoh ini, titik entrinya adalah 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()
}

Di PHP, Anda mendaftarkan fungsi handler CloudEvent dengan Functions Framework untuk PHP. Fungsi handler Anda harus menerima argumen yang sesuai dengan antarmuka CloudEventInterface.

Titik entri fungsi adalah nama yang digunakan handler untuk mendaftar pada Functions Framework. Dalam contoh ini, titik entrinya adalah myCloudEventFunction.

Untuk fungsi CloudEvent, data peristiwa diteruskan ke fungsi Anda dalam format CloudEvents, dengan payload data CloudEvents yang sesuai dengan jenis peristiwa yang memicu fungsi Anda. Baca artikel Pemicu Cloud Run Functions untuk mengetahui informasi tentang pemicu yang didukung, jenis peristiwa, dan format data peristiwa terkait.

Repositori Google Events berisi resource untuk bekerja dengan CloudEvents yang dikeluarkan oleh Google.

Fungsi latar belakang

Fungsi berbasis peristiwa di runtime Node.js, Python, Go, dan Java mengharapkan argumen yang berbeda dari fungsi CloudEvent. Gaya lama fungsi berbasis peristiwa ini disebut fungsi latar belakang.

Contoh berikut menunjukkan file sumber fungsi latar belakang dasar untuk setiap runtime. Lihat Struktur direktori sumber untuk mengetahui informasi tentang lokasi kode sumber.

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();
};

Di Node.js, Anda menentukan dan mengekspor fungsi yang menangani data peristiwa. Cloud Run Functions meneruskan argumen berikut ke fungsi handler Anda:

  • eventData: Objek yang mewakili payload data peristiwa. Formatnya bergantung pada jenis peristiwa.
  • context: Objek yang berisi metadata tentang peristiwa.
  • callback: Fungsi opsional yang dapat Anda panggil untuk menyelesaikan sinyal. Argumen pertama untuk callback ini ditafsirkan sebagai menandakan error. Jangan teruskan argumen atau argumen pertama null untuk menandakan keberhasilan.

Titik entri fungsi adalah nama handler peristiwa yang diekspor. Dalam contoh ini, titik entrinya adalah 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

Di Python, Anda menentukan fungsi yang menangani data peristiwa. Cloud Run Functions meneruskan argumen berikut ke fungsi handler Anda:

  • event_data: Kamus yang mewakili payload data peristiwa. Formatnya bergantung pada jenis peristiwa.
  • context: Objek yang berisi metadata tentang peristiwa.

Titik entri fungsi adalah nama fungsi handler. Dalam contoh ini, titik entrinya adalah 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
}

Di Go, Anda menentukan fungsi yang diekspor yang menangani data peristiwa. Cloud Run Functions meneruskan argumen berikut ke fungsi handler Anda:

  • ctx: Objek context.Context yang berisi metadata tentang peristiwa. Anda dapat mengambil metadata menggunakan paket cloud.google.com/go/functions/metadata.
  • e: Objek yang mewakili payload data peristiwa. Jenisnya, yang ditunjukkan dalam contoh di atas sebagai EventDataType, harus berupa struct yang sesuai dengan jenis peristiwa yang ditangani fungsi. Payload data peristiwa tidak disusun ke dalam struct menggunakan json.Unmarshal().

Titik entri fungsi adalah nama handler peristiwa yang diekspor. Dalam contoh ini, titik entrinya adalah 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
  }
}

Di Java, Anda menggunakan Functions Framework Java API untuk mengimplementasikan class handler peristiwa dengan antarmuka BackgroundFunction<T>. Metode accept() menerima payload data peristiwa sebagai argumen dan objek Context yang berisi metadata tentang peristiwa tersebut.

Jenis argumen payload data peristiwa, yang ditunjukkan dalam contoh di atas sebagai EventDataType, harus sesuai dengan jenis peristiwa yang ditangani fungsi. Payload data peristiwa dideserialisasi ke instance class ini menggunakan Gson.fromJson().

Titik entri fungsi adalah nama yang sepenuhnya memenuhi syarat dari class handler peristiwa, termasuk nama paket. Dalam contoh ini, titik entrinya adalah mybackgroundfunction.MyBackgroundFunction.

Untuk fungsi latar belakang, payload data peristiwa diteruskan langsung ke fungsi Anda dalam format yang sesuai dengan jenis peristiwa yang memicu fungsi Anda. Lihat Pemicu yang didukung di Cloud Run Functions (generasi ke-1) untuk mengetahui informasi tentang pemicu yang didukung, jenis peristiwa, dan format data peristiwa terkait.

Penghentian fungsi

Cloud Run Functions menganggap eksekusi fungsi berbasis peristiwa selesai saat fungsi tersebut ditampilkan. Jika fungsi membuat tugas latar belakang (seperti dengan thread, future, objek Promise JavaScript, callback, atau proses sistem), Anda harus menghentikan atau menyelesaikan tugas ini sebelum kembali dari fungsi. Setiap tugas yang tidak dihentikan sebelum fungsi ditampilkan mungkin belum diselesaikan, dan dapat menyebabkan perilaku yang tidak ditentukan.

Percobaan ulang otomatis

Fungsi berbasis peristiwa dapat dikonfigurasi untuk mencoba kembali pemanggilan yang gagal secara otomatis. Lihat Mencoba kembali fungsi berbasis peristiwa untuk mengetahui informasi selengkapnya.

Langkah berikutnya