البرنامج التعليمي: مصادقة خدمة Azure SignalR باستخدام Azure Functions

في هذا البرنامج التعليمي خطوة بخطوة، يمكنك إنشاء غرفة محادثة مع المصادقة والمراسلة الخاصة باستخدام هذه التقنيات:

• Azure Functions: واجهة برمجة تطبيقات خلفية لمصادقة المستخدمين وإرسال رسائل الدردشة.
• خدمة Azure SignalR: خدمة لبث رسائل جديدة إلى عملاء الدردشة المتصلة.
• Azure Storage: خدمة التخزين التي تتطلبها Azure Functions.
• Azure App Service: الخدمة التي توفر مصادقة المستخدم.

الطراز v4

إشعار

يمكنك الحصول على التعليمات البرمجية المذكورة في هذه المقالة من GitHub.

الطراز v3

إشعار

يمكنك الحصول على التعليمات البرمجية المذكورة في هذه المقالة من GitHub.

المتطلبات الأساسية

• حساب Azure مع اشتراك نشط. إذا لم يكن لديك مثل هذا الحساب، فيمكنك إنشاء واحد مجانًا.
• Node.js (الإصدار 20.x).
• Azure Functions Core Tools (الإصدار 4).

هل تواجه مشكلات؟ أبلغنا بها.

إنشاء موارد أساسية على Azure

إنشاء مورد Azure SignalR Service

سيدخل تطبيقك إلى مثيل Azure SignalR Service. استخدم الخطوات التالية لإنشاء مثيل Azure SignalR Service باستخدام مدخل Microsoft Azure:

1. في مدخل Microsoft Azure، حدد الزر Create a resource (+).

2. ابحث عن SignalR Service وحدده.

3. حدد إنشاء.

4. أدخل المعلومات التالية.

   الاسم	القيمة‬
   مجموعة الموارد	إنشاء مجموعة موارد جديدة باسم فريد.
   اسم المورد	أدخل اسما فريدا لمثيل خدمة Azure SignalR.
   المنطقة	حدد أقرب منطقة إليك.
   مستوى التسعير	حدد Free.
   وضع الخدمة	حدد بلا خادم.

5. حدد "استعراض + إنشاء".

6. حدد إنشاء.

هل تواجه مشكلات؟ أبلغنا بها.

إنشاء تطبيق دالة Azure وحساب تخزين Azure

1. من الصفحة الرئيسية في مدخل Microsoft Azure، حدد Create a resource (+).

2. ابحث عن Function App وحدده.

3. حدد إنشاء.

4. أدخل المعلومات التالية.

   الاسم	القيمة‬
   مجموعة الموارد	استخدم نفس مجموعة الموارد مع مثيل خدمة Azure SignalR.
   اسم تطبيق الوظائف	أدخل اسما فريدا لتطبيق الوظائف.
   مكدس وقت التشغيل	حدد Node.js.
   المنطقة	حدد أقرب منطقة إليك.

5. بشكل افتراضي، يتم إنشاء حساب تخزين Azure جديد في نفس مجموعة الموارد جنبا إلى جنب مع تطبيق الوظائف الخاص بك. إذا كنت تريد استخدام حساب تخزين آخر في تطبيق الوظائف، فانتقل إلى علامة التبويب Hosting لاختيار حساب.

6. حدد «Review + Create»، ثم حدد «Create».

إنشاء مشروع Azure Functions محليا

تهيئة تطبيق دالة

1. من سطر الأوامر، قم بإنشاء مجلد جذر لمشروعك وقم بالتغيير إلى المجلد.

2. قم بتشغيل الأمر التالي في المحطة الطرفية لإنشاء مشروع وظائف JavaScript جديد:

الطراز v4

func init --worker-runtime node --language javascript --name my-app --model V4

الطراز v3

func init --worker-runtime node --language javascript --name my-app --model V3

