כתיבה של פונקציות Cloud Run

בדף הזה מוסבר איך לכתוב פונקציות Cloud Run מבוססות-אירועים ופונקציות HTTP באמצעות Functions Framework.

סקירה כללית של Functions Framework

כשכותבים קוד מקור של פונקציות, צריך להשתמש ב-Functions Framework, ספריית קוד פתוח לכתיבת פונקציות Cloud Run. באמצעות Functions Framework אפשר לכתוב פונקציות קלות משקל שפועלות ב-Cloud Run ובסביבות אחרות, כולל במכונת הפיתוח המקומית ובסביבות מבוססות Knative.

ה-Functions Framework מאפשר לכם:

• הפעלת פונקציית Cloud Run בתגובה לבקשה.
• האירועים שתואמים למפרט CloudEvents, שהוא מפרט בתקן התעשייה לתיאור נתוני אירועים בדרך משותפת, מבוטלים באופן אוטומטי.
• מפעילים שרת פיתוח מקומי לבדיקה.

‫Functions Framework מספק ממשק ליצירת שירותים מודולריים. כדי להשתמש ב-Functions Framework בקוד המקור, צריך לציין את הפרטים הבאים:

• Function entry point
• סוג החתימה

נקודת כניסה לפונקציה

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

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

סוג החתימה

כשכותבים את קוד המקור של פונקציה באמצעות Functions Framework, צריך לציין אחד משני סוגי החתימות:

• פונקציות HTTP: רישום של פונקציית handler של HTTP. משתמשים בפונקציית HTTP כשהפונקציה צריכה נקודת קצה של כתובת URL וחייבת להגיב לבקשות HTTP, למשל עבור webhook.
• פונקציות מבוססות-אירועים, שנקראות גם פונקציות CloudEvents: רושמת פונקציית handler של CloudEvents. משתמשים בפונקציה מבוססת-אירועים כשהפונקציה מופעלת ישירות בתגובה לאירועים ב Google Cloud פרויקט, כמו הודעות בנושא Pub/Sub או שינויים בקטגוריה של Cloud Storage.

המבנה של ספריית קובצי המקור

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

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

Node.js

מבנה הספריות הבסיסי של פונקציות Node.js הוא כזה:

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

כברירת מחדל, Cloud Run מנסה לטעון קוד מקור מקובץ בשם index.js בספריית הבסיס של הפונקציה. כדי לציין קובץ מקור ראשי אחר, משתמשים בשדה main בקובץ package.json.

קובץ package.json צריך לכלול גם את Functions Framework for Node.js כתלות:

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

הערה: אפשר להוסיף את התלות ב-Functions Framework באמצעות npm על ידי הפעלת npm install @google-cloud/functions-framework.

הקוד בקובץ הראשי צריך להגדיר את נקודת הכניסה של הפונקציה, ויכול לייבא קוד אחר ומודולים של Node.js. בנוסף, בקובץ הראשי אפשר להגדיר כמה נקודות כניסה לפונקציות שאפשר לפרוס בנפרד.

פרטים נוספים זמינים במאמרים סקירה כללית של סביבת זמן הריצה של Node.js וFunctions Framework for Node.js.

Python

מבנה הספריות הבסיסי של פונקציות Python הוא כדלקמן:

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

‫Cloud Run טוען קוד מקור מקובץ בשם main.py שנמצא בספרייה הבסיסית של הפונקציה. צריך לתת לקובץ הראשי את השם main.py.

קובץ requirements.txt חייב לכלול את Functions Framework for Python כתלות:

functions-framework==3.*

הקוד בקובץ main.py צריך להגדיר את נקודת הכניסה של הפונקציה, ויכול לייבא קוד אחר ותלות חיצונית כרגיל. קובץ main.py יכול להגדיר גם כמה נקודות כניסה לפונקציות שאפשר לפרוס בנפרד.

פרטים נוספים זמינים במאמר סקירה כללית של Python runtime ובמאמר Functions Framework for Python.

Go

המבנה הבסיסי של ספריית פונקציות Go הוא כדלקמן:

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

