وظائف الاستدعاء من خلال طلبات 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.js

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

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

Python

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.js

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

Python

@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.js

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

Python

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.js

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

Python

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

إنهاء وظائف HTTP

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

Node.js

احرص دائمًا على إنهاء دالة 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

Python

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.