دوال الاستدعاء عبر طلبات HTTP

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

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

تشغيل دالة باستخدام طلب HTTP

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

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

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

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

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

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

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

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

نوع المحتوى	نص الطلب	السلوك
`application/json`	`'{"name":"John"}'`	الحقل `request.body.name` يساوي "يوسف".
`application/octet-stream`	"نصي"	`request.body` تساوي "6d792074657874" (وحدات البايت الأولية للطلب، ويمكنك مراجعة وثائق التخزين المؤقت لـ Node.js)
`text/plain`	"نصي"	`request.body` يساوي "النص"
`application/x-www-form-urlencoded`	"name=John"	الحقل `request.body.name` يساوي "يوسف".

يتم إجراء هذا التحليل باستخدام برامج تحليل النص الأساسي التالية:

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

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

إنهاء دوال 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);index.js

ربط دوال HTTP باستضافة Firebase

يمكنك ربط وظيفة HTTP بـ "استضافة Firebase". يمكن إنشاء خادم وكيل للطلبات على موقع "استضافة Firebase" الإلكتروني مع وظائف HTTP محدّدة. كما يتيح لك ذلك استخدام نطاقك الخاص مع دالة HTTP. تعرَّف على مزيد من المعلومات عن ربط دوال Cloud باستضافة Firebase.