مشاركة عبر

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

  • مقالة

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

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

إشعار

حاليا، هذه الميزة غير متوفرة في مساحات العمل.

يمكن تأمين واجهات برمجة تطبيقات WebSocket من خلال تطبيق نهج التحكم في الوصول الخاصة بإدارة واجهة برمجة التطبيقات على عملية تأكيد الاتصال الأولية. يمكنك أيضًا اختبار واجهات برمجة التطبيقات 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 إلى البوابة، مع استدعاء عملية onHandshake
  2. تطبق بوابة APIM النهج المكونة وترسل طلبات تأكيد اتصال WebSocket إلى خدمة الواجهة الخلفية المقابلة.
  3. ترقّي الخدمة الخلفية اتصال WebSocket.
  4. تقوم البوابة بترقية الاتصال المقابل إلى WebSocket.
  5. بعد تأسيس زوج الاتصال، يقوم وسطاء API Management بالرسائل ذهابا وإيابا بين تطبيق العميل وخدمة الواجهة الخلفية.
  6. يرسل تطبيق العميل رسالة إلى البوابة.
  7. تعيد البوابة توجيه الرسالة إلى خدمة الواجهة الخلفية.
  8. ترسل خدمة الواجهة الخلفية رسالة إلى البوابة.
  9. تقوم البوابة بإعادة توجيه الرسالة إلى تطبيق العميل.
  10. عند قطع اتصال أي من الجانبين، تنهي API Management الاتصال المقابل.

إشعار

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

عملية onHandshake

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

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

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

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

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

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

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

    الحقل الوصف
    ‏‫اسم العرض‬ الاسم الذي يتم من خلاله عرض واجهة برمجة تطبيقات WebSocket.
    الاسم الاسم الخام لواجهة برمجة تطبيقات 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 من خلال النهج، يتم تخطيها في وقت التشغيل.

المحتوى ذو الصلة

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