הפונקציה צריכה להיות בחבילת Go בשורש הפרויקט. לחבילה ולקובצי המקור שלה יכול להיות כל שם, אבל הפונקציה לא יכולה להיות ב-package main. אם אתם צריכים חבילת main, למשל לצורך בדיקות מקומיות, אתם יכולים ליצור אותה בספריית משנה:

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

קובץ go.mod צריך לכלול את Functions Framework for Go כתלות:

module example.com/my-module

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

הערה: אפשר להוסיף את התלות ב-Functions Framework על ידי הפעלת הפקודה go get github.com/GoogleCloudPlatform/functions-framework-go.

הקוד בחבילת הבסיס צריך להגדיר את נקודת הכניסה של הפונקציה, ויכול לייבא קוד אחר מחבילות משנה ומקובצי תלות כרגיל. החבילה יכולה להגדיר גם כמה נקודות כניסה של פונקציות שאפשר לפרוס בנפרד.

הערה: דוגמה להגדרת פרויקט בסיסי של Cloud Run ב-Go אפשר למצוא במדריך למתחילים בנושא Functions Framework for Go ב-GitHub.

פרטים נוספים זמינים במאמר סקירה כללית של זמן הריצה של Go ובמאמר בנושא Functions Framework for 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 צריך לכלול את Functions Framework for Java כתלות:

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

הקוד בקובצי המקור צריך להגדיר את נקודת הכניסה של הפונקציה, ואפשר לייבא קוד אחר ותלות חיצונית כרגיל. בנוסף, קובצי המקור יכולים להגדיר כמה נקודות כניסה של פונקציות שאפשר לפרוס בנפרד.

פרטים נוספים זמינים במאמרים בנושא סקירה כללית של Java runtime ו-Functions Framework for Java.

‎.NET

מבנה הספריות הבסיסי של פונקציות ‎ .NET הוא כדלקמן:

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

אתם יכולים לבנות את הפרויקטים שלכם כמו כל קוד מקור אחר של ‎ .NET. קובצי המקור יכולים להיות בכל שם.

הערה: אותו דפוס חל גם אם משתמשים ב-F# ‎ או ב-Visual Basic, אבל עם סיומות קבצים מתאימות (.fs ו-.fsproj ל-F#‎,‏ .vb ו-.vbproj ל-Visual Basic).

קובץ הפרויקט צריך לכלול את Functions Framework for .NET כתלות:

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

הקוד בקובצי המקור צריך להגדיר את נקודת הכניסה של הפונקציה, ואפשר לייבא קוד אחר ותלות חיצונית כרגיל. בנוסף, קובצי המקור יכולים להגדיר כמה נקודות כניסה של פונקציות שאפשר לפרוס בנפרד.

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

פרטים נוספים זמינים במאמר סקירה כללית של זמן הריצה של ‎.NET ובמאמר Functions Framework for .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"

הערה: אפשר להוסיף את התלות ב-Functions Framework באמצעות Bundler על ידי הפעלת bundle add functions_framework.

הקוד בקובץ app.rb צריך להגדיר את נקודת הכניסה של הפונקציה, ויכול לייבא קוד אחר ותלות חיצונית כרגיל. קובץ app.rb יכול להגדיר גם כמה נקודות כניסה לפונקציות שאפשר לפרוס בנפרד.

פרטים נוספים זמינים במאמר סקירה כללית של זמן הריצה של Ruby ובמאמר בנושא Functions Framework for Ruby.

PHP

מבנה הספריות הבסיסי של פונקציות PHP הוא כזה:

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

‫Cloud Run טוען קוד מקור מקובץ בשם index.php שנמצא בספרייה הבסיסית של הפונקציה. צריך לתת לקובץ הראשי את השם index.php.

קובץ composer.json צריך לכלול את Functions Framework for PHP כתלות:

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

הערה: אפשר להוסיף את התלות של Functions Framework באמצעות Composer על ידי הפעלת הפקודה composer require google/cloud-functions-framework.

הקוד בקובץ index.php צריך להגדיר את נקודת הכניסה של הפונקציה, ויכול לייבא קוד אחר ותלות חיצונית כרגיל. קובץ index.php יכול להגדיר גם כמה נקודות כניסה לפונקציות שאפשר לפרוס בנפרד.