بشكل افتراضي، يتضمن المشروع الذي تم إنشاؤه ملف host.json يحتوي على حزم الملحقات التي تتضمن ملحق SignalR. لمزيد من المعلومات حول حزم الملحقات، راجع تسجيل ملحقات ربط وظائف Azure.

تكوين إعدادات التطبيق

عند تشغيل وقت تشغيل Azure Functions وتصحيحه محليا، يقرأ تطبيق الوظائف إعدادات التطبيق من local.settings.json. قم بتحديث هذا الملف مع سلسلة الاتصال مثيل Azure SignalR Service وحساب التخزين الذي قمت بإنشائه سابقا.

استبدل محتوى local.settings.json بالتعليمات البرمجية التالية:

{
  "IsEncrypted": false,
  "Values": {
    "FUNCTIONS_WORKER_RUNTIME": "node",
    "AzureWebJobsStorage": "<your-storage-account-connection-string>",
    "AzureSignalRConnectionString": "<your-Azure-SignalR-connection-string>"
  }
}

في التعليمات البرمجية السابقة:

• أدخل سلسلة الاتصال خدمة Azure SignalR في AzureSignalRConnectionString الإعداد.

  للحصول على السلسلة، انتقل إلى مثيل خدمة Azure SignalR في مدخل Microsoft Azure. في قسم الإعدادات، حدد موقع إعداد Keys. حدد الزر نسخ إلى يمين سلسلة الاتصال لنسخه إلى الحافظة. يمكنك استخدام سلسلة الاتصال الأساسي أو الثانوي.

• أدخل حساب التخزين سلسلة الاتصال في AzureWebJobsStorage الإعداد.

  للحصول على السلسلة، انتقل إلى حساب التخزين الخاص بك في مدخل Microsoft Azure. في قسم الأمان + الشبكات، حدد موقع إعداد مفاتيح الاختصار. حدد الزر نسخ إلى يمين سلسلة الاتصال لنسخه إلى الحافظة. يمكنك استخدام سلسلة الاتصال الأساسي أو الثانوي.

هل تواجه مشكلات؟ أبلغنا بها.

إنشاء دالة لمصادقة المستخدمين على Azure SignalR Service

عند فتح تطبيق الدردشة لأول مرة في المتصفح، يتطلب بيانات اعتماد اتصال صالحة للاتصال بخدمة Azure SignalR Service. إنشاء دالة مشغل HTTP المسماة negotiate في تطبيق الوظائف الخاص بك لإرجاع معلومات الاتصال هذه.

إشعار

يجب تسمية negotiate هذه الدالة لأن عميل SignalR يتطلب نقطة نهاية تنتهي ب /negotiate.

الطراز v4

1. من مجلد المشروع الجذر، قم بإنشاء الدالة negotiate من قالب مضمن باستخدام الأمر التالي:

   func new --template "HTTP trigger" --name negotiate
   

2. افتح src/functions/negotiate.js، وحدث المحتوى كما يلي:

   const { app, input } = require('@azure/functions');
   
   const inputSignalR = input.generic({
       type: 'signalRConnectionInfo',
       name: 'connectionInfo',
       hubName: 'default',
       connectionStringSetting: 'AzureSignalRConnectionString',
   });
   
   app.post('negotiate', {
       authLevel: 'anonymous',
       handler: (request, context) => {
           return { body: JSON.stringify(context.extraInputs.get(inputSignalR)) }
       },
       route: 'negotiate',
       extraInputs: [inputSignalR],
   });
   

   تحتوي الدالة على ربط مشغل HTTP لتلقي الطلبات من عملاء SignalR. تحتوي الدالة أيضا على ربط إدخال SignalR لإنشاء بيانات اعتماد صالحة للعميل للاتصال بمركز خدمة Azure SignalR المسمى default.

   تأخذ هذه الدالة معلومات اتصال SignalR من ربط الإدخال وتعيدها إلى العميل في نص استجابة HTTP.

   لا userId توجد خاصية في signalRConnectionInfo الربط للتطوير المحلي. ستضيفه لاحقا لتعيين اسم المستخدم لاتصال SignalR عند نشر تطبيق الوظائف إلى Azure.

