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

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

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

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

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

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

عند استخدامه كوسيطات في onRequest()، يمنحك كائن الطلب إمكانية الوصول إلى خصائص طلب 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.

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

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

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

• محلل النص الأساسي JSON
• محلل لغة أولية للجسم
• المحلل اللغوي لنص النص
• محلل النص الأساسي للنموذج بترميز عنوان URL

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

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	"شيء ما"
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.