פרטים נוספים זמינים במאמר סקירה כללית של זמן הריצה של PHP ובמאמר Functions Framework for PHP.

אם מקבצים כמה פונקציות בפרויקט אחד, צריך לזכור שכל הפונקציות עשויות לחלוק את אותה קבוצה של תלות. עם זאת, יכול להיות שחלק מהפונקציות לא יזדקקו לכל התלויות.

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

כתיבת פונקציות HTTP

כותבים פונקציית HTTP כשרוצים להפעיל פונקציה באמצעות בקשת HTTP(S). כדי לאפשר סמנטיקה של HTTP, משתמשים ב-Function Framework ומציינים את חתימת הפונקציה של HTTP כדי לקבל ארגומנטים ספציפיים ל-HTTP.

בדוגמה הבאה מוצג קובץ מקור של פונקציית HTTP בסיסית לכל סביבת זמן ריצה. דוגמה מלאה ופעילה מופיעה במאמר פריסת פונקציית Cloud Run באמצעות Google Cloud CLI. מידע נוסף על המיקום של קוד המקור זמין במאמר בנושא מבנה ספריית קובצי המקור.

Node.js

מודול ES

  import { http } from '@google-cloud/functions-framework';
  http('myHttpFunction', (req, res) => {
    // Your code here

    // Send an HTTP response
    res.send('OK');
  });

מוסיפים את יחסי התלות הבאים, כולל "type": "module" בקובץ package.json:

  {
    "dependencies": {
      "@google-cloud/functions-framework": "^3.0.0"
    },
    "type": "module"
  }

מודול CommonJS

  const functions = require('@google-cloud/functions-framework');

  // Register an HTTP function with the Functions Framework
  functions.http('myHttpFunction', (req, res) => {
    // Your code here

    // Send an HTTP response
    res.send('OK');
  });

מוסיפים את יחסי התלות הבאים לקובץ package.json:

  {
    "dependencies": {
      "@google-cloud/functions-framework": "^3.0.0"
    }
  }

ב-Node.js, רושמים פונקציה לטיפול ב-HTTP באמצעות Functions Framework for Node.js. פונקציית ה-handler של HTTP צריכה להיות פונקציית תווכה של Express שמקבלת את הארגומנטים request ו-response ושולחת תגובת HTTP.

‫Cloud Run מנתח באופן אוטומטי את גוף הבקשה על סמך הכותרת Content-Type של הבקשה באמצעות body-parser, כך שתוכלו לגשת לאובייקטים req.body ו-req.rawBody ב-handler של HTTP.

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

Python

import functions_framework

# Register an HTTP function with the Functions Framework
@functions_framework.http
def my_http_function(request):
  # Your code here

  # Return an HTTP response
  return 'OK'

ב-Python, רושמים פונקציית handler של HTTP באמצעות Functions Framework for Python. פונקציית ה-handler של ה-HTTP חייבת לקבל אובייקט Flask request כארגומנט ולהחזיר ערך ש-Flask יכול להמיר לאובייקט תגובת HTTP.

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

Go

package myhttpfunction

import (
    "fmt"
    "net/http"

    "github.com/GoogleCloudPlatform/functions-framework-go/functions"
)

func init() {
    // Register an HTTP function with the Functions Framework
    functions.HTTP("MyHTTPFunction", myHTTPFunction)
}

// Function myHTTPFunction is an HTTP handler
func myHTTPFunction(w http.ResponseWriter, r *http.Request) {
    // Your code here

    // Send an HTTP response
    fmt.Fprintln(w, "OK")
}

ב-Go, רושמים פונקציה לטיפול ב-HTTP באמצעות Functions Framework for Go בפונקציה init(). פונקציית ה-handler של ה-HTTP צריכה להשתמש בממשק http.HandlerFunc הרגיל כדי לשלוח תגובת HTTP.

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