الطراز v3

1. من مجلد المشروع الجذر، قم بإنشاء الدالة negotiate من قالب مضمن باستخدام الأمر التالي:

   func new --template "SignalR negotiate HTTP trigger" --name negotiate
   

2. افتح negotiate/function.json لعرض تكوين ربط الدالة.

   تحتوي الدالة على ربط مشغل HTTP لتلقي الطلبات من عملاء SignalR. تحتوي الدالة أيضا على ربط إدخال SignalR لإنشاء بيانات اعتماد صالحة للعميل للاتصال بمركز خدمة Azure SignalR المسمى default.

   {
     "disabled": false,
     "bindings": [
       {
         "authLevel": "anonymous",
         "type": "httpTrigger",
         "direction": "in",
         "methods": ["post"],
         "name": "req",
         "route": "negotiate"
       },
       {
         "type": "http",
         "direction": "out",
         "name": "res"
       },
       {
         "type": "signalRConnectionInfo",
         "name": "connectionInfo",
         "hubName": "default",
         "connectionStringSetting": "AzureSignalRConnectionString",
         "direction": "in"
       }
     ]
   }
   

   لا userId توجد خاصية في signalRConnectionInfo الربط للتطوير المحلي. ستضيفه لاحقا لتعيين اسم المستخدم لاتصال SignalR عند نشر تطبيق الوظائف إلى Azure.

3. أغلق ملف التفاوض/function.json.

4. افتح negotiate/index.js لعرض نص الدالة:

   module.exports = async function (context, req, connectionInfo) {
     context.res.body = connectionInfo;
   };
   

   تأخذ هذه الوظيفة معلومات اتصال SignalR من ربط الإدخال وتعيدها إلى العميل في النص الأساسي لاستجابة HTTP. يستخدم عميل SignalR هذه المعلومات للاتصال بمثيل خدمة Azure SignalR.

هل تواجه مشكلات؟ أبلغنا بها.

إنشاء وظيفة لإرسال رسائل الدردشة

يتطلب تطبيق الويب أيضًا وجود واجهة برمجة تطبيقات HTTP لإرسال رسائل الدردشة. إنشاء دالة مشغل HTTP التي ترسل رسائل إلى جميع العملاء المتصلين الذين يستخدمون Azure SignalR Service:

الطراز v4

1. من مجلد المشروع الجذر، قم بإنشاء دالة مشغل HTTP المسماة sendMessage من القالب باستخدام الأمر التالي:

   func new --name sendMessage --template "Http trigger"
   

2. افتح ملف src/functions/sendMessage.js ، وحدث المحتوى كما يلي:

   const { app, output } = require('@azure/functions');
   
   const signalR = output.generic({
       type: 'signalR',
       name: 'signalR',
       hubName: 'default',
       connectionStringSetting: 'AzureSignalRConnectionString',
   });
   
   app.http('messages', {
       methods: ['POST'],
       authLevel: 'anonymous',
       extraOutputs: [signalR],
       handler: async (request, context) => {
           const message = await request.json();
           message.sender = request.headers && request.headers.get('x-ms-client-principal-name') || '';
   
           let recipientUserId = '';
           if (message.recipient) {
               recipientUserId = message.recipient;
               message.isPrivate = true;
           }
           context.extraOutputs.set(signalR,
               {
                   'userId': recipientUserId,
                   'target': 'newMessage',
                   'arguments': [message]
               });
       }
   });
   

   تحتوي الدالة على مشغل HTTP وربط إخراج SignalR. يأخذ النص الأساسي من طلب HTTP ويرسله إلى العملاء المتصلين بخدمة Azure SignalR. يستدعي دالة مسماة newMessage على كل عميل.

   يمكن للدالة قراءة هوية المرسل ويمكنها قبول recipient قيمة في نص الرسالة للسماح لك بإرسال رسالة بشكل خاص إلى مستخدم واحد. ستستخدم هذه الوظائف لاحقا في البرنامج التعليمي.

