وظائف الاستدعاء من خلال طلبات HTTP

الجيل الثاني الجيل الأول

يمكنك تنشيط وظيفة من خلال طلب HTTP باستخدام معالج طلب. يتيح لك ذلك استدعاء دالة من خلال طُرق HTTP المتوافقة التالية: GET وPOST وPUT وDELETE و OPTIONS.

خيارات HTTP الإضافية

Option	الوصف
region	يمكن أن تحدِّد دوالّ HTTP صفيفًا من المناطق بالإضافة إلى منطقة واحدة. عند تحديد مناطق متعدّدة، سيتم نشر نسخة منفصلة من الدالة لكل منطقة.
‫timeoutSeconds (timeout_sec لبرنامج Python)	يمكن أن تحدِّد دوالّ HTTP مهلة تصل إلى ساعة واحدة.
cors	يمكن أن تحدِّد دوالّ HTTP سياسات CORS. يمكنك ضبط هذا الخيار على true للسماح لجميع المصادر أو string أو regex أو array لتحديد المصادر المسموح بها. يتم ضبط القيمة تلقائيًا على خطأ/بدون سياسات مشاركة الموارد المتعدّدة المصادر (CORS) في حال عدم ضبطها بشكل صريح.

ضبط سياسة مشاركة الموارد المتعدّدة المصادر (CORS)

استخدِم الخيار cors للتحكّم في مصادر البيانات التي يمكنها الوصول إلى وظيفتك. لا يتم ضبط بروتوكول CORS تلقائيًا في وظائف HTTP، ما يعني أنّ أي طلب من مصدر مختلف إلى وظيفتك يؤدي إلى ظهور هذا الخطأ:

request has been blocked by CORS policy: No 'Access-Control-Allow-Origin' header is present on the requested resource.

يمكنك أيضًا إيقاف CORS صراحةً من خلال ضبط الخيار cors على false لدالة.

للسماح ببعض طلبات المصادر المختلفة، وليس كلها، يمكنك تمرير قائمة بنطاقات أو تعبيرات منتظمة محدّدة يجب السماح بها. على سبيل المثال، إذا كان لديك النطاقان firebase.com وflutter.com، وكان بإمكان firebase.com أن يتضمّن العديد من النطاقات الفرعية، يمكنك ضبط الخيار cors على [/firebase\.com$/, 'flutter.com'] لاستخدام Node.js أو [r'firebase\.com$', r'https://flutter\.com'] لاستخدام Python:

Node.jsPython

const { onRequest } = require("firebase-functions/v2/https");

exports.sayHello = onRequest(
  { cors: [/firebase\.com$/, "flutter.com"] },
  (req, res) => {
    res.status(200).send("Hello world!");
  }
);

from firebase_functions import https_fn, options

@https_fn.on_request(
    cors=options.CorsOptions(
        cors_origins=[r"firebase\.com$", r"https://flutter\.com"],
        cors_methods=["get", "post"],
    )
)
def say_hello(req: https_fn.Request) -> https_fn.Response:
    return https_fn.Response("Hello world!")

إذا كان يجب أن تكون وظيفتك متاحة بشكل علني، على سبيل المثال إذا كانت تقدّم واجهة برمجة تطبيقات أو موقعًا إلكترونيًا متاحَين للجميع، اضبط سياسة cors على true.

بدء دالة باستخدام طلب HTTP

استخدِم معالِج الطلبات لنظامك الأساسي (onRequest() أو on_request) لإنشاء دالة تعالج أحداث HTTP. تستند الأمثلة الواردة في هذا القسم إلى نموذج "خادم الوقت" الذي يتم تشغيله عند إرسال طلب HTTP GET إلى نقطة نهاية الدوالّ. تسترجع الدالة النموذجية وقت الخادم الحالي، وتُعدّل الوقت على النحو المحدّد في مَعلمة طلب بحث عنوان URL، وتُرسِل النتيجة في استجابة HTTP.

استخدام عناصر الطلب والاستجابة

يمنحك عنصر الطلب إمكانية الوصول إلى سمات طلب HTTP الذي أرسله العميل، ويمنحك عنصر الاستجابة طريقة لإرسال استجابة إلى العميل.

Node.jsPython

exports.date = onRequest(
    {timeoutSeconds: 1200, region: ["us-west1", "us-east1"]},
    (req, res) => {
// ...
});