פונקציית ה-handler של HTTP צריכה להטמיע את הממשק הרגיל של http.HandlerFunc. היא מקבלת ממשק http.ResponseWriter שהפונקציה משתמשת בו כדי ליצור תשובה לבקשה, ומצביע למבנה http.Request שמכיל את הפרטים של בקשת ה-HTTP הנכנסת.

Java

package myhttpfunction;

import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;

// Define a class that implements the HttpFunction interface
public class MyHttpFunction implements HttpFunction {
  // Implement the service() method to handle HTTP requests
  @Override
  public void service(HttpRequest request, HttpResponse response) throws Exception {
    // Your code here

    // Send an HTTP response
    response.getWriter().write("OK");
  }
}

ב-Java, משתמשים ב-Functions Framework Java API כדי להטמיע מחלקה של handler ל-HTTP עם הממשק HttpFunction. השיטה service() חייבת לשלוח תגובת HTTP.

נקודת הכניסה של הפונקציה היא השם המלא של מחלקת ה-handler של ה-HTTP, כולל שם החבילה. בדוגמה הזו, נקודת הכניסה היא myhttpfunction.MyHttpFunction.

השיטה service מקבלת אובייקט HttpRequest שמתאר את בקשת ה-HTTP הנכנסת, ואובייקט HttpResponse שהפונקציה מאכלסת בהודעת תגובה.

‎.NET

using Google.Cloud.Functions.Framework;
using Microsoft.AspNetCore.Http;
using System.Threading.Tasks;

namespace MyProject
{
    // Define a class that implements the IHttpFunction interface
    public class MyHttpFunction : IHttpFunction
    {
        // Implement the HandleAsync() method to handle HTTP requests
        public async Task HandleAsync(HttpContext context)
        {
            // Your code here

            // Send an HTTP response
            await context.Response.WriteAsync("OK");
        }
    }
}

בזמני ריצה של ‎ .NET, משתמשים ב-Functions Framework for .NET כדי להטמיע מחלקה של HTTP handler עם הממשק IHttpFunction. השיטה HandleAsync() מקבלת אובייקט HttpContext סטנדרטי של ASP.NET כארגומנט, והיא חייבת לשלוח תגובת HTTP.

נקודת הכניסה של הפונקציה היא השם המלא של מחלקת ה-handler של HTTP, כולל מרחב השמות. בדוגמה הזו, נקודת הכניסה היא MyProject.MyHttpFunction.

Ruby

require "functions_framework"

# Register an HTTP function with the Functions Framework
FunctionsFramework.http "my_http_function" do |request|
  # Your code here

  # Return an HTTP response
  "OK"
end

ב-Ruby, רושמים פונקציית handler של HTTP באמצעות Functions Framework for Ruby. פונקציית ה-handler של HTTP חייבת לקבל אובייקט Rack request כארגומנט ולהחזיר ערך שאפשר להשתמש בו כתגובת HTTP.

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

PHP

<?php

use Google\CloudFunctions\FunctionsFramework;
use Psr\Http\Message\ServerRequestInterface;

// Register an HTTP function with the Functions Framework
FunctionsFramework::http('myHttpFunction', 'myHttpHandler');

// Define your HTTP handler
function myHttpHandler(ServerRequestInterface $request): string
{
    // Your code here

    // Return an HTTP response
    return 'OK';
}

ב-PHP, רושמים פונקציית handler של HTTP באמצעות Functions Framework for PHP. פונקציית הטיפול ב-HTTP חייבת לקבל ארגומנט שמיישם את הממשק PSR-7 ServerRequestInterface ולחזיר תגובת HTTP כמחרוזת או כאובייקט שמיישם את הממשק PSR-7 ResponseInterface.

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

בקשות ותגובות HTTP

כשרושמים פונקציית handler של HTTP ב-Functions Framework, ה-handler של HTTP יכול לבדוק את שיטת הבקשה ולבצע פעולות שונות על סמך השיטה.

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

טיפול ב-CORS

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

כדי לאפשר לבקשות ממקורות שונים לגשת לפונקציה, צריך להגדיר את הכותרת Access-Control-Allow-Origin בתגובת ה-HTTP. במקרה של בקשות קדם-הפעלה ממקורות שונים, צריך להשיב לבקשת קדם-ההפעלה OPTIONS עם קוד תגובה 204 וכותרות נוספות.

