يمكنك تشغيل دالة من خلال طلب HTTP باستخدام
functions.https
. يتيح لك ذلك استدعاء دالة متزامنة من خلال طرق HTTP المتوافقة التالية: GET
وPOST
وPUT
وDELETE
وOPTIONS
.
تستند الأمثلة الواردة في هذه الصفحة إلى دالة نموذجية يتم تشغيلها عند إرسال طلب HTTP GET
إلى نقطة نهاية الدوال. تستردّ الدالة النموذجية وقت الخادم الحالي، وتنسّق الوقت كما هو محدّد في مَعلَمة طلب بحث عنوان URL، وترسل النتيجة في استجابة HTTP.
تشغيل دالة باستخدام طلب HTTP
استخدِم functions.https
لإنشاء دالة تعالج أحداث HTTP. يستمع معالج الأحداث الخاص بوظيفة HTTP إلى حدث onRequest()
، الذي يتيح استخدام الموجهات والتطبيقات التي تديرها Express، وهي إطار عمل للويب.
استخدام عناصر الطلبات والاستجابات في Express
يمنحك الكائن Request، الذي يتم استخدامه كمعلمات للدالة onRequest()
، إمكانية الوصول إلى خصائص طلب HTTP الذي أرسله العميل، كما يمنحك الكائن Response طريقة لإرسال ردّ إلى العميل.
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
إذا واجهت أخطاء في الأذونات عند نشر الدوال، تأكَّد من أنّ أدوار إدارة الهوية وإمكانية الوصول (IAM) المناسبة ممنوحة للمستخدم الذي ينفّذ أوامر النشر.
باستخدام ميزة "توجيه التطبيقات السريع"، تتم إضافة اسم الدالة كبادئة لمسارات عناوين 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 يساوي "يوسف" |
application/octet-stream |
'my text' | request.body تساوي 6d792074657874 (وحدات البايت الأولية للطلب، يمكنك الاطّلاع على مستندات Node.js Buffer) |
text/plain |
'my text' | 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;
إنهاء دوال 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