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

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

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

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

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

استخدام كائنَي الطلب والاستجابة في 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

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

باستخدام توجيه تطبيقات Express، تتم إضافة اسم الدالة كبادئة لمسارات عناوين 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 "something"
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.