3. حفظ الملف.

الطراز v3

1. من مجلد المشروع الجذر، قم بإنشاء دالة مشغل HTTP المسماة sendMessage من القالب باستخدام الأمر التالي:

   func new --name sendMessage --template "Http trigger"
   

2. لتكوين روابط الدالة، استبدل محتوى sendMessage/function.json بالتعليمات البرمجية التالية:

   {
     "disabled": false,
     "bindings": [
       {
         "authLevel": "anonymous",
         "type": "httpTrigger",
         "direction": "in",
         "name": "req",
         "route": "messages",
         "methods": ["post"]
       },
       {
         "type": "http",
         "direction": "out",
         "name": "res"
       },
       {
         "type": "signalR",
         "name": "$return",
         "hubName": "default",
         "direction": "out"
       }
     ]
   }
   

   تقوم التعليمات البرمجية السابقة بإجراء تغييرين على الملف الأصلي:

   • يغير المسار إلى messages ويقيد مشغل HTTP إلى POST أسلوب HTTP.
   • يضيف ربط إخراج Azure SignalR Service الذي يرسل رسالة تم إرجاعها بواسطة الدالة إلى جميع العملاء المتصلين بمركز خدمة Azure SignalR المسمى default.

3. استبدل محتوى sendMessage/index.js بالتعليمات البرمجية التالية:

   module.exports = async function (context, req) {
     const message = req.body;
     message.sender =
       (req.headers && req.headers["x-ms-client-principal-name"]) || "";
   
     let recipientUserId = "";
     if (message.recipient) {
       recipientUserId = message.recipient;
       message.isPrivate = true;
     }
   
     return {
       userId: recipientUserId,
       target: "newMessage",
       arguments: [message],
     };
   };
   

   تأخذ هذه الدالة النص الأساسي من طلب HTTP وترسله إلى العملاء المتصلين بخدمة Azure SignalR. يستدعي دالة مسماة newMessage على كل عميل.

   يمكن للدالة قراءة هوية المرسل ويمكنها قبول recipient قيمة في نص الرسالة للسماح لك بإرسال رسالة بشكل خاص إلى مستخدم واحد. ستستخدم هذه الوظائف لاحقا في البرنامج التعليمي.

4. حفظ الملف.

هل تواجه مشكلات؟ أبلغنا بها.

استضافة واجهة مستخدم الويب لعميل الدردشة

واجهة مستخدم تطبيق الدردشة هي تطبيق بسيط من صفحة واحدة (SPA) تم إنشاؤه باستخدام إطار عمل Vue JavaScript باستخدام عميل ASP.NET Core SignalR JavaScript. للتبسيط، يستضيف تطبيق الدالة صفحة الويب. في بيئة الإنتاج، يمكنك استخدام Static Web Apps لاستضافة صفحة الويب.

الطراز v4

1. إنشاء ملف باسم index.html في الدليل الجذر لمشروع الدالة الخاص بك.

2. انسخ محتوى index.html والصقه في الملف. حفظ الملف.

3. من مجلد المشروع الجذر، قم بإنشاء دالة مشغل HTTP المسماة index من القالب باستخدام هذا الأمر:

   func new --name index --template "Http trigger"
   

4. تعديل محتوى src/functions/index.js إلى التعليمات البرمجية التالية:

   const { app } = require('@azure/functions');
   const { readFile } = require('fs/promises');
   
   app.http('index', {
       methods: ['GET'],
       authLevel: 'anonymous',
       handler: async (context) => {
           const content = await readFile('index.html', 'utf8', (err, data) => {
               if (err) {
                   context.err(err)
                   return
               }
           });
   
           return {
               status: 200,
               headers: {
                   'Content-Type': 'text/html'
               },
               body: content,
           };
       }
   });
   

   تقرأ الدالة صفحة الويب الثابتة وتعيدها إلى المستخدم.

