استدعاء الدوال من خلال طلبات HTTP (الجيل الأول)

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

تستند الأمثلة في هذه الصفحة إلى نموذج دالة يتم تشغيله عند إرسال طلب HTTP GET إلى نقطة نهاية الدوال. تسترد الدالة النموذجية وقت الخادم الحالي، وتنسّق الوقت كما هو محدّد في مَعلمة طلب بحث عنوان URL، وترسل النتيجة في استجابة HTTP.

تفعيل دالة باستخدام طلب HTTP

استخدِم functions.https لإنشاء دالة تعالج أحداث HTTP. يستمع معالج الأحداث لدالة HTTP إلى الحدث onRequest()، الذي يتوافق مع أجهزة التوجيه والتطبيقات التي يديرها إطار عمل الويب Express.

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

يتم استخدام الكائنين Request و Response كوسيطات للدالة onRequest()، حيث يتيح لك الكائن Request الوصول إلى خصائص طلب HTTP الذي أرسله العميل، بينما يتيح لك الكائن Response إرسال استجابة إلى العميل.

exports.date = functions.https.onRequest((req, res) => {
  // ...
});

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

باستخدام App كوسيطة لـ onRequest()، يمكنك تمرير تطبيق Express كامل إلى دالة HTTP. يمكن نقل الرمز البرمجي النموذجي إلى البرمجيات الوسيطة كما هو موضّح:

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

const app = express();

// Automatically allow cross-origin requests
app.use(cors({ origin: true }));

// 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 = functions.https.onRequest(app);

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

بعد نشر دالة HTTP، يمكنك استدعاؤها من خلال عنوان URL الفريد الخاص بها. يتضمّن عنوان URL ما يلي بالترتيب:

  • المنطقة (أو المناطق) التي نشرت فيها الدالة قد تحتاج بعض دوال الإنتاج إلى ضبط الموقع الجغرافي بشكل صريح لتقليل وقت استجابة الشبكة.
  • رقم تعريف مشروع Firebase الخاص بك
  • cloudfunctions.net
  • اسم الدالة

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

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

إذا واجهت أخطاء في الأذونات عند نشر الدوال، تأكَّد من أنّه تم منح أدوار إدارة الهوية وإمكانية الوصول المناسبة للمستخدم الذي يشغّل أوامر النشر.

باستخدام ميزة "توجيه التطبيق السريع"، تتم إضافة اسم الدالة كبادئة إلى مسارات عناوين URL في التطبيق الذي تحدّده. على سبيل المثال، عنوان URL لاستدعاء دالة getter في مثال تطبيق Express أعلاه يبدو كالتالي:

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

إذا كنت تستدعي دوال HTTP من خلف جدار حماية أو فلتر عناوين IP، يمكنك البحث عن عناوين IP التي تستخدمها Google لعرض دوال HTTP.

استخدام وحدات البرمجيات الوسيطة مع Cloud Functions

إذا كنت بحاجة إلى إدخال تبعيات البرمجيات الوسيطة لأمور مثل دعم ملفات تعريف الارتباط أو CORS، يمكنك استدعاء هذه التبعيات داخل الدالة. على سبيل المثال، لتفعيل ميزة "مشاركة الموارد المتعدّدة المصادر" (CORS)، أضِف الكتلة التالية:

// Enable CORS using the `cors` express middleware.
cors(req, res, () => {
  // ...
});

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

يسرد الجدول التالي بعض السيناريوهات الشائعة:

نوع المحتوى نص الطلب السلوك
application/json '{"name":"John"}' ‫request.body.name يساوي "John"
application/octet-stream 'my text' ‫request.body تساوي '6d792074657874' (وحدات البايت الأولية للطلب، راجِع مستندات Node.js Buffer)
text/plain 'my text' ‫request.body يساوي "my text"
application/x-www-form-urlencoded 'name=John' ‫request.body.name يساوي "John"

يتم إجراء هذا التحليل من خلال المحلّلات اللغوية التالية:

لنفترض أنّه تم استدعاء الدالة باستخدام الطلب التالي:

curl -X POST -H "Content-Type:application/json" -H "X-MyHeader: 123" YOUR_HTTP_TRIGGER_ENDPOINT?foo=baz -d '{"text":"something"}'

سيتم بعد ذلك تجسيد البيانات المُرسَلة ضمن:

السمة/الطريقة القيمة
req.method "POST"
req.get('x-myheader') "123"
req.query.foo "baz"
req.body.text "شيء"
req.rawBody وحدات البايت الأولية (غير المحلَّلة) للطلب

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

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

إنهاء دوال HTTP

يجب دائمًا إنهاء دالة HTTP باستخدام send() أو redirect() أو end(). وإلا، قد تستمر الدالة في العمل ويتم إنهاؤها بالقوة بواسطة النظام. يمكنك أيضًا الاطّلاع على المزامنة وغير المتزامنة والوعود.

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

const formattedDate = moment().format(`${format}`);
functions.logger.log('Sending Formatted date:', formattedDate);
res.status(200).send(formattedDate);

ربط دوال HTTP بـ "Firebase Hosting"

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