Azure Relay Hybrid Connections protocol
Azure Relay هي واحدة من ركائز القدرات الرئيسية للنظام الأساسي ناقل خدمة Azure. تعد قدرة الاتصالات الهجينة الجديدة ل Relay تطورا آمنا ومفتوحا للبروتوكول يعتمد على HTTP و WebSockets. إنه يحل محل ميزة BizTalk Services السابقة ، التي تحمل نفس الاسم والتي تم بناؤها على أساس بروتوكول خاص. سيستمر دمج الاتصالات المختلطة في خدمات تطبيقات Azure في العمل كما هي.
تتيح الاتصالات المختلطة الاتصال ثنائي الاتجاه والاستجابة للطلبات والتدفق الثنائي وتدفق مخطط البيانات البسيط بين تطبيقين متصلين بالشبكة. يمكن أن يكون أي من الطرفين أو كليهما وراء NATs أو جدران الحماية.
توضح هذه المقالة التفاعلات من جانب العميل مع ترحيل الاتصالات المختلطة لتوصيل العملاء في أدوار المستمع والمرسل. كما يصف كيف يقبل المستمعون الاتصالات والطلبات الجديدة.
نموذج التفاعل
يربط ترحيل الاتصالات المختلطة بين طرفين من خلال توفير نقطة التقاء في سحابة Azure يمكن للأطراف اكتشافها والاتصال بها من منظور الشبكة الخاصة بهم. تسمى نقطة الالتقاء "الاتصال المختلط" في هذه الوثيقة وغيرها من الوثائق، وفي واجهات برمجة التطبيقات، وكذلك في مدخل Azure. يشار إلى نقطة نهاية خدمة الاتصالات المختلطة باسم "الخدمة" لبقية هذه المقالة.
تسمح الخدمة بترحيل اتصالات مقبس الويب وطلبات وردود HTTP (S).
يعتمد نموذج التفاعل على التسميات التي أنشأتها العديد من واجهات برمجة تطبيقات الشبكات الأخرى. هناك مستمع يشير أولا إلى استعداده للتعامل مع الاتصالات الواردة ، ثم يقبلها عند وصولها. على الجانب الآخر ، يتصل العميل بالمستمع ، متوقعا أن يتم قبول هذا الاتصال لإنشاء مسار اتصال ثنائي الاتجاه. "الاتصال" و "استمع" و "قبول" هي نفس المصطلحات التي تجدها في معظم واجهات برمجة تطبيقات المقبس.
أي نموذج اتصال منقول لديه أي من الطرفين إجراء اتصالات صادرة نحو نقطة نهاية الخدمة. هذا يجعل "المستمع" أيضا "عميلا" في الاستخدام العامي ، وقد يتسبب أيضا في زيادة الأحمال الزائدة للمصطلحات. المصطلحات الدقيقة المستخدمة لذلك للاتصالات الهجينة هي كما يلي:
تسمى البرامج الموجودة على جانبي الاتصال "العملاء" ، نظرا لأنهم عملاء للخدمة. العميل الذي ينتظر الاتصالات ويقبلها هو "المستمع" ، أو يقال إنه في "دور المستمع". يسمى العميل الذي يبدأ اتصالا جديدا تجاه مستمع عبر الخدمة "المرسل" ، أو يكون في "دور المرسل".
تفاعلات المستمعين
المستمع لديه خمسة تفاعلات مع الخدمة. يتم وصف كافة تفاصيل الأسلاك لاحقا في هذه المقالة في قسم المراجع.
يتم استلام رسائل الاستماع والقبول والطلب من الخدمة. يتم إرسال عمليتي التجديد و Ping بواسطة المستمع.
استمع إلى الرسالة
للإشارة إلى الاستعداد للخدمة التي يكون المستمع مستعدا لقبول الاتصالات ، فإنه ينشئ اتصال WebSocket صادر. تحمل مصافحة الاتصال اسم اتصال مختلط تم تكوينه على مساحة اسم Relay ، ورمز أمان يمنح "الاستماع" مباشرة على هذا الاسم.
عندما يتم قبول WebSocket من قبل الخدمة ، يكتمل التسجيل ويتم الاحتفاظ ب WebSocket الذي تم إنشاؤه على قيد الحياة ك "قناة التحكم" لتمكين جميع التفاعلات اللاحقة. تتيح الخدمة ما يصل إلى 25 مستمعا متزامنا للاتصال الهجين الواحد. سيتم تحديد حصة AppHooks.
بالنسبة للاتصالات المختلطة ، إذا كان هناك مستمعان نشطان أو أكثر ، فإن الاتصالات الواردة متوازنة عبرها بترتيب عشوائي ؛ تتم محاولة التوزيع العادل بأفضل جهد.
قبول الرسالة
عندما يفتح المرسل اتصالا جديدا على الخدمة، تختار الخدمة أحد المستمعين النشطين على الاتصال المختلط وتخطره. يتم إرسال هذا الإعلام إلى المستمع عبر قناة التحكم المفتوحة كرسالة JSON. تحتوي الرسالة على عنوان URL لنقطة نهاية WebSocket التي يجب على المستمع الاتصال بها لقبول الاتصال.
يمكن ويجب استخدام عنوان URL مباشرة من قبل المستمع دون أي عمل إضافي. المعلومات المشفرة صالحة فقط لفترة قصيرة من الزمن ، بشكل أساسي طالما أن المرسل على استعداد لانتظار إنشاء الاتصال من البداية إلى النهاية. الحد الأقصى للافتراض هو 30 ثانية. لا يمكن استخدام عنوان URL إلا لمحاولة اتصال واحدة ناجحة. بمجرد إنشاء اتصال WebSocket بعنوان URL للالتقاء ، يتم ترحيل جميع الأنشطة الإضافية على WebSocket هذا من وإلى المرسل. يحدث هذا السلوك دون أي تدخل أو تفسير من قبل الخدمة.
طلب رسالة
بالإضافة إلى اتصالات WebSocket ، يمكن للمستمع أيضا تلقي إطارات طلب HTTP من مرسل ، إذا تم تمكين هذه الإمكانية بشكل صريح على الاتصال المختلط.
يجب على المستمعين الذين يربطون بالاتصالات المختلطة مع دعم HTTP التعامل مع request الإيماءة. قد يتم حظر المستمع الذي لا يتعامل وبالتالي request يسبب أخطاء المهلة المتكررة أثناء الاتصال بواسطة الخدمة في المستقبل.
تتم ترجمة البيانات الوصفية لرأس إطار HTTP إلى JSON لمعالجة أبسط بواسطة إطار عمل المستمع ، أيضا لأن مكتبات تحليل رأس HTTP أكثر ندرة من محللي JSON. لا تتم إعادة توجيه بيانات تعريف HTTP ذات الصلة فقط بالعلاقة بين المرسل وبوابة ترحيل HTTP، بما في ذلك معلومات التفويض. يتم نقل هيئات طلب HTTP بشفافية كإطارات WebSocket ثنائية.
يمكن للمستمع الاستجابة لطلبات HTTP باستخدام إيماءة استجابة مكافئة.
يستخدم تدفق الطلب/الاستجابة قناة التحكم بشكل افتراضي، ولكن يمكن "ترقيته" إلى WebSocket لقاء مميز كلما لزم الأمر. تعمل اتصالات WebSocket المتميزة على تحسين الإنتاجية لكل محادثة عميل ، ولكنها تثقل كاهل المستمع بمزيد من الاتصالات التي تحتاج إلى التعامل معها ، والتي قد لا تكون قادرة على العملاء ذوي الوزن الخفيف.
على قناة التحكم ، تقتصر هيئات الطلب والاستجابة على 64 كيلو بايت على الأكثر في الحجم. تقتصر البيانات الوصفية لرأس HTTP على ما مجموعه 32 كيلوبايت. إذا تجاوز الطلب أو الاستجابة هذا الحد، فيجب على المستمع الترقية إلى WebSocket التقاء باستخدام إيماءة مكافئة للتعامل مع القبول.
بالنسبة للطلبات، تقرر الخدمة ما إذا كانت ستوجه الطلبات عبر قناة التحكم أم لا. ويشمل ذلك، على سبيل المثال لا الحصر، الحالات التي يتجاوز فيها الطلب 64 كيلوبايت (الرؤوس بالإضافة إلى النص) مباشرة، أو إذا تم إرسال الطلب باستخدام ترميز النقل "المقطع" وكان لدى الخدمة سبب لتوقع أن يتجاوز الطلب 64 كيلوبايت أو إذا كانت قراءة الطلب ليست فورية. إذا اختارت الخدمة تسليم الطلب عبر اللقاء ، فإنها تمرر فقط عنوان اللقاء إلى المستمع. ثم يجب على المستمع إنشاء WebSocket الالتقاء وتقوم الخدمة على الفور بتسليم الطلب الكامل بما في ذلك الهيئات عبر WebSocket اللقاء. يجب أن تستخدم الاستجابة أيضا WebSocket اللقاء.
بالنسبة للطلبات التي تصل عبر قناة التحكم، يقرر المستمع ما إذا كان سيستجيب عبر قناة التحكم أو عبر اللقاء. يجب أن تتضمن الخدمة عنوان الالتقاء مع كل طلب يتم توجيهه عبر قناة التحكم. هذا العنوان صالح فقط للترقية من الطلب الحالي.
إذا اختار المستمع الترقية ، فإنه يتصل ويسلم الاستجابة على الفور عبر مقبس الالتقاء المحدد.
بمجرد إنشاء WebSocket اللقاء ، يجب على المستمع الاحتفاظ به لمزيد من التعامل مع الطلبات والردود من نفس العميل. ستحتفظ الخدمة ب WebSocket طالما استمر اتصال مقبس HTTPS مع المرسل وستوجه جميع الطلبات اللاحقة من هذا المرسل عبر WebSocket الذي تمت صيانته. إذا اختار المستمع إسقاط WebSocket اللقاء من جانبه ، فستقوم الخدمة أيضا بإسقاط الاتصال بالمرسل ، بغض النظر عما إذا كان الطلب اللاحق قد يكون قيد التقدم بالفعل.
تجديد التشغيل
قد تنتهي صلاحية رمز الأمان المميز الذي يجب استخدامه لتسجيل المستمع والحفاظ على قناة التحكم أثناء نشاط المستمع. لا يؤثر انتهاء صلاحية الرمز المميز على الاتصالات المستمرة ، ولكنه يتسبب في إسقاط قناة التحكم بواسطة الخدمة في لحظة انتهاء الصلاحية أو بعدها مباشرة. عملية "التجديد" هي رسالة JSON يمكن للمستمع إرسالها لاستبدال الرمز المميز المقترن بقناة التحكم، بحيث يمكن الحفاظ على قناة التحكم لفترات طويلة.
عملية بينغ
إذا ظلت قناة التحكم خاملة لفترة طويلة، فقد يقوم الوسطاء في الطريق، مثل موازنات التحميل أو NATs بإسقاط اتصال TCP. تتجنب عملية "ping" ذلك عن طريق إرسال كمية صغيرة من البيانات على القناة التي تذكر الجميع على مسار الشبكة بأن الاتصال من المفترض أن يكون على قيد الحياة ، كما أنه بمثابة اختبار "مباشر" للمستمع. في حالة فشل ping ، يجب اعتبار قناة التحكم غير قابلة للاستخدام ويجب على المستمع إعادة الاتصال.
تفاعل المرسل
لدى المرسل تفاعلان مع الخدمة: فهو يربط مقبس ويب أو يرسل طلبات عبر HTTPS. لا يمكن إرسال الطلبات عبر مقبس ويب من دور المرسل.
عملية الاتصال
تفتح عملية "الاتصال" WebSocket على الخدمة، مما يوفر اسم الاتصال المختلط و(اختياريا، ولكن مطلوبا بشكل افتراضي) رمز أمان يمنح إذن "إرسال" في سلسلة الاستعلام. ثم تتفاعل الخدمة مع المستمع بالطريقة الموضحة سابقا ، ويقوم المستمع بإنشاء اتصال التقاء يتم ضمه إلى WebSocket هذا. بعد قبول WebSocket ، تكون جميع التفاعلات الإضافية على WebSocket مع مستمع متصل.
طلب عملية
بالنسبة إلى الاتصالات المختلطة التي تم تمكين الميزة لها، يمكن للمرسل إرسال طلبات HTTP غير مقيدة إلى حد كبير إلى المستمعين.
باستثناء الرمز المميز للوصول إلى الترحيل الذي يتم تضمينه إما في سلسلة الاستعلام أو في رأس HTTP للطلب ، فإن الترحيل شفاف تماما لجميع عمليات HTTP على عنوان الترحيل وجميع اللواحق لمسار عنوان الترحيل ، مما يترك المستمع يتحكم بالكامل في التفويض من طرف إلى طرف وحتى ميزات ملحق HTTP مثل CORS.
يتم تشغيل تفويض المرسل باستخدام نقطة نهاية الترحيل بشكل افتراضي، ولكنه اختياري. يمكن لمالك الاتصال المختلط اختيار السماح للمرسلين المجهولين. ستقوم الخدمة باعتراض وفحص وتجريد معلومات التفويض على النحو التالي:
- إذا كانت سلسلة الاستعلام تحتوي على
sb-hc-tokenتعبير، دائما تجريد التعبير من سلسلة الاستعلام. سيتم تقييمه إذا تم تشغيل تفويض الترحيل. - إذا كانت رؤوس الطلبات تحتوي على
ServiceBusAuthorizationرأس، دائما تجريد تعبير الرأس من مجموعة الرؤوس. سيتم تقييمه إذا تم تشغيل تفويض الترحيل. - فقط في حالة تشغيل تفويض الترحيل، وإذا كانت رؤوس الطلبات تحتوي على
Authorizationرأس، ولم يكن أي من التعبيرات السابقة موجودا، تقييم الرأس وتجريده. خلاف ذلك ،Authorizationيتم تمرير دائما على ما هو عليه.
إذا لم يكن هناك مستمع نشط ، فستعرض الخدمة رمز خطأ 502 "Bad Gateway". إذا لم تظهر الخدمة للتعامل مع الطلب، فستعرض الخدمة "مهلة البوابة" 504 بعد 60 ثانية.
ملخص التفاعل
نتيجة نموذج التفاعل هذا هو أن العميل المرسل يخرج من المصافحة باستخدام WebSocket "نظيف" ، متصل بمستمع ولا يحتاج إلى مزيد من الديباجة أو الإعداد. يمكن هذا النموذج عمليا أي تطبيق عميل WebSocket موجود من الاستفادة بسهولة من خدمة الاتصالات المختلطة عن طريق توفير عنوان URL تم إنشاؤه بشكل صحيح في طبقة عميل WebSocket الخاصة بهم.
اتصال الالتقاء WebSocket الذي يحصل عليه المستمع من خلال تفاعل القبول نظيف أيضا ويمكن تسليمه إلى أي تنفيذ خادم WebSocket موجود مع بعض الحد الأدنى من التجريد الإضافي الذي يميز بين عمليات "قبول" على مستمعي الشبكة المحلية لإطارهم وعمليات "قبول" الاتصالات الهجينة عن بعد.
يمنح نموذج طلب/استجابة HTTP المرسل مساحة سطح بروتوكول HTTP غير مقيدة إلى حد كبير مع طبقة تخويل اختيارية. يحصل المستمع على قسم رأس طلب HTTP معد يمكن تحويله مرة أخرى إلى طلب HTTP في المراحل النهائية أو التعامل معه كما هو ، مع إطارات ثنائية تحمل أجسام HTTP. تستخدم الردود نفس التنسيق. يمكن التعامل مع التفاعلات التي تحتوي على أقل من 64 كيلوبايت من نص الطلب والاستجابة عبر مقبس ويب واحد تتم مشاركته لجميع المرسلين. يمكن التعامل مع الطلبات والردود الأكبر باستخدام نموذج اللقاء.
مرجع البروتوكول
يصف هذا القسم تفاصيل تفاعلات البروتوكول الموضحة سابقا.
يتم إجراء جميع اتصالات WebSocket على المنفذ 443 كترقية من HTTPS 1.1 ، والتي يتم استخلاصها عادة بواسطة بعض إطار WebSocket أو واجهة برمجة التطبيقات. الوصف هنا هو الحفاظ على التنفيذ محايدا ، دون اقتراح إطار محدد.
بروتوكول المستمع
يتكون بروتوكول المستمع من إيماءتين للاتصال وثلاث عمليات رسالة.
اتصال قناة تحكم المستمع
يتم فتح قناة التحكم بإنشاء اتصال WebSocket إلى:
wss://{namespace-address}/$hc/{path}?sb-hc-action=...[&sb-hc-id=...]&sb-hc-token=...
namespace-address هو اسم المجال المؤهل بالكامل لمساحة اسم Azure Relay التي تستضيف الاتصال المختلط، وعادة ما يكون من النموذج {myname}.servicebus.windows.net.
خيارات معلمة سلسلة الاستعلام هي كما يلي.
| المعلمة | مطلوب | الوصف |
|---|---|---|
sb-hc-action |
نعم | بالنسبة لدور المستمع، يجب أن تكون المعلمة sb-hc-action=listen |
{path} |
نعم | مسار مساحة الاسم المشفرة بواسطة عنوان URL للاتصال المختلط الذي تم تكوينه مسبقا لتسجيل هذا المستمع عليه. يتم إلحاق هذا التعبير بجزء المسار الثابت $hc/ . |
sb-hc-token |
نعم* | يجب على المستمع توفير رمز وصول مشترك صالح ومشفر بواسطة عنوان URL لمساحة الاسم أو الاتصال المختلط الذي يمنح حق الاستماع . |
sb-hc-id |
لا | يتيح هذا المعرف الاختياري الذي يوفره العميل إمكانية التتبع التشخيصي من طرف إلى طرف. |
إذا فشل اتصال WebSocket بسبب عدم تسجيل مسار الاتصال المختلط أو رمز مميز غير صالح أو مفقود أو خطأ آخر، يتم توفير ملاحظات الخطأ باستخدام نموذج ملاحظات حالة HTTP 1.1 العادي. يحتوي وصف الحالة على معرف تعقب الأخطاء الذي يمكن إبلاغه إلى موظفي دعم Azure:
| رمز | خطأ | الوصف |
|---|---|---|
| 404 | غير موجود | مسار الاتصال المختلط غير صالح أو عنوان URL الأساسي مشوه. |
| 401 | غير مصرح به | رمز الأمان مفقود أو مشوه أو غير صالح. |
| 403 | محظور | رمز الأمان غير صالح لهذا المسار لهذا الإجراء. |
| 500 | خطأ داخلي | حدث خطأ ما في الخدمة. |
إذا تم إيقاف تشغيل اتصال WebSocket عمدا بواسطة الخدمة بعد إعداده في البداية، إبلاغ سبب القيام بذلك باستخدام رمز خطأ بروتوكول WebSocket مناسب إلى جانب رسالة خطأ وصفية تتضمن أيضا معرف تعقب. لن تقوم الخدمة بإيقاف تشغيل قناة التحكم دون مواجهة حالة خطأ. يتم التحكم في أي إيقاف تشغيل نظيف من قبل العميل.
| حالة WS | الوصف |
|---|---|
| 1001 | تم حذف مسار الاتصال المختلط أو تعطيله. |
| 1008 | انتهت صلاحية رمز الأمان المميز ، وبالتالي يتم انتهاك سياسة التفويض. |
| 1011 | حدث خطأ ما في الخدمة. |
قبول المصافحة
يتم إرسال إشعار "قبول" بواسطة الخدمة إلى المستمع عبر قناة التحكم التي تم إنشاؤها مسبقا كرسالة JSON في إطار نص WebSocket. لا يوجد رد على هذه الرسالة.
تحتوي الرسالة على كائن JSON باسم "قبول" ، والذي يحدد الخصائص التالية في هذا الوقت:
- العنوان - سلسلة عنوان URL التي سيتم استخدامها لإنشاء WebSocket إلى الخدمة لقبول اتصال وارد.
- معرف - المعرف الفريد لهذا الاتصال. إذا تم توفير المعرف من قبل عميل المرسل ، فستكون القيمة التي قدمها المرسل ، وإلا فهي قيمة تم إنشاؤها بواسطة النظام.
- connectHeaders - جميع رؤوس HTTP التي تم توفيرها إلى نقطة نهاية الترحيل بواسطة المرسل ، والتي تتضمن أيضا بروتوكولات Sec-WebSocket ورؤوس Sec-WebSocket-Extensions.
{
"accept" : {
"address" : "wss://dc-node.servicebus.windows.net:443/$hc/{path}?..."
"id" : "4cb542c3-047a-4d40-a19f-bdc66441e736",
"connectHeaders" : {
"Host" : "...",
"Sec-WebSocket-Protocol" : "...",
"Sec-WebSocket-Extensions" : "..."
}
}
}
يتم استخدام عنوان URL للعنوان المقدم في رسالة JSON من قبل المستمع لإنشاء WebSocket لقبول أو رفض مقبس المرسل.
قبول المقبس
للقبول ، يقوم المستمع بإنشاء اتصال WebSocket بالعنوان المقدم.
إذا كانت الرسالة "قبول" تحمل رأسا Sec-WebSocket-Protocol ، فمن المتوقع أن يقبل المستمع WebSocket فقط إذا كان يدعم هذا البروتوكول. بالإضافة إلى ذلك، فإنه يعين الرأس كما تم تأسيس WebSocket.
وينطبق الشيء نفسه على Sec-WebSocket-Extensions الرأس. إذا كان إطار العمل يدعم ملحقا ، فيجب عليه تعيين الرأس إلى الرد من جانب الخادم للمصافحة المطلوبة Sec-WebSocket-Extensions للإضافة.
يجب استخدام عنوان URL كما هو لإنشاء مقبس القبول، ولكنه يحتوي على المعلمات التالية:
| المعلمة | مطلوب | الوصف |
|---|---|---|
sb-hc-action |
نعم | لقبول مقبس ، يجب أن تكون المعلمة sb-hc-action=accept |
{path} |
نعم | (انظر الفقرة التالية) |
sb-hc-id |
لا | انظر الوصف السابق للمعرف. |
{path} هو مسار مساحة الاسم المشفرة بواسطة عنوان URL للاتصال المختلط الذي تم تكوينه مسبقا لتسجيل هذا المستمع عليه. يتم إلحاق هذا التعبير بجزء المسار الثابت $hc/ .
path يمكن توسيع التعبير باستخدام لاحقة وتعبير سلسلة استعلام يتبع الاسم المسجل بعد شرطة مائلة للأمام منفصلة.
تمكن هذه المعلمة عميل المرسل من تمرير وسيطات الإرسال إلى المستمع المقبول عندما يتعذر تضمين رؤوس HTTP. التوقع هو أن إطار عمل المستمع يحلل جزء المسار الثابت والاسم المسجل من المسار ويجعل الباقي ، ربما بدون أي وسيطات سلسلة استعلام مسبوقة ب sb-، متاحا للتطبيق لتحديد ما إذا كان سيتم قبول الاتصال.
لمزيد من المعلومات، راجع قسم "بروتوكول المرسل" التالي.
إذا كان هناك خطأ ، يمكن للخدمة الرد على النحو التالي:
| رمز | خطأ | الوصف |
|---|---|---|
| 403 | محظور | عنوان URL غير صالح. |
| 500 | خطأ داخلي | حدث خطأ ما في الخدمة |
بعد تأسيس الاتصال، يقوم الخادم بإيقاف تشغيل WebSocket عند إيقاف تشغيل WebSocket المرسل، أو بالحالة التالية:
| حالة WS | الوصف |
|---|---|
| 1001 | يقوم العميل المرسل بإيقاف تشغيل الاتصال. |
| 1001 | تم حذف مسار الاتصال المختلط أو تعطيله. |
| 1008 | انتهت صلاحية رمز الأمان المميز ، وبالتالي يتم انتهاك سياسة التفويض. |
| 1011 | حدث خطأ ما في الخدمة. |
رفض المقبس
يتطلب رفض المقبس بعد فحص الرسالة مصافحة مماثلة بحيث يمكن أن يتدفق رمز الحالة ووصف الحالة اللذين ينقلان accept سبب الرفض إلى المرسل.
خيار تصميم البروتوكول هنا هو استخدام مصافحة WebSocket (التي تم تصميمها لتنتهي في حالة خطأ محددة) بحيث يمكن لتطبيقات عميل المستمع الاستمرار في الاعتماد على عميل WebSocket ولا تحتاج إلى استخدام عميل HTTP إضافي عاري.
لرفض المقبس، يأخذ العميل عنوان URI من accept الرسالة ويقوم بإلحاق معلمتين لسلسلة الاستعلام به، كما يلي:
| بارام | مطلوب | الوصف |
|---|---|---|
| sb-hc-statusCode | نعم | رمز حالة HTTP رقمي. |
| sb-hc-statusالوصف | نعم | سبب قابل للقراءة البشرية للرفض. |
ثم يتم استخدام URI الناتج لإنشاء اتصال WebSocket.
عند الانتهاء بشكل صحيح ، تفشل هذه المصافحة عمدا برمز خطأ HTTP 410 ، حيث لم يتم إنشاء WebSocket. إذا حدث خطأ ما، تصف الرموز التالية الخطأ:
| رمز | خطأ | الوصف |
|---|---|---|
| 403 | محظور | عنوان URL غير صالح. |
| 500 | خطأ داخلي | حدث خطأ ما في الخدمة. |
طلب رسالة
request يتم إرسال الرسالة بواسطة الخدمة إلى المستمع عبر قناة التحكم. يتم إرسال نفس الرسالة أيضا عبر الالتقاء WebSocket بمجرد إنشائها.
يتكون request من جزأين: رأس وإطار (إطارات) جسم ثنائي.
إذا لم يكن هناك جسم ، يتم حذف إطارات الجسم. تشير الخاصية المنطقية body إلى ما إذا كان النص الأساسي موجودا في رسالة الطلب أم لا.
بالنسبة للطلب الذي يحتوي على نص طلب ، قد يبدو الهيكل كما يلي:
----- Web Socket text frame ----
{
"request" :
{
"body" : true,
...
}
}
----- Web Socket binary frame ----
FEFEFEFEFEFEFEFEFEFEF...
----- Web Socket binary frame ----
FEFEFEFEFEFEFEFEFEFEF...
----- Web Socket binary frame -FIN
FEFEFEFEFEFEFEFEFEFEF...
----------------------------------
يجب على المستمع التعامل مع تلقي نص الطلب المقسم عبر إطارات ثنائية متعددة (راجع أجزاء WebSocket). ينتهي الطلب عند استلام إطار ثنائي مع مجموعة علامات FIN.
بالنسبة لطلب بدون نص أساسي، يوجد إطار نص واحد فقط.
----- Web Socket text frame ----
{
"request" :
{
"body" : false,
...
}
}
----------------------------------
محتوى request JSON هو كما يلي:
العنوان - سلسلة URI. إنه عنوان الالتقاء الذي يجب استخدامه لهذا الطلب. إذا كان الطلب الوارد أكبر من 64 كيلو بايت، يتم ترك ما تبقى من هذه الرسالة فارغا، ويجب على العميل بدء مصافحة لقاء تعادل
acceptالعملية الموضحة أدناه. ستقوم الخدمة بعد ذلك بوضع الكاملrequestعلى مقبس الويب الذي تم إنشاؤه. إذا كان من المتوقع أن تتجاوز الاستجابة 64 كيلو بايت، فيجب على المستمع أيضا بدء مصافحة اللقاء، ثم نقل الاستجابة عبر مقبس الويب الذي تم إنشاؤه.معرف – سلسلة. المعرف الفريد لهذا الطلب.
requestHeaders - يحتوي هذا الكائن على جميع رؤوس HTTP التي تم توفيرها إلى نقطة النهاية من قبل المرسل ، باستثناء معلومات التفويض كما هو موضح أعلاه ، والرؤوس التي ترتبط ارتباطا وثيقا بالاتصال بالبوابة. وعلى وجه التحديد، يتم تجريد جميع الرؤوس المحددة أو المحجوزة في RFC7230، باستثناء
Via، ولا يتم إعادة توجيهها:Connection(RFC7230، القسم 1.6)Content-Length(RFC7230، القسم 3.3.2)Host(RFC7230، القسم 4.5)TE(RFC7230، القسم 4.3)Trailer(RFC7230، القسم 4.4)Transfer-Encoding(RFC7230، القسم 3.3.1)Upgrade(RFC7230، القسم 7.6)Close(RFC7230، القسم 8.1)
requestTarget – سلسلة. تحتوي هذه الخاصية على " هدف الطلب" (RFC7230، القسم 5.3) من الطلب. يتضمن جزء سلسلة الاستعلام ، والذي يتم تجريده من جميع
sb-hc-المعلمات البادئة.الطريقة - سلسلة. هذه هي طريقة الطلب ، لكل RFC7231 ، القسم 4.
CONNECTيجب عدم استخدام الطريقة.الجسم – منطقي. يشير إلى ما إذا كان واحد أو أكثر من إطارات الجسم الثنائية يتبع.
{
"request" : {
"address" : "wss://dc-node.servicebus.windows.net:443/$hc/{path}?...",
"id" : "42c34cb5-7a04-4d40-a19f-bdc66441e736",
"requestTarget" : "/abc/def?myarg=value&otherarg=...",
"method" : "GET",
"requestHeaders" : {
"Host" : "...",
"Content-Type" : "...",
"User-Agent" : "..."
},
"body" : true
}
}
الاستجابة للطلبات
يجب أن يستجيب المتلقي. قد يؤدي الفشل المتكرر في الاستجابة للطلبات مع الحفاظ على الاتصال إلى حظر المستمع.
قد يتم إرسال الردود بأي ترتيب ، ولكن يجب الرد على كل طلب في غضون 60 ثانية أو سيتم الإبلاغ عن فشل التسليم. يتم احتساب الموعد النهائي البالغ 60 ثانية حتى response يتم استلام الإطار من قبل الخدمة. لا يمكن أن تصبح الاستجابة المستمرة ذات الإطارات الثنائية المتعددة خاملة لأكثر من 60 ثانية أو يتم إنهاؤها.
إذا تم استلام الطلب عبر قناة التحكم، فيجب إما إرسال الرد على قناة التحكم التي تم استلام الطلب منها أو يجب إرساله عبر قناة التقاء.
الاستجابة عبارة عن كائن JSON يسمى "الاستجابة". قواعد التعامل مع محتوى النص الأساسي تشبه تماما request الرسالة وتستند body إلى الخاصية.
- requestId – سلسلة. مطلوب.
idقيمة الخاصية للرسالة التيrequestيتم الرد عليها. - statusCode – الرقم. مطلوب. رمز حالة HTTP رقمي يشير إلى نتيجة الإشعار. يسمح بجميع رموز الحالة الخاصة ب RFC7231 ، القسم 6 ، باستثناء 502 "Bad Gateway" و 504 "Gateway Timeout".
- statusDescription - سلسلة. اختياري. عبارة سبب رمز حالة HTTP لكل RFC7230 ، القسم 3.1.2
- responseHeaders - رؤوس HTTP ليتم تعيينها في رد HTTP خارجي.
كما هو الحال مع
request، يجب عدم استخدام الرؤوس المحددة RFC7230. - الجسم – منطقي. يشير إلى ما إذا كان إطار (إطارات) الجسم الثنائي يتبع (إطارات) الجسم الثنائي.
----- Web Socket text frame ----
{
"response" : {
"requestId" : "42c34cb5-7a04-4d40-a19f-bdc66441e736",
"statusCode" : "200",
"responseHeaders" : {
"Content-Type" : "application/json",
"Content-Encoding" : "gzip"
}
"body" : true
}
}
----- Web Socket binary frame -FIN
{ "hey" : "mydata" }
----------------------------------
الرد عبر اللقاء
بالنسبة للاستجابات التي تتجاوز 64 كيلو بايت، يجب تسليم الاستجابة عبر مقبس التقاء. أيضا ، إذا تجاوز الطلب 64 كيلو بايت ، وكان request يحتوي فقط على حقل العنوان ، فيجب إنشاء مقبس الالتقاء للحصول على request. بمجرد إنشاء مقبس الالتقاء ، يجب تسليم الردود على العميل المعني والطلبات اللاحقة من هذا العميل المعني عبر مقبس الالتقاء أثناء استمراره.
address يجب استخدام عنوان URL في request المستند كما هو لإنشاء مقبس الالتقاء، ولكنه يحتوي على المعلمات التالية:
| المعلمة | مطلوب | الوصف |
|---|---|---|
sb-hc-action |
نعم | لقبول مقبس ، يجب أن تكون المعلمة sb-hc-action=request |
إذا كان هناك خطأ ، يمكن للخدمة الرد على النحو التالي:
| رمز | خطأ | الوصف |
|---|---|---|
| 400 | طلب غير صالح | إجراء غير معروف أو عنوان URL غير صالح. |
| 403 | محظور | انتهت صلاحية عنوان URL. |
| 500 | خطأ داخلي | حدث خطأ ما في الخدمة |
بعد إنشاء الاتصال، يقوم الخادم بإيقاف تشغيل WebSocket عند إيقاف تشغيل مقبس HTTP الخاص بالعميل، أو بالحالة التالية:
| حالة WS | الوصف |
|---|---|
| 1001 | يقوم العميل المرسل بإيقاف تشغيل الاتصال. |
| 1001 | تم حذف مسار الاتصال المختلط أو تعطيله. |
| 1008 | انتهت صلاحية رمز الأمان المميز ، وبالتالي يتم انتهاك سياسة التفويض. |
| 1011 | حدث خطأ ما في الخدمة. |
تجديد الرمز المميز للمستمع
عندما يكون الرمز المميز للمستمع على وشك الانتهاء ، يمكنه استبداله عن طريق إرسال رسالة إطار نصي إلى الخدمة عبر قناة التحكم المحددة. تحتوي الرسالة على كائن JSON يسمى renewToken، والذي يعرف الخاصية التالية في هذا الوقت:
- الرمز المميز - رمز مميز صالح ومشفر بواسطة عنوان URL ل Service Bus Shared Access لمساحة الاسم أو الاتصال المختلط الذي يمنح حق الاستماع .
{
"renewToken": {
"token":
"SharedAccessSignature sr=http%3a%2f%2fcontoso.servicebus.windows.net%2fhyco%2f&sig=XXXXXXXXXX%3d&se=1471633754&skn=SasKeyName"
}
}
في حالة فشل التحقق من صحة الرمز المميز، يتم رفض الوصول، وتقوم الخدمة السحابية بإغلاق قناة التحكم WebSocket بحدوث خطأ. خلاف ذلك لا يوجد رد.
| حالة WS | الوصف |
|---|---|
| 1008 | انتهت صلاحية رمز الأمان المميز ، وبالتالي يتم انتهاك سياسة التفويض. |
بروتوكول توصيل مقبس الويب
بروتوكول المرسل مطابق بشكل فعال للطريقة التي يتم بها إنشاء المستمع. الهدف هو أقصى قدر من الشفافية ل WebSocket من طرف إلى طرف. العنوان المطلوب الاتصال به هو نفسه بالنسبة للمستمع ، ولكن "الإجراء" يختلف ويحتاج الرمز المميز إلى إذن مختلف:
wss://{namespace-address}/$hc/{path}?sb-hc-action=...&sb-hc-id=...&sb-hc-token=...
عنوان مساحة الاسم هو اسم المجال المؤهل بالكامل لمساحة اسم Azure Relay التي تستضيف الاتصال المختلط، عادة من النموذج {myname}.servicebus.windows.net.
يمكن أن يحتوي الطلب على رؤوس HTTP إضافية تعسفية، بما في ذلك تلك المعرفة بالتطبيق. تتدفق جميع الرؤوس المرفقة إلى المستمع ويمكن العثور عليها على connectHeader كائن رسالة التحكم في القبول .
خيارات معلمة سلسلة الاستعلام هي كما يلي:
| بارام | مطلوب؟ | الوصف |
|---|---|---|
sb-hc-action |
نعم | بالنسبة لدور المرسل ، يجب أن تكون sb-hc-action=connectالمعلمة . |
{path} |
نعم | (انظر الفقرة التالية) |
sb-hc-token |
نعم* | يجب على المستمع توفير رمز وصول مشترك صالح ومشفر بواسطة عنوان URL لمساحة الاسم أو الاتصال المختلط الذي يمنح حق الإرسال . |
sb-hc-id |
لا | معرف اختياري يتيح التتبع التشخيصي من طرف إلى طرف ويتم إتاحته للمستمع أثناء المصافحة المقبولة. |
هذا {path} هو مسار مساحة الاسم المشفرة بعنوان URL للاتصال المختلط الذي تم تكوينه مسبقا لتسجيل هذا المستمع عليه. path يمكن توسيع التعبير باستخدام لاحقة وتعبير سلسلة استعلام للتواصل بشكل أكبر. إذا تم تسجيل الاتصال المختلط ضمن المسار hyco، path فيمكن hyco/suffix?param=value&... اتباع التعبير بمعلمات سلسلة الاستعلام المحددة هنا. قد يكون التعبير الكامل بعد ذلك كما يلي:
wss://{namespace-address}/$hc/hyco/suffix?param=value&sb-hc-action=...[&sb-hc-id=...&]sb-hc-token=...
path يتم تمرير التعبير إلى المستمع في عنوان URI الموجود في رسالة التحكم "قبول".
إذا فشل اتصال WebSocket بسبب عدم تسجيل مسار الاتصال المختلط أو رمز مميز غير صالح أو مفقود أو أي خطأ آخر، يتم توفير ملاحظات الخطأ باستخدام نموذج ملاحظات حالة HTTP 1.1 العادي. يحتوي وصف الحالة على معرف تعقب الأخطاء الذي يمكن إبلاغه إلى موظفي دعم Azure:
| رمز | خطأ | الوصف |
|---|---|---|
| 404 | غير موجود | مسار الاتصال المختلط غير صالح أو عنوان URL الأساسي مشوه. |
| 401 | غير مصرح به | رمز الأمان مفقود أو مشوه أو غير صالح. |
| 403 | محظور | رمز الأمان غير صالح لهذا المسار ولهذا الإجراء. |
| 500 | خطأ داخلي | حدث خطأ ما في الخدمة. |
إذا تم إيقاف تشغيل اتصال WebSocket عمدا بواسطة الخدمة بعد إعداده في البداية، إبلاغ سبب القيام بذلك باستخدام رمز خطأ بروتوكول WebSocket مناسب إلى جانب رسالة خطأ وصفية تتضمن أيضا معرف تعقب.
| حالة WS | الوصف |
|---|---|
| 1000 | يقوم المستمع بإيقاف تشغيل المقبس. |
| 1001 | تم حذف مسار الاتصال المختلط أو تعطيله. |
| 1008 | انتهت صلاحية رمز الأمان، وبالتالي يتم انتهاك سياسة التفويض. |
| 1011 | حدث خطأ ما في الخدمة. |
بروتوكول طلب HTTP
يسمح بروتوكول طلب HTTP بطلبات HTTP التعسفية، باستثناء ترقيات البروتوكول. يتم توجيه طلبات HTTP إلى عنوان وقت التشغيل العادي للكيان، بدون الإصلاح $hc المستخدم لعملاء WebSocket للاتصالات المختلطة.
https://{namespace-address}/{path}?sb-hc-token=...
عنوان مساحة الاسم هو اسم المجال المؤهل بالكامل لمساحة اسم Azure Relay التي تستضيف الاتصال المختلط، عادة من النموذج {myname}.servicebus.windows.net.
يمكن أن يحتوي الطلب على رؤوس HTTP إضافية تعسفية، بما في ذلك تلك المعرفة بالتطبيق. تتدفق جميع الرؤوس المرفقة، باستثناء تلك المحددة مباشرة في RFC7230 (راجع طلب الرسالة) إلى المستمع ويمكن العثور عليها على requestHeader كائن رسالة الطلب .
خيارات معلمة سلسلة الاستعلام هي كما يلي:
| بارام | مطلوب؟ | الوصف |
|---|---|---|
sb-hc-token |
نعم* | يجب على المستمع توفير رمز وصول مشترك صالح ومشفر بواسطة عنوان URL لمساحة الاسم أو الاتصال المختلط الذي يمنح حق الإرسال . |
يمكن أيضا حمل الرمز المميز إما في ServiceBusAuthorization رأس HTTP أو Authorization HTTP. يمكن حذف الرمز المميز إذا تم تكوين الاتصال المختلط للسماح بالطلبات المجهولة.
نظرا لأن الخدمة تعمل بشكل فعال كوكيل ، حتى لو لم يكن كوكيل HTTP حقيقي ، فإنها إما تضيف رأسا Via أو تعلق على الرأس الحالي Via المتوافق مع RFC7230 ، القسم 5.7.1.
تضيف الخدمة اسم مضيف مساحة اسم الترحيل إلى Via.
| رمز | رسالة | الوصف |
|---|---|---|
| 200 | موافق | تم التعامل مع الطلب من قبل مستمع واحد على الأقل. |
| 202 | مقبول | تم قبول الطلب من قبل مستمع واحد على الأقل. |
إذا كان هناك خطأ، يمكن للخدمة الرد على النحو التالي. يمكن تحديد ما إذا كانت الاستجابة تنشأ من الخدمة أو من المستمع من Via خلال وجود الرأس. إذا كان الرأس موجودا، فستكون الاستجابة من المستمع.
| رمز | خطأ | الوصف |
|---|---|---|
| 404 | غير موجود | مسار الاتصال المختلط غير صالح أو عنوان URL الأساسي مشوه. |
| 401 | غير مصرح به | رمز الأمان مفقود أو مشوه أو غير صالح. |
| 403 | محظور | رمز الأمان غير صالح لهذا المسار ولهذا الإجراء. |
| 500 | خطأ داخلي | حدث خطأ ما في الخدمة. |
| 503 | بوابة غير صالحة | تعذر توجيه الطلب إلى أي مستمع. |
| 504 | مهلة البوابة | تم توجيه الطلب إلى مستمع، لكن المستمع لم يقر بالاستلام في الوقت المطلوب. |