5. اختبر تطبيقك محليا. ابدأ تشغيل تطبيق الدالة باستخدام هذا الأمر:

   func start
   

6. افتح http://localhost:7071/api/index في مستعرض الويب الخاص بك. يجب أن تظهر صفحة ويب دردشة.

   

7. أدخل رسالة في مربع الدردشة.

   بعد تحديد المفتاح Enter، تظهر الرسالة على صفحة الويب. نظرا لعدم تعيين اسم مستخدم عميل SignalR، فأنت ترسل جميع الرسائل بشكل مجهول.

الطراز v3

1. أنشئ مجلدا باسم content في الدليل الجذر لمشروع الدالة الخاص بك.

2. في مجلد المحتوى ، أنشئ ملفا باسم index.html.

3. انسخ محتوى index.html والصقه في الملف. حفظ الملف.

4. من مجلد المشروع الجذر، قم بإنشاء دالة مشغل HTTP المسماة index من القالب باستخدام هذا الأمر:

   func new --name index --template "Http trigger"
   

5. تعديل محتوى index/index.js إلى التعليمات البرمجية التالية:

   const fs = require("fs");
   
   module.exports = async function (context, req) {
     const fileContent = fs.readFileSync("content/index.html", "utf8");
   
     context.res = {
       // status: 200, /* Defaults to 200 */
       body: fileContent,
       headers: {
         "Content-Type": "text/html",
       },
     };
   };
   

   تقرأ الدالة صفحة الويب الثابتة وتعيدها إلى المستخدم.

6. افتح الفهرس/function.json، وغير authLevel قيمة الروابط إلى anonymous. الآن يبدو الملف بأكمله مثل هذا المثال:

   {
     "bindings": [
       {
         "authLevel": "anonymous",
         "type": "httpTrigger",
         "direction": "in",
         "name": "req",
         "methods": ["get", "post"]
       },
       {
         "type": "http",
         "direction": "out",
         "name": "res"
       }
     ]
   }
   

7. اختبر تطبيقك محليا. ابدأ تشغيل تطبيق الدالة باستخدام هذا الأمر:

   func start
   

8. افتح http://localhost:7071/api/index في مستعرض الويب الخاص بك. يجب أن تظهر صفحة ويب دردشة.

   

9. أدخل رسالة في مربع الدردشة.

   بعد تحديد المفتاح Enter، تظهر الرسالة على صفحة الويب. نظرا لعدم تعيين اسم مستخدم عميل SignalR، فأنت ترسل جميع الرسائل بشكل مجهول.

هل تواجه مشكلات؟ أبلغنا بها.

النشر على Azure وتمكين المصادقة

لقد كنت تقوم بتشغيل تطبيق الوظائف و تطبيق الدردشة محليا. الآن، قم بنشرها في Azure وتمكين المصادقة والمراسلة الخاصة.

تكوين تطبيق الدالة للمصادقة

يعمل تطبيق الدردشة دون الكشف عن الهوية حتى الآن. في Azure، ستستخدم مصادقة App Service لمصادقة المستخدم. يتم تمرير معرف المستخدم أو اسم المستخدم للمستخدم المصادق عليه إلى SignalRConnectionInfo الربط لإنشاء معلومات الاتصال المصادق عليها كمستخدم.

الطراز v4

1. افتح ملف src/functions/negotiate.js .

2. إدراج خاصية userId في inputSignalR الربط بالقيمة {headers.x-ms-client-principal-name}. هذه القيمة هي تعبير ربط يعين اسم المستخدم لعميل SignalR إلى اسم المستخدم المصادق عليه. يجب أن يبدو الربط الآن مثل هذا المثال:

   const inputSignalR = input.generic({
       type: 'signalRConnectionInfo',
       name: 'connectionInfo',
       hubName: 'default',
       connectionStringSetting: 'AzureSignalRConnectionString',
       userId: '{headers.x-ms-client-principal-name}'
   });
   

