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


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

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

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

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

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

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

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

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

استخدام وحدات الوسيط مع Cloud Functions

إذا كنت بحاجة إلى إدخال تبعيات البرمجيات الوسيطة لأشياء مثل إتاحة ملفات تعريف الارتباط أو قم باستدعاء هذه العناصر ضمن الدالة. على سبيل المثال، لتفعيل دعم سياسة مشاركة الموارد المتعددة المصادر (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.