Node.js

const functions = require('@google-cloud/functions-framework');

/**
 * HTTP function that supports CORS requests.
 *
 * @param {Object} req Cloud Function request context.
 * @param {Object} res Cloud Function response context.
 */
functions.http('corsEnabledFunction', (req, res) => {
  // Set CORS headers for preflight requests
  // Allows GETs from any origin with the Content-Type header
  // and caches preflight response for 3600s

  res.set('Access-Control-Allow-Origin', '*');

  if (req.method === 'OPTIONS') {
    // Send response to OPTIONS requests
    res.set('Access-Control-Allow-Methods', 'GET');
    res.set('Access-Control-Allow-Headers', 'Content-Type');
    res.set('Access-Control-Max-Age', '3600');
    res.status(204).send('');
  } else {
    res.send('Hello World!');
  }
});

Python

import functions_framework

@functions_framework.http
def cors_enabled_function(request):
    # For more information about CORS and CORS preflight requests, see:
    # https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request

    # Set CORS headers for the preflight request
    if request.method == "OPTIONS":
        # Allows GET requests from any origin with the Content-Type
        # header and caches preflight response for an 3600s
        headers = {
            "Access-Control-Allow-Origin": "*",
            "Access-Control-Allow-Methods": "GET",
            "Access-Control-Allow-Headers": "Content-Type",
            "Access-Control-Max-Age": "3600",
        }

        return ("", 204, headers)

    # Set CORS headers for the main request
    headers = {"Access-Control-Allow-Origin": "*"}

    return ("Hello World!", 200, headers)

Go

// Package http provides a set of HTTP Cloud Functions samples.
package http

import (
	"fmt"
	"net/http"

	"github.com/GoogleCloudPlatform/functions-framework-go/functions"
)

// CORSEnabledFunction is an example of setting CORS headers.
// For more information about CORS and CORS preflight requests, see
// https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request.
func CORSEnabledFunction(w http.ResponseWriter, r *http.Request) {
	// Set CORS headers for the preflight request
	if r.Method == http.MethodOptions {
		w.Header().Set("Access-Control-Allow-Origin", "*")
		w.Header().Set("Access-Control-Allow-Methods", "POST")
		w.Header().Set("Access-Control-Allow-Headers", "Content-Type")
		w.Header().Set("Access-Control-Max-Age", "3600")
		w.WriteHeader(http.StatusNoContent)
		return
	}
	// Set CORS headers for the main request.
	w.Header().Set("Access-Control-Allow-Origin", "*")
	fmt.Fprint(w, "Hello, World!")
}

func init() {
	functions.HTTP("CORSEnabledFunction", CORSEnabledFunction)
}

Java

import com.google.cloud.functions.HttpFunction;
import com.google.cloud.functions.HttpRequest;
import com.google.cloud.functions.HttpResponse;
import java.io.BufferedWriter;
import java.io.IOException;
import java.net.HttpURLConnection;

public class CorsEnabled implements HttpFunction {
  // corsEnabled is an example of setting CORS headers.
  // For more information about CORS and CORS preflight requests, see
  // https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request.
  @Override
  public void service(HttpRequest request, HttpResponse response)
      throws IOException {
    // Set CORS headers
    //   Allows GETs from any origin with the Content-Type
    //   header and caches preflight response for 3600s
    response.appendHeader("Access-Control-Allow-Origin", "*");

    if ("OPTIONS".equals(request.getMethod())) {
      response.appendHeader("Access-Control-Allow-Methods", "GET");
      response.appendHeader("Access-Control-Allow-Headers", "Content-Type");
      response.appendHeader("Access-Control-Max-Age", "3600");
      response.setStatusCode(HttpURLConnection.HTTP_NO_CONTENT);
      return;
    }

    // Handle the main request.
    BufferedWriter writer = response.getWriter();
    writer.write("CORS headers set successfully!");
  }
}

‎.NET

using Google.Cloud.Functions.Framework;
using Microsoft.AspNetCore.Http;
using System.Net;
using System.Threading.Tasks;

namespace Cors;