@https_fn.on_request(cors=options.CorsOptions(cors_origins="*", cors_methods=["get", "post"]))
def date(req: https_fn.Request) -> https_fn.Response:
    """Get the server's local date and time."""
main.py

ملاحظة مهمة: تأكَّد من أنّ جميع وظائف HTTP تنتهي بشكلٍ سليم. من خلال إنهاء الدوالّ بشكلٍ صحيح، يمكنك تجنُّب الرسوم المفرطة للدوالّ التي تعمل لفترة طويلة جدًا.

استخدام تطبيقات Express أو Flask الحالية

باستخدام التطبيق كوسيطة لمعالج الطلب، يمكنك تمرير تطبيق كامل إلى دالة HTTP:

Node.jsPython

const { onRequest } = require('firebase-functions/v2/https');

const express = require('express');
const app = express();

// Add middleware to authenticate requests
app.use(myMiddleware);

// build multiple CRUD interfaces:
app.get('/:id', (req, res) => res.send(Widgets.getById(req.params.id)));
app.post('/', (req, res) => res.send(Widgets.create()));
app.put('/:id', (req, res) => res.send(Widgets.update(req.params.id, req.body)));
app.delete('/:id', (req, res) => res.send(Widgets.delete(req.params.id)));
app.get('/', (req, res) => res.send(Widgets.list()));

// Expose Express API as a single Cloud Function:
exports.widgets = onRequest(app);

from firebase_admin import initialize_app, db
from firebase_functions import https_fn
import flask

initialize_app()
app = flask.Flask(__name__)

# Build multiple CRUD interfaces:


@app.get("/widgets")
@app.get("/widgets/<id>")
def get_widget(id=None):
    if id is not None:
        return db.reference(f"/widgets/{id}").get()
    else:
        return db.reference("/widgets").get()


@app.post("/widgets")
def add_widget():
    new_widget = flask.request.get_data(as_text=True)
    db.reference("/widgets").push(new_widget)
    return flask.Response(status=201, response="Added widget")


# Expose Flask app as a single Cloud Function:


@https_fn.on_request()
def httpsflaskexample(req: https_fn.Request) -> https_fn.Response:
    with app.request_context(req.environ):
        return app.full_dispatch_request()
main.py

استدعاء دالة HTTP

بعد نشر دالة HTTP، يمكنك استدعاؤها من خلال عنوان URL الفريد الخاص بها. استخدِم عنوان URL الدقيق الذي يتم عرضه من وحدة تحكّم سطر الأوامر بعد النشر.

على سبيل المثال، يبدو عنوان URL لاستدعاء date() على النحو التالي:

https://us-central1-<project-id>.cloudfunctions.net/date

باستخدام مسار تطبيق Express وFlask، تتم إضافة اسم الدالة كبادئة إلى مسارات عناوين URL في التطبيق الذي تحدّده.

قراءة القيم من الطلب

في مثال الدالة date()، تختبر الدالة كلّ من مَعلمة عنوان URL و النص بحثًا عن قيمة format لضبط تنسيق التاريخ/الوقت المراد استخدامه:

Node.jsPython

let format = req.query.format;
format = req.body.format;
index.js

format = req.args["format"] if "format" in req.args else None
main.py

إنهاء وظائف HTTP

بعد استرداد وقت الخادم وتنسيقه، تنتهي الدالة date() بإرسال النتيجة في استجابة HTTP:

Node.jsPython

احرص دائمًا على إنهاء وظيفة HTTP بـ send() أو redirect() أو end(). بخلاف ذلك، قد يستمر تشغيل الدالة وقد يتم إيقافها بشكل قسري من قِبل النظام. راجِع أيضًا Sync وAsync وPromises.

const formattedDate = moment().format(`${format}`);
logger.log("Sending formatted date:", formattedDate);
res.status(200).send(formattedDate);
index.js

formatted_date = datetime.now().strftime(format)
print(f"Sending Formatted date: {formatted_date}")
return https_fn.Response(formatted_date)
main.py

الدمج مع "استضافة Firebase"

يمكنك ربط دالة HTTP بـ Firebase Hosting. يمكن تمثيل الطلبات على موقعك الإلكتروني Firebase Hosting من خلال وظائف HTTP معيّنة. يتيح لك ذلك أيضًا استخدام نطاقك المخصّص مع دالة HTTP. اطّلِع على مزيد من المعلومات عن ربط Cloud Functions بـ Firebase Hosting.