כתיבת פונקציות מבוססות-אירועים

בפונקציות Cloud Run, משתמשים בפונקציות מבוססות-אירועים כשרוצים שפונקציה תופעל אוטומטית בתגובה לאירוע שמתרחש בסביבת הענן.

יש שתי דרכים להטמיע פונקציות מבוססות-אירועים. הדרך שבה משתמשים ב-depends משתנה בהתאם לזמן הריצה של השפה שנבחרה:

פונקציות CloudEvent

פונקציות CloudEvent מבוססות על CloudEvents, מפרט שהוא תקן בתעשייה לתיאור נתוני אירועים בדרך משותפת. מידע נוסף על המפרט של CloudEvents זמין במאגר CloudEvents GitHub. בפרויקט CloudEvents יש גם קבוצה של ערכות SDK של CloudEvents שעוזרות לעבוד עם אובייקטים של 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, משתמשים ב-Functions Framework for .NET כדי להטמיע מחלקה של handler ל-CloudEvent עם הממשק ICloudEventFunction<T>. ה-method ‏HandleAsync() מקבלת אובייקט CloudEvent ומטען ייעודי (payload) של נתוני CloudEvent כארגומנטים.

הסוג של הארגומנט של מטען הנתונים של CloudEvent, שמוצג בדוגמה שלמעלה כ-CloudEventDataType, צריך להתאים לסוג האירוע שהפונקציה מטפלת בו. ספריית ‎ .NET של Google CloudEvents מספקת סוגי נתונים לאירועים השונים שנתמכים על ידי Google.

נקודת הכניסה של הפונקציה היא השם המלא של מחלקת ה-handler של 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, רושמים פונקציית handler של CloudEvent באמצעות Functions Framework for Ruby. פונקציית ה-handler צריכה לקבל אובייקט של CloudEvents‏ Event כארגומנט.

נקודת הכניסה של הפונקציה היא השם שבו רשום ה-handler ב-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, רושמים פונקציית handler של CloudEvent באמצעות Functions Framework for PHP. פונקציית ה-handler צריכה לקבל ארגומנט שתואם לממשק CloudEventInterface.

נקודת הכניסה של הפונקציה היא השם שבו רשום ה-handler ב-Functions Framework. בדוגמה הזו, נקודת הכניסה היא myCloudEventFunction.

בפונקציות CloudEvent, נתוני האירוע מועברים לפונקציה בפורמט CloudEvents, עם מטען ייעודי (payload) של נתונים של CloudEvent שמתאים לסוג האירוע שמפעיל את הפונקציה. במאמר בנושא טריגרים של פונקציות Cloud Run מפורט מידע על טריגרים נתמכים, סוגי אירועים ופורמטים של נתוני אירועים משויכים.

מאגר Google Events מכיל משאבים לעבודה עם CloudEvents שהונפקו על ידי Google.

פונקציות ברקע

פונקציות מבוססות-אירועים בסביבות זמן הריצה של 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 מעבירות לפונקציית ה-handler את הארגומנטים הבאים:

  • ‫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 מעבירות לפונקציית ה-handler את הארגומנטים הבאים:

  • event_data: מילון שמייצג את נתוני האירוע. הפורמט שלו תלוי בסוג האירוע.
  • ‫context: אובייקט שמכיל מטא-נתונים על האירוע.

נקודת הכניסה של הפונקציה היא השם של פונקציית ה-handler. בדוגמה הזו, נקודת הכניסה היא 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 מעבירות לפונקציית ה-handler את הארגומנטים הבאים:

  • ‫ctx: אובייקט context.Context שמכיל מטא-נתונים על האירוע. אפשר לאחזר את המטא-נתונים באמצעות חבילת cloud.google.com/go/functions/metadata.
  • ‫e: אובייקט שמייצג את נתוני האירוע. הסוג שלו, שמוצג בדוגמה שלמעלה כ-EventDataType, חייב להיות מבנה שמתאים לסוג האירוע שהפונקציה מטפלת בו. מטען הייעודי (payload) של נתוני האירוע מבוטל (unmarshaled) למבנה באמצעות 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 שמכיל מטא-נתונים על האירוע.

הסוג של ארגומנט המטען הייעודי (payload) של נתוני האירוע, שמוצג בדוגמה שלמעלה כ-EventDataType, צריך להתאים לסוג האירוע שהפונקציה מטפלת בו. המטען הייעודי (payload) של נתוני האירועים עובר דה-סריאליזציה למופע של המחלקה הזו באמצעות Gson.fromJson().

‫function entry point הוא השם המלא של מחלקת ה-event handler, כולל שם החבילה. בדוגמה הזו, נקודת הכניסה היא mybackgroundfunction.MyBackgroundFunction.

בפונקציות שפועלות ברקע, מטען הייעודי של נתוני האירוע מועבר ישירות לפונקציה בפורמט שמתאים לסוג האירוע שמפעיל את הפונקציה. מידע על טריגרים נתמכים, סוגי אירועים ופורמטים משויכים של נתוני אירועים זמין במאמר בנושא טריגרים שנתמכים בפונקציות Cloud Run (דור ראשון).

סיום הפונקציה

פונקציות Cloud Run מחשיבות את הביצוע של פונקציה מבוססת-אירועים כהשלמה כשהפונקציה מחזירה ערך. אם הפונקציה יוצרת משימות ברקע (כמו עם threads,‏ futures,‏ אובייקטים של JavaScript Promise, קריאות חוזרות או תהליכי מערכת), צריך לסיים את המשימות האלה או לפתור אותן בדרך אחרת לפני שחוזרים מהפונקציה. יכול להיות שמשימות שלא הסתיימו לפני שהפונקציה מחזירה ערך לא יושלמו, ועלולות לגרום להתנהגות לא מוגדרת.

ניסיונות חוזרים אוטומטיים

אפשר להגדיר פונקציות מבוססות-אירועים כך שינסו אוטומטית להפעיל שוב קריאות שנכשלו. מידע נוסף זמין במאמר בנושא ניסיון חוזר של פונקציות מבוססות-אירועים.

השלבים הבאים