// For more information about CORS and CORS preflight requests, see
// https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request.
public class Function : IHttpFunction
{
    public async Task HandleAsync(HttpContext context)
    {
        HttpRequest request = context.Request;
        HttpResponse response = context.Response;

        // Set CORS headers
        //   Allows GETs from any origin with the Content-Type
        //   header and caches preflight response for 3600s

        response.Headers.Append("Access-Control-Allow-Origin", "*");
        if (HttpMethods.IsOptions(request.Method))
        {
            response.Headers.Append("Access-Control-Allow-Methods", "GET");
            response.Headers.Append("Access-Control-Allow-Headers", "Content-Type");
            response.Headers.Append("Access-Control-Max-Age", "3600");
            response.StatusCode = (int) HttpStatusCode.NoContent;
            return;
        }

        await response.WriteAsync("CORS headers set successfully!", context.RequestAborted);
    }
}

Ruby

FunctionsFramework.http "cors_enabled_function" do |request|
  # For more information about CORS and CORS preflight requests, see
  # https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request
  # for more information.

  # Set CORS headers for the preflight request
  if request.options?
    # Allows GET requests from any origin with the Content-Type
    # header and caches preflight response for an 3600s
    headers = {
      "Access-Control-Allow-Origin"  => "*",
      "Access-Control-Allow-Methods" => "GET",
      "Access-Control-Allow-Headers" => "Content-Type",
      "Access-Control-Max-Age"       => "3600"
    }
    [204, headers, []]
  else
    # Set CORS headers for the main request
    headers = {
      "Access-Control-Allow-Origin" => "*"
    }

    [200, headers, ["Hello World!"]]
  end
end

PHP

use Psr\Http\Message\ResponseInterface;
use Psr\Http\Message\ServerRequestInterface;
use GuzzleHttp\Psr7\Response;

function corsEnabledFunction(ServerRequestInterface $request): ResponseInterface
{
    // Set CORS headers for preflight requests
    // Allows GETs from any origin with the Content-Type header
    // and caches preflight response for 3600s
    $headers = ['Access-Control-Allow-Origin' => '*'];

    if ($request->getMethod() === 'OPTIONS') {
        // Send response to OPTIONS requests
        $headers = array_merge($headers, [
            'Access-Control-Allow-Methods' => 'GET',
            'Access-Control-Allow-Headers' => 'Content-Type',
            'Access-Control-Max-Age' => '3600'
        ]);
        return new Response(204, $headers, '');
    } else {
        return new Response(200, $headers, 'Hello World!');
    }
}

אם CORS לא מוגדר כמו שצריך, יכול להיות שיוצגו שגיאות כמו השגיאות הבאות:

XMLHttpRequest cannot load https://YOUR_FUNCTION_URL.
No 'Access-Control-Allow-Origin' header is present on the requested resource.
Origin 'https://YOUR_DOMAIN' is therefore not allowed access.

מגבלות CORS

בבקשות קדם-הפעלה בין מקורות, בקשות קדם-הפעלה מסוג OPTIONS נשלחות ללא כותרת Authorization, ולכן הן יידחו בכל הפונקציות של HTTP שדורשות אימות. הבקשות הראשיות ייכשלו גם הן כי הבקשות המקדימות נכשלות. כדי לעקוף את ההגבלה הזו, אפשר להשתמש באחת מהאפשרויות הבאות:

• Allow public access (מתן גישה ציבורית) של הפונקציה.
• מגדירים שרת proxy לאימות זהויות עבור הפונקציה, שמספק את כותרת ההרשאה לבקשות OPTIONS קדם-הפעלה שנשלחות לפונקציות Cloud Run.
• כדי להימנע מ-CORS, מארחים את אפליקציית האינטרנט ואת Cloud Run באותו דומיין. אפשר לעשות זאת באמצעות שילוב של אירוח ב-Firebase עם פונקציות Cloud Run.

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

כדאי לכתוב פונקציה מבוססת-אירועים כשרוצים שהפונקציה תופעל ישירות בתגובה לאירועים ב Google Cloud פרויקט, כמו הודעות בנושא Pub/Sub או שינויים בקטגוריה של Cloud Storage.

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

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

