مشاركة عبر

استيراد واجهة برمجة تطبيقات WebSocket

  • مقالة

ينطبق على: المطور | أساسي | الإصدار 2 الأساسي | قياسي | الإصدار 2 القياسي | بريميوم

باستخدام حل API Management WebSocket API، يمكن لناشري واجهة برمجة التطبيقات إضافة واجهة برمجة تطبيقات WebSocket بسرعة في APIM عبر مدخل Microsoft Azure وAzure CLI وAzure PowerShell وأدوات Azure الأخرى.

يمكنك تأمين واجهات برمجة تطبيقات WebSocket عن طريق تطبيق نهج التحكم في الوصول الحالية، مثل التحقق من صحة JWT. يمكنك أيضًا اختبار واجهات برمجة التطبيقات WebSocket باستخدام وحدات التحكم في اختبار API في كل من مدخل Azure ومدخل المطور. بناءً على إمكانات المراقبة الحالية، توفر APIM قياسات وسجلات لمراقبة واجهات برمجة تطبيقات WebSocket، واستكشاف الأخطاء وإصلاحها.

في هذه المقالة، سوف تتمكن من:

  • فهم تدفق المرور عبر Websocket.
  • إضافة API WebSocket إلى مثيل APIM الخاص بك.
  • اختبار API WebSocket الخاص بك.
  • عرض القياسات والسجلات لـ API WebSocket الخاص بك.
  • تعرف على قيود واجهة برمجة تطبيقات WebSocket.

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

بطاقة مرور WebSocket

تدعم APIM بطاقة مرور WebSocket.

توضيح مرئي لتدفق عبور WebSocket

أثناء مرور WebSocket، يقوم تطبيق العميل بإنشاء اتصال WebSocket مع بوابة APIM، والتي تقوم بعد ذلك بإنشاء اتصال مع خدمات الخلفية المقابلة. APIM ثم وكلاء WebSocket رسائل الخادم- العميل.

  1. يرسل تطبيق العميل طلب تأكيد اتصال WebSocket إلى بوابة APIM، ويستدعي عملية onHandshake.
  2. يرسل بوابة APIM طلب تأكيد اتصال WebSocket إلى الخدمة الخلفية المطابقة.
  3. ترقّي الخدمة الخلفية اتصال WebSocket.
  4. تقوم بوابة APIM بترقية الاتصال المقابل بـ WebSocket.
  5. بمجرد إنشاء زوج الاتصال، سيقوم APIM بوساطة الرسائل ذهابًا وإيابًا بين تطبيق العميل والخدمة الخلفية.
  6. يرسل تطبيق العميل رسالة إلى بوابة APIM.
  7. تقوم بوابة APIM بإعادة توجيه الرسالة إلى الخدمة الخلفية.
  8. ترسل الخدمة الخلفية رسالة إلى بوابة APIM.
  9. تقوم بوابة APIM بإعادة توجيه الرسالة إلى تطبيق العميل.
  10. عند قطع اتصال أي من الجانبين، تنهي APIM الاتصال المطابق.

إشعار

تتكون اتصالات جانب العميل والجهة الخلفية من تعيين واحد إلى واحد.

عملية onHandshake

وفقا لبروتوكول WebSocket، عندما يحاول تطبيق عميل إنشاء اتصال WebSocket مع خدمة خلفية، فإنه سيرسل أولا طلب تأكيد اتصال فتح. يحتوي كل API WebSocket في APIM على عملية onHandshake. onHandshake هي عملية نظام ثابت وغير قابل للإزالة تم إنشاؤها تلقائيًا. تمكّن عملية onHandshake ناشري واجهة برمجة التطبيقات من اعتراض طلبات تأكيد الاتصال هذه، وتطبيق سياسات APIM عليهم.

مثال على شاشة onHandshake

إضافة واجهة برمجة تطبيقات WebSocket

    1. في مدخل Azure، انتقل إلى مثيل API Management الخاص بك.

  2. في القائمة اليسرى، حدد APIs>+ Add API.

  3. ضمن تعريف واجهة برمجة تطبيقات جديدة، حدد WebSocket.

  4. في مربع الحوار، حدد كامل وأكمل حقول النموذج المطلوبة.

    الحقل الوصف
    ‏‫اسم العرض‬ الاسم الذي سيتم عرض WebSocket API به.
    الاسم الاسم الخام لواجهة برمجة تطبيقات WebSocket. يتم ملؤه تلقائيًا أثناء كتابة الاسم المعروض.
    WebSocket URL عنوان URL الأساسي مع اسم websocket الخاص بك. على سبيل المثال: ws://example.com/your-socket-name
    مخطط URL قبول الإعداد الافتراضي
    لاحقة عنوان URL لواجهة برمجة التطبيقات أضف لاحقة URL لتحديد واجهة برمجة التطبيقات المحددة هذه في مثيل APIM. يجب أن تكون فريدة في مثيل APIM هذا.
    المنتجات إقران واجهة برمجة تطبيقات WebSocket مع منتج لنشره.
    البوابات‬ إقران API WebSocket مع البوابات الموجودة.

  5. انقر فوق Create.

