‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

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

בעזרת Functions Framework אתם יכולים לכתוב פונקציות Cloud Run שמגיבות לבקשות HTTP או מעבדות אירועים בענן. אתם יכולים להטמיע גורמים מטפלים ב-HTTP ל-webhooks ולנקודות קצה של כתובות URL, או גורמים מטפלים מבוססי-אירועים שמופעלים על ידי שירותים כמו Pub/Sub ו-Cloud Storage.

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

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

בעזרת Functions Framework אפשר:

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

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

נקודת הכניסה של הפונקציה
סוג החתימה

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

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

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

סוג החתימה

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

פונקציות HTTP: רישום של פונקציית handler של HTTP. משתמשים בפונקציית HTTP כשהפונקציה צריכה נקודת קצה (endpoint) של כתובת URL וחייבת להגיב לבקשות HTTP, כמו במקרה של תגובות לפעילות אינטרנט (webhooks).
פונקציות מבוססות-אירועים, שנקראות גם פונקציות 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"
}

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

למידע נוסף, קראו את הסקירה הכללית על סביבת זמן הריצה של Node.js ואת Functions Framework ל-Node.js.

Python

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

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

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

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

functions-framework==3.*

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

למידע נוסף, קראו את הסקירה הכללית על סביבת זמן הריצה של Python ואת Functions Framework ל-Python.

המשך

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

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

הפונקציה צריכה להיות בחבילת Go ברמה הבסיסית (root) של הפרויקט. החבילה וקובצי המקור שלה יכולים להיות בכל שם, אבל הפונקציה לא יכולה להיות ב-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
)

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

למידע נוסף, קראו את הסקירה הכללית על סביבת זמן הריצה של Go ואת Functions Framework ל-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/.

קובץ ה-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 ואת המאמר Functions Framework ל-Java.

‎.NET

זהו מבנה הספרייה הבסיסי של פונקציות ‎ .NET:

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

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

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

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

למידע נוסף, קראו את הסקירה הכללית על סביבת זמן הריצה של ‎.NET ואת המאמר Functions Framework ל-‎ .NET.

Ruby

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

.
├── app.rb
├── Gemfile
└── Gemfile.lock

‫Cloud Run טוען קוד מקור מקובץ בשם app.rb ברמה הבסיסית (root) של ספריית הפונקציות. הקובץ הראשי צריך להיקרא app.rb.

קובץ Gemfile צריך לכלול את Functions Framework for Ruby כתלות:

source "https://rubygems.org"
gem "functions_framework", "~> 1.0"

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

למידע נוסף, קראו את הסקירה הכללית על סביבת זמן הריצה של Ruby ואת המאמר Functions Framework ל-Ruby.

PHP

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

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

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

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

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

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

למידע נוסף, קראו את הסקירה הכללית על סביבת זמן הריצה של PHP ואת המאמר Functions Framework ל-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';
// Register an HTTP function with the Functions Framework that executes
// when you make an HTTP request to the deployed function's endpoint.
http('helloGET', (req, res) => {
  res.send('Hello World!');
});

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

{
  "name": "nodejs-docs-samples-functions-hello-world-get",
  "version": "0.0.1",
  "private": true,
  "license": "Apache-2.0",
  "author": "Google Inc.",
  "repository": {
    "type": "git",
    "url": "https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git"
  },
  "engines": {
    "node": ">=16.0.0"
  },
  "scripts": {
    "test": "c8 mocha -p -j 2 test/*.test.js --timeout=6000 --exit"
  },
  "dependencies": {
    "@google-cloud/functions-framework": "^3.1.0"
  },
  "devDependencies": {
    "c8": "^10.0.0",
    "gaxios": "^6.0.0",
    "mocha": "^10.0.0",
    "wait-port": "^1.0.4"
  }
}

מודול CommonJS

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

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

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

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

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

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

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

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

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. פונקציית ה-HTTP handler צריכה לקבל אובייקט בקשת Flask כארגומנט, ולהחזיר ערך ש-Flask יכולה להמיר לאובייקט תגובת HTTP.

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

המשך

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

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

פונקציית ה-HTTP handler צריכה להטמיע את הממשק הרגיל של 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. ה-method‏ service() חייבת לשלוח תגובת HTTP.

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

ה-method‏ 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 כדי להטמיע מחלקה של handler ל-HTTP עם הממשק IHttpFunction. ה-method‏ HandleAsync() מקבלת אובייקט HttpContext סטנדרטי של ASP.NET כארגומנט, וחייבת לשלוח תגובת HTTP.

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

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

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

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

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

כשמגדירים ספק אירועים לשליחת בקשות HTTP לפונקציית Cloud Run, הפונקציה שולחת תגובת HTTP. אם הפונקציה יוצרת משימות ברקע (למשל, באמצעות שרשורים, אובייקטים של Promise ב-JavaScript, פונקציות קריאה חוזרת או תהליכי מערכת), צריך לסיים את המשימות האלה או לטפל בהן בדרך אחרת לפני ששולחים תגובת 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 שדורשות אימות. בגלל שהבקשות המקדימות נכשלות, גם הבקשות הראשיות נכשלות. כדי לעקוף את המגבלה הזו, אפשר להשתמש באחת מהאפשרויות הבאות:

לאפשר גישה ציבורית לפונקציה.
מגדירים את שרת ה-Proxy לאימות זהויות (IAP) לפונקציה, שמספק את כותרת ההרשאה לבקשות 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 ל-Node.js. פונקציית ה-handler צריכה לקבל אובייקט CloudEvent כארגומנט.

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

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

המשך

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 של CloudEvent באמצעות Functions Framework ל-Go. פונקציית ה-handler צריכה לקבל אובייקט event.Event של CloudEvents כארגומנט.

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

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

סוג הארגומנט של המטען הייעודי (payload) של נתוני CloudEvent, שמוצג בקוד לדוגמה בתור CloudEventDataType, צריך להתאים לסוג האירוע שהפונקציה מטפלת בו. ספריית Google CloudEvents .NET מספקת סוגי נתונים לאירועים השונים שנתמכים על ידי 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 ל-Ruby. פונקציית ה-handler צריכה לקבל אובייקט Event של CloudEvents כארגומנט.

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

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

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

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

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

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

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

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

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

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

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

סוג החתימה

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

Node.js

Python

המשך

Java

‎.NET

Ruby

PHP

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

Node.js

מודול ES

מודול CommonJS

Python

המשך

Java

‎.NET

Ruby

PHP

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

טיפול ב-CORS

Node.js

Python

Go

Java

‎.NET

Ruby

PHP

מגבלות של CORS

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

Node.js

מודול ES

מודול CommonJS

Python

המשך

Java

‎.NET

Ruby

PHP

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

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

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

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