Node.js

מודול ES

  import { cloudEvent } from "@google-cloud/functions-framework";
  cloudEvent('myCloudEventFunction', cloudEvent => {
    // Your code here
    // Access the CloudEvent data payload using cloudEvent.data
  });

מוסיפים את יחסי התלות הבאים, כולל "type": "module" בקובץ package.json:

  {
    "dependencies": {
      "@google-cloud/functions-framework": "^3.0.0"
    },
    "type": "module"
  }

מודול CommonJS

const functions = require('@google-cloud/functions-framework');

// Register a CloudEvent function with the Functions Framework
functions.cloudEvent('myCloudEventFunction', cloudEvent => {
  // Your code here
  // Access the CloudEvent data payload using cloudEvent.data
});

מוסיפים את יחסי התלות הבאים לקובץ package.json:

  {
    "dependencies": {
      "@google-cloud/functions-framework": "^3.0.0"
    }
  }

ב-Node.js, רושמים פונקציית handler של CloudEvent באמצעות Functions Framework for Node.js. פונקציית ה-handler צריכה לקבל אובייקט CloudEvent כארגומנט.

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

Python

import functions_framework

# Register a CloudEvent function with the Functions Framework
@functions_framework.cloud_event
def my_cloudevent_function(cloud_event):
  # Your code here
  # Access the CloudEvent data payload via cloud_event.data

ב-Python, רושמים פונקציית handler של CloudEvent באמצעות Functions Framework for Python. פונקציית ה-handler צריכה לקבל אובייקט CloudEvent כארגומנט.

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

Go

package mycloudeventfunction

import (
    "context"

    "github.com/GoogleCloudPlatform/functions-framework-go/functions"
    "github.com/cloudevents/sdk-go/v2/event"
)

func init() {
    // Register a CloudEvent function with the Functions Framework
    functions.CloudEvent("MyCloudEventFunction", myCloudEventFunction)
}

// Function myCloudEventFunction accepts and handles a CloudEvent object
func myCloudEventFunction(ctx context.Context, e event.Event) error {
    // Your code here
    // Access the CloudEvent data payload using e.Data() or e.DataAs(...)

    // Returning an error causes its message to be logged.
    // Example:
    err := myInternalFunction() // may return an error
    if err != nil {
        // Append error message to log
        return err
    }

    // Return nil if no error occurred
    return nil
}

ב-Go, רושמים פונקציית handler של CloudEvents באמצעות Functions Framework for Go. פונקציית ה-handler צריכה לקבל אובייקט CloudEvents event.Event כארגומנט.

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

Java

package mycloudeventfunction;

import com.google.cloud.functions.CloudEventsFunction;
import io.cloudevents.CloudEvent;

// Define a class that implements the CloudEventsFunction interface
public class MyCloudEventFunction implements CloudEventsFunction {
  // Implement the accept() method to handle CloudEvents
  @Override
  public void accept(CloudEvent event) {
    // Your code here
    // Access the CloudEvent data payload using event.getData()
    // To get the data payload as a JSON string, use:
    // new String(event.getData().toBytes())
  }
}

ב-Java, משתמשים ב-Functions Framework Java API כדי להטמיע מחלקה של handler של CloudEvent עם הממשק CloudEventsFunction. השיטה accept() חייבת לקבל אובייקט CloudEvent כארגומנט ולבצע עיבוד של האירוע.

נקודת הכניסה של הפונקציה היא השם המלא של מחלקת הטיפול ב-CloudEvent, כולל שם החבילה. בדוגמה הזו, נקודת הכניסה היא mycloudeventfunction.MyCloudEventFunction.

‎.NET

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 using $event->getData()
}

ב-PHP, רושמים פונקציית handler של CloudEvent באמצעות Functions Framework for PHP. פונקציית ה-handler צריכה לקבל ארגומנט שתואם לממשק CloudEventInterface.

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

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

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

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

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

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

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

המאמרים הבאים

• טריגרים של פונקציות
• פריסת פונקציה ב-Cloud Run
• מידע על החוזה של Functions Framework