اختبار واجهة برمجة تطبيقات WebSocket

  1. انتقل إلى واجهة برمجة تطبيقات WebSocket.

  2. ضمن WEBSocket API، حدد عملية على onHandshake.

  3. حدد علامة تبويب اختبار للوصول إلى وحدة الاختبار.

  4. اختياريًا، قم بتوفير معلمات سلسلة الاستعلام المطلوبة؛ لتأكيد اتصال WebSocket.

    مثال على اختبار واجهة برمجة التطبيقات

  5. انقر على اتصال.

  6. عرض حالة الاتصال في الإخراج.

  7. أدخل قيمة في Payload.

  8. انقر فوق إرسال.

  9. عرض الرسائل المستلمة في الإخراج.

  10. كرر الخطوات السابقة لاختبار البيانات الأساسية المختلفة.

  11. عند اكتمال الاختبار، حدد قطع الاتصال.

عرض القياسات والسجلات

استخدم ميزات إدارة واجهة برمجة التطبيقات القياسية وAzure Monitor لمراقبة واجهات برمجة تطبيقات WebSocket:

  • عرض قياسات API في Azure Monitor
  • تمكين إعدادات التشخيص بشكل اختياري لتجميع سجلات بوابة APIM وعرضها، والتي تتضمن عمليات WEBSocket API

على سبيل المثال، تُظهر لقطة الشاشة التالية استجابات WebSocket API الأخيرة مع التعليمة البرمجية من 101 جدول ApiManagementGatewayLogs. تشير هذه النتائج إلى التبديل الناجح للطلبات من بروتوكول تحكم الإرسال إلى بروتوكول WebSocket.

سجلات الاستعلام لطلبات WebSocket API

القيود

فيما يلي القيود الحالية لدعم WebSocket في APIM:

  • واجهات برمجة التطبيقات WebSocket غير مدعمة حتى الآن في مستوى الاستهلاك.
  • تدعم واجهات برمجة تطبيقات WebSocket أنواع المخزن المؤقت الصالحة التالية للرسائل: Close و BinaryFragment و BinaryMessage و UTF8Fragment و UTF8Message.
  • حاليًا، لا تدعم سياسة الرأس المعين تغيير بعض الرؤوس المعروفة، بما في ذلك Host العناوين في طلبات onHandshake.
  • في أثناء تأكيد اتصال TLS مع خلفية WebSocket، يتحقق APIM من أن شهادة الخادم موثوق بها وأن اسم موضوعها يطابق اسم المضيف. باستخدام واجهات برمجة تطبيقات HTTP، يتحقق APIM من أن الشهادة موثوق بها، ولكنها لا تتحقق من صحة اسم المضيف ومطابقة الموضوع.

للحصول على حدود اتصال WebSocket، راجع حدود إدارة واجهة برمجة التطبيقات.

سياسات غير مدعمة

النُهج التالية غير مدعومة، ولا يمكن تطبيقها على عملية onHandshake:

  • استجابة صورية
  • الحصول من ذاكرة التخزين المؤقت
  • تخزين إلى ذاكرة التخزين المؤقت
  • السماح باستدعاءات عبر المجال
  • CORS
  • JSONP
  • تعيين أسلوب الطلب
  • تعيين النص الأساسي
  • تحويل XML إلى JSON
  • تحويل JSON إلى XML
  • تحويل لغة التمييز قابلة الامتداد باستخدام تحويلات لغة صفحات الأنماط الموسعة
  • التحقق من صحة المحتوى
  • معلمات التحقق من الصحة
  • التحقق من صحة العناوين
  • التحقق من صحة تعليمة الحالة البرمجية

إشعار

إذا قمت بتطبيق النهج في نطاقات أعلى (أي عمومي أو منتج) وتم توريثها بواسطة واجهة برمجة تطبيقات WebSocket من خلال النهج، فسيتم تخطيها في وقت التشغيل.

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

تحويل واجهة برمجة تطبيقات منشورة وحمايتها