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


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

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

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

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

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

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

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

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

باستخدام التطبيق كوسيطة لـ 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 لاستدعاء دالة الحصول في مثال تطبيق 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 يساوي "يوسف"
application/octet-stream 'my text' request.body يساوي ‎6d792074657874 (البايت الأوّلي للطلب، راجِع مستندات Node.js Buffer)
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 مشاركة
req.get('x-myheader') "123"
req.query.foo "baz"
req.body.text "something"
req.rawBody وحدات البايت الأوّلية (غير المفسَّرة) للطلب

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

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

إنهاء وظائف HTTP

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

بعد استرداد وقت الخادم وتنسيقه باستخدام وحدة 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 Hosting

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