3. حفظ الملف.

الطراز v3

1. فتح التفاوض/function.json.

2. إدراج خاصية userId في SignalRConnectionInfo الربط بالقيمة {headers.x-ms-client-principal-name}. هذه القيمة هي تعبير ربط يعين اسم المستخدم لعميل SignalR إلى اسم المستخدم المصادق عليه. يجب أن يبدو الربط الآن مثل هذا المثال:

   {
     "type": "signalRConnectionInfo",
     "name": "connectionInfo",
     "userId": "{headers.x-ms-client-principal-name}",
     "hubName": "default",
     "direction": "in"
   }
   

3. حفظ الملف.

نشر تطبيق الوظائف إلى Azure

انشر تطبيق الدالة إلى Azure باستخدام الأمر التالي:

func azure functionapp publish <your-function-app-name> --publish-local-settings

ينشر --publish-local-settings الخيار إعداداتك المحلية من ملف local.settings.json إلى Azure، لذلك لا تحتاج إلى تكوينها في Azure مرة أخرى.

تمكين مصادقة App Service

تدعم Azure Functions المصادقة باستخدام معرف Microsoft Entra وFacebook وTwitter وحساب Microsoft وGoogle. ستستخدم Microsoft كموفر هوية لهذا البرنامج التعليمي.

1. في مدخل Microsoft Azure، انتقل إلى صفحة الموارد لتطبيق الوظائف.

2. حدد الإعدادات> مصادقة.

3. انقر فوق إضافة مزود الهوية.

   

4. في قائمة موفر الهوية، حدد Microsoft. بعد ذلك، حدد إضافة.

   

تنشئ الإعدادات المكتملة تسجيل تطبيق يربط موفر الهوية بتطبيق الوظائف.

لمزيد من المعلومات حول موفري الهوية المدعومين، راجع المقالات التالية:

• معرِّف Microsoft Entra
• Facebook
• موقع Twitter
• حساب Microsoft
• Google

جرب التطبيق

1. افتح https://<YOUR-FUNCTION-APP-NAME>.azurewebsites.net/api/index.
2. حدد تسجيل الدخول للمصادقة باستخدام موفر المصادقة الذي اخترته.
3. أرسل رسائل عامة عن طريق إدخالها في مربع الدردشة الرئيسي.
4. أرسل رسائل خاصة عن طريق تحديد اسم مستخدم في محفوظات الدردشة. يتلقى المستلم المحدد هذه الرسائل فقط.

تهانينا! لقد قمت بنشر تطبيق دردشة بدون خادم في الوقت الفعلي.

هل تواجه مشكلات؟ أبلغنا بها.

تنظيف الموارد

لتنظيف الموارد التي قمت بإنشائها في هذا البرنامج التعليمي، احذف مجموعة الموارد باستخدام مدخل Microsoft Azure.

تنبيه

يؤدي حذف مجموعة الموارد إلى حذف كافة الموارد التي تحتوي عليها. إذا كانت مجموعة الموارد تحتوي على موارد خارج نطاق هذا البرنامج التعليمي، يتم حذفها أيضا.

هل تواجه مشكلات؟ أبلغنا بها.

الخطوات التالية

في هذا البرنامج التعليمي، تعلمت كيفية استخدام وظائف Azure مع خدمة Azure SignalR Service. اقرأ المزيد حول إنشاء تطبيقات بلا خادم في الوقت الحقيقي باستخدام روابط خدمة Azure SignalR لوظائف Azure:

تطبيقات في الوقت الحقيقي باستخدام Azure SignalR Service وAzure Functions

هل تواجه مشكلات؟ أبلغنا بها.