بروتوكول azure Relay Hybrid الاتصال ions
Azure Relay هي واحدة من ركائز القدرة الرئيسية للنظام الأساسي ناقل خدمة Azure. تعد إمكانية الاتصال المختلطة الجديدة من Relay تطورا آمنا ومفتوح البروتوكول استنادا إلى HTTP وWebSockets. يحل محل الأول، المسمى بالتساوي ميزة خدمات BizTalk التي تم إنشاؤها على أساس بروتوكول خاص. سيستمر تكامل الاتصال المختلطة في Azure App Services في العمل كما هي.
تتيح الاتصال المختلطة الاتصال ثنائي الاتجاه، والاستجابة للطلب، والتدفق الثنائي، وتدفق مخطط البيانات البسيط بين تطبيقين شبكيين. يمكن أن يكون أي من الطرفين أو كليهما وراء NATs أو جدران الحماية.
توضح هذه المقالة التفاعلات من جانب العميل مع ترحيل الاتصال المختلطة لتوصيل العملاء في أدوار المستمع والمرسل. كما يصف كيفية قبول المستمعين للاتصالات والطلبات الجديدة.
نموذج التفاعل
يربط ترحيل الاتصال المختلطة طرفين من خلال توفير نقطة موعد في سحابة Azure يمكن للأطراف اكتشافها والاتصال بها من منظور شبكتهم الخاصة. تسمى نقطة الموعد "hybrid الاتصال ion" في هذه الوثائق والوثائق الأخرى، في واجهات برمجة التطبيقات، وأيضا في مدخل Microsoft Azure. يشار إلى نقطة نهاية خدمة الاتصال ions المختلطة باسم "الخدمة" لبقية هذه المقالة.
تسمح الخدمة بترحيل اتصالات مأخذ توصيل الويب وطلبات واستجابات HTTP(S).
يعتمد نموذج التفاعل على التسمية التي أنشأتها العديد من واجهات برمجة تطبيقات الشبكات الأخرى. هناك وحدة استماع تشير أولا إلى الاستعداد للتعامل مع الاتصالات الواردة، ثم تقبلها بعد ذلك عند وصولها. على الجانب الآخر، يتصل العميل بوحدة الاستماع، ويتوقع أن يتم قبول هذا الاتصال لإنشاء مسار اتصال ثنائي الاتجاه. "الاتصال" و"Listen" و"Accept" هي نفس المصطلحات التي تجدها في معظم واجهات برمجة التطبيقات للمأخذ.
يحتوي أي نموذج اتصال مرحل على أي طرف يقوم بإجراء اتصالات صادرة نحو نقطة نهاية الخدمة. وهذا يجعل "المستمع" أيضا "عميلا" في الاستخدام العامي، وقد يتسبب أيضا في التحميل الزائد للمصطلحات الأخرى. لذلك، فإن المصطلحات الدقيقة المستخدمة في الاتصال المختلطة هي كما يلي:
تسمى البرامج على كلا جانبي الاتصال "العملاء"، نظرا لأنهم عملاء للخدمة. العميل الذي ينتظر ويقبل الاتصالات هو "المستمع"، أو يقال إنه في "دور المستمع". يسمى العميل الذي يبدأ اتصالا جديدا نحو وحدة استماع عبر الخدمة "المرسل"، أو في "دور المرسل".
تفاعلات وحدة الاستماع
لدى وحدة الاستماع خمسة تفاعلات مع الخدمة؛ يتم وصف جميع تفاصيل الأسلاك لاحقا في هذه المقالة في القسم المرجعي.
يتم تلقي رسائل الاستماع والقبول والطلب من الخدمة. يتم إرسال عمليات التجديد و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 ذات الصلة فقط بالعلاقة بين المرسل وبوابة Relay HTTP، بما في ذلك معلومات التخويل. يتم نقل هيئات طلب HTTP بشفافية كإطارات WebSocket ثنائية.
يمكن للمستمع الاستجابة لطلبات HTTP باستخدام إيماءة استجابة مكافئة.
يستخدم تدفق الطلب/الاستجابة قناة التحكم بشكل افتراضي، ولكن يمكن "ترقيته" إلى WebSocket مميز عند الحاجة. تعمل اتصالات WebSocket المميزة على تحسين معدل النقل لكل محادثة عميل، ولكنها تثقل كاهل المستمع بمزيد من الاتصالات التي تحتاج إلى معالجة، والتي قد لا تكون رغبة في أن تكون قادرة على العملاء الخفيفي الوزن.
في قناة التحكم، تقتصر هيئات الطلب والاستجابة على 64 كيلوبايت على الأكثر في الحجم. تقتصر بيانات تعريف رأس HTTP على إجمالي 32 كيلوبايت. إذا تجاوز الطلب أو الاستجابة هذا الحد، يجب على وحدة الاستماع الترقية إلى WebSocket الملتقي باستخدام إيماءة مكافئة لمعالجة قبول.
بالنسبة للطلبات، تقرر الخدمة ما إذا كنت تريد توجيه الطلبات عبر قناة التحكم. وهذا يشمل، على سبيل المثال لا الحصر، الحالات التي يتجاوز فيها الطلب 64 كيلوبايت (الرؤوس بالإضافة إلى النص الأساسي) بشكل صريح، أو إذا تم إرسال الطلب مع ترميز النقل "المقتسم" وكانت الخدمة لديها سبب لتوقع أن يتجاوز الطلب 64 كيلوبايت أو إذا لم تكن قراءة الطلب فورية. إذا اختارت الخدمة تسليم الطلب أكثر من موعد، فإنها تمرر عنوان الموعد فقط إلى وحدة الاستماع. يجب على وحدة الاستماع بعد ذلك إنشاء WebSocket الملتقي، وتقدم الخدمة الطلب الكامل على الفور بما في ذلك الهيئات عبر WebSocket الملتقي. يجب أن تستخدم الاستجابة أيضا WebSocket الملتقي.
بالنسبة للطلبات التي تصل عبر قناة التحكم، يقرر المستمع ما إذا كان سيستجيب عبر قناة التحكم أو عبر موعد. يجب أن تتضمن الخدمة عنوان موعد مع كل طلب يتم توجيهه عبر قناة التحكم. هذا العنوان صالح فقط للترقية من الطلب الحالي.
إذا اختار المستمع الترقية، فإنه يتصل ويسلم الاستجابة على الفور عبر مأخذ التوصيل المحدد.
بمجرد إنشاء WebSocket الملتقي، يجب أن يحتفظ به المستمع لمزيد من المعالجة للطلبات والاستجابات من نفس العميل. ستحافظ الخدمة على WebSocket طالما استمر اتصال مأخذ توصيل HTTPS بالمرسل وستوجه جميع الطلبات اللاحقة من هذا المرسل عبر WebSocket الذي تم صيانته. إذا اختار المستمع إسقاط WebSocket الملتقي من جانبه، فستسقط الخدمة أيضا الاتصال بالمرسل، بغض النظر عما إذا كان الطلب اللاحق قيد التقدم بالفعل.
عملية التجديد
قد تنتهي صلاحية رمز الأمان الذي يجب استخدامه لتسجيل وحدة الاستماع والحفاظ على قناة التحكم أثناء نشاط وحدة الاستماع. لا تؤثر انتهاء صلاحية الرمز المميز على الاتصالات المستمرة، ولكنها تتسبب في إسقاط قناة التحكم من قبل الخدمة في لحظة انتهاء الصلاحية أو بعد ذلك بقليل. عملية "التجديد" هي رسالة JSON التي يمكن للمستمع إرسالها لاستبدال الرمز المميز المقترن بقناة التحكم، بحيث يمكن الاحتفاظ بقناة التحكم لفترات طويلة.
عملية Ping
إذا بقيت قناة التحكم الخامة لفترة طويلة، فقد يقوم الوسطاء في الطريق، مثل موازنات التحميل أو NATs بإسقاط اتصال TCP. تتجنب عملية "ping" ذلك عن طريق إرسال كمية صغيرة من البيانات على القناة التي تذكر الجميع على مسار الشبكة بأن الاتصال من المفترض أن يكون على قيد الحياة، كما أنه يعمل كاختبار "مباشر" للمستمع. إذا فشل اختبار الاتصال، يجب اعتبار قناة التحكم غير قابلة للاستخدام ويجب على وحدة الاستماع إعادة الاتصال.
تفاعل المرسل
لدى المرسل تفاعلان مع الخدمة: فهو يربط مأخذ توصيل ويب أو يرسل طلبات عبر HTTPS. لا يمكن إرسال الطلبات عبر مأخذ ويب من دور المرسل.
عملية الاتصال
تفتح عملية "الاتصال" WebSocket على الخدمة، مع توفير اسم الاتصال المختلط و (اختياريا، ولكن مطلوب بشكل افتراضي) إذن "إرسال" رمز أمان مميز في سلسلة الاستعلام. ثم تتفاعل الخدمة مع وحدة الإصغاء بالطريقة الموضحة سابقا، وتنشئ وحدة الاستماع اتصالا منضما إلى WebSocket هذا. بعد قبول WebSocket، تكون جميع التفاعلات الإضافية على WebSocket هذه مع وحدة استماع متصلة.
عملية الطلب
بالنسبة إلى الاتصال المختلطة التي تم تمكين الميزة لها، يمكن للمرسل إرسال طلبات HTTP غير مقيدة إلى حد كبير إلى المستمعين.
باستثناء الرمز المميز للوصول إلى الترحيل المضمن في سلسلة الاستعلام أو في رأس HTTP للطلب، يكون Relay شفافا تماما لجميع عمليات HTTP على عنوان الترحيل وجميع لاحقات مسار عنوان الترحيل، مما يترك وحدة الاستماع تتحكم بالكامل في التخويل الشامل وحتى ميزات ملحق HTTP مثل CORS.
يتم تشغيل تخويل المرسل مع نقطة نهاية الترحيل بشكل افتراضي، ولكنه اختياري. يمكن لمالك الاتصال المختلط اختيار السماح للمرسلين المجهولين. ستعترض الخدمة معلومات التخويل وتفحصها وتجردها كما يلي:
- إذا كانت سلسلة الاستعلام تحتوي على تعبير
sb-hc-token، فسيتم دائما تجريد التعبير من سلسلة الاستعلام. سيتم تقييمه إذا تم تشغيل تخويل الترحيل. - إذا كانت رؤوس الطلب تحتوي على
ServiceBusAuthorizationرأس، فسيتم دائما تجريد تعبير الرأس من مجموعة الرؤوس. سيتم تقييمه إذا تم تشغيل تخويل الترحيل. - فقط إذا تم تشغيل تخويل الترحيل، وإذا كانت رؤوس الطلب تحتوي على
Authorizationرأس، ولم يكن أي من التعبيرات السابقة موجودا، فسيتم تقييم العنوان وتجريده. وإلا،Authorizationيتم تمرير دائما كما هي.
إذا لم يكن هناك وحدة استماع نشطة، سترجع الخدمة رمز خطأ 502 "بوابة غير صحيحة". إذا لم تظهر الخدمة لمعالجة الطلب، فسترجع الخدمة "مهلة البوابة" 504 بعد 60 ثانية.
ملخص التفاعل
نتيجة نموذج التفاعل هذا هو أن عميل المرسل يخرج من المصافحة باستخدام WebSocket "نظيف"، وهو متصل بمستمع ولا يحتاج إلى أي ديباجات أو إعداد إضافي. يتيح هذا النموذج عمليا لأي تطبيق عميل WebSocket موجود الاستفادة بسهولة من خدمة hybrid الاتصال ions عن طريق توفير عنوان 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 |
نعم* | يجب أن توفر وحدة الاستماع رمز وصول مشترك لناقل خدمة Microsoft Azure صالحا مرمزا بعنوان URL لمساحة الاسم أو الاتصال المختلطة التي تمنح حق الاستماع. |
sb-hc-id |
لا | يتيح هذا المعرف الاختياري الذي يوفره العميل تتبع التشخيص من طرف إلى طرف. |
إذا فشل اتصال WebSocket بسبب عدم تسجيل مسار الاتصال المختلط، أو رمز مميز غير صالح أو مفقود، أو خطأ آخر، يتم توفير ملاحظات الخطأ باستخدام نموذج ملاحظات حالة HTTP 1.1 العادي. يحتوي وصف الحالة على معرف تتبع خطأ يمكن توصيله إلى موظفي دعم Azure:
| الرمز | خطأ | الوصف |
|---|---|---|
| 404 | غير موجود | مسار الاتصال المختلط غير صحيح أو تم تكوين عنوان URL الأساسي بشكل غير صحيح. |
| 401 | غير مصرح به | رمز الأمان مفقود أو غير صحيح أو غير صالح. |
| 403 | محظور | رمز الأمان غير صالح لهذا المسار لهذا الإجراء. |
| 500 | خطأ داخلي | حدث خطأ ما في الخدمة. |
إذا تم إيقاف اتصال WebSocket عن قصد بواسطة الخدمة بعد إعداده في البداية، يتم توصيل سبب القيام بذلك باستخدام رمز خطأ بروتوكول WebSocket مناسب إلى جانب رسالة خطأ وصفية تتضمن أيضا معرف تعقب. لن تقوم الخدمة بإيقاف تشغيل قناة التحكم دون مواجهة شرط خطأ. يتم التحكم في أي إيقاف تشغيل نظيف من قبل العميل.
| حالة WS | الوصف |
|---|---|
| 1001 | تم حذف مسار الاتصال المختلط أو تعطيله. |
| 1008 | انتهت صلاحية الرمز المميز للأمان، لذلك يتم انتهاك نهج التخويل. |
| 1011 | حدث خطأ ما في الخدمة. |
قبول تأكيد الاتصال
يتم إرسال إعلام "القبول" بواسطة الخدمة إلى وحدة الاستماع عبر قناة التحكم التي تم إنشاؤها مسبقا كرسالة JSON في إطار نص WebSocket. لا يوجد رد على هذه الرسالة.
تحتوي الرسالة على كائن JSON يسمى "accept"، والذي يحدد الخصائص التالية في هذا الوقت:
- address – سلسلة URL التي سيتم استخدامها لإنشاء WebSocket إلى الخدمة لقبول اتصال وارد.
- المعرف - المعرف الفريد لهذا الاتصال. إذا تم توفير المعرف من قبل عميل المرسل، فهي القيمة المقدمة للمرسل، وإلا فهي قيمة تم إنشاؤها بواسطة النظام.
- connectHeaders – جميع عناوين HTTP التي تم توفيرها إلى نقطة نهاية الترحيل من قبل المرسل، والتي تتضمن أيضا عناوين Sec-WebSocket-Protocol ورؤوس 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 الرسالة ويلحق معلمتين لسلسلة الاستعلام به، كما يلي:
| Param | المطلوب | الوصف |
|---|---|---|
| sb-hc-statusCode | نعم | رمز حالة HTTP الرقمي. |
| sb-hc-statusDescription | نعم | سبب قابل للقراءة البشرية للرفض. |
ثم يتم استخدام 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,
...
}
}
----------------------------------
محتوى JSON ل request كما يلي:
address - سلسلة URI. إنه عنوان الموعد الذي يجب استخدامه لهذا الطلب. إذا كان الطلب الوارد أكبر من 64 كيلوبايت، يتم ترك باقي هذه الرسالة فارغا، ويجب على العميل بدء تأكيد اتصال موعد مكافئ للعملية الموضحة
acceptأدناه. ثم ستضع الخدمة كاملrequestعلى مأخذ ويب الذي تم إنشاؤه. إذا كان من المتوقع أن تتجاوز الاستجابة 64 كيلوبايت، يجب على المستمع أيضا بدء تأكيد اتصال موعد، ثم نقل الاستجابة عبر مأخذ ويب الذي تم إنشاؤه.المعرف – سلسلة. المعرف الفريد لهذا الطلب.
requestHeaders – يحتوي هذا الكائن على جميع رؤوس HTTP التي تم توفيرها إلى نقطة النهاية من قبل المرسل، باستثناء معلومات التخويل كما هو موضح أعلاه، والعناوين التي تتعلق بشكل صارم بالاتصال بالبوابة. على وجه التحديد، يتم تجريد كافة الرؤوس المعرفة أو المحجوزة في RFC7230، باستثناء
Via، وعدم إعادة توجيهها:Connection(RFC7230، القسم 6.1)Content-Length(RFC7230، القسم 3.3.2)Host(RFC7230، القسم 5.4)TE(RFC7230، القسم 4.3)Trailer(RFC7230، القسم 4.4)Transfer-Encoding(RFC7230، القسم 3.3.1)Upgrade(RFC7230، القسم 6.7)Close(RFC7230، القسم 8.1)
requestTarget – سلسلة. تحتوي هذه الخاصية على "Request Target" (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يتم الرد عليها. - رمز الحالة – رقم. مطلوب. رمز حالة HTTP رقمي يشير إلى نتيجة الإعلام. يسمح بجميع رموز الحالة RFC7231، القسم 6، باستثناء 502 "بوابة غير صحيحة" و504 "مهلة البوابة".
- 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 للوصول المشترك لناقل خدمة Microsoft Azure لمساحة الاسم أو الاتصال المختلط الذي يمنح حق الاستماع.
{
"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 كائن رسالة التحكم قبول.
خيارات معلمة سلسلة الاستعلام كما يلي:
| Param | مطلوب؟ | الوصف |
|---|---|---|
sb-hc-action |
نعم | بالنسبة لدور المرسل، يجب أن تكون sb-hc-action=connectالمعلمة . |
{path} |
نعم | (راجع الفقرة التالية) |
sb-hc-token |
نعم* | يجب أن توفر وحدة الاستماع رمز وصول مشترك لناقل خدمة Microsoft Azure صالحا مرمزا بعنوان 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 infix المستخدم للاتصالات المختلطة لعملاء WebSocket.
https://{namespace-address}/{path}?sb-hc-token=...
عنوان مساحة الاسم هو اسم المجال المؤهل بالكامل لمساحة اسم Azure Relay التي تستضيف الاتصال المختلط، عادة من النموذج {myname}.servicebus.windows.net.
يمكن أن يحتوي الطلب على رؤوس HTTP إضافية عشوائية، بما في ذلك رؤوس محددة من قبل التطبيق. تتدفق جميع الرؤوس المتوفرة، باستثناء تلك المعرفة مباشرة في RFC7230 (راجع رسالة الطلب) إلى وحدة الاستماع ويمكن العثور عليها على requestHeader كائن رسالة الطلب .
خيارات معلمة سلسلة الاستعلام كما يلي:
| Param | مطلوب؟ | الوصف |
|---|---|---|
sb-hc-token |
نعم* | يجب أن توفر وحدة الاستماع رمز وصول مشترك لناقل خدمة Microsoft Azure صالحا مرمزا بعنوان URL لمساحة الاسم أو الاتصال المختلط الذي يمنح حق الإرسال. |
يمكن أيضا حمل الرمز المميز إما في ServiceBusAuthorization عنوان HTTP أو Authorization . يمكن حذف الرمز المميز إذا تم تكوين الاتصال المختلط للسماح بالطلبات المجهولة.
نظرا لأن الخدمة تعمل بشكل فعال كوكيل، حتى لو لم تكن كوكيل HTTP صحيح، فإنها إما تضيف عنوانا Via أو تضيف تعليقا توضيحيا للرأس الموجود Via المتوافق مع RFC7230، القسم 5.7.1.
تضيف الخدمة اسم مضيف مساحة اسم الترحيل إلى Via.
| الرمز | رسالة | الوصف |
|---|---|---|
| 200 | موافق | تمت معالجة الطلب من قبل وحدة استماع واحدة على الأقل. |
| 202 | مقبولة | تم قبول الطلب من قبل وحدة استماع واحدة على الأقل. |
إذا كان هناك خطأ، يمكن للخدمة الرد على النحو التالي. يمكن تحديد ما إذا كانت الاستجابة تنشأ من الخدمة أو من وحدة الاستماع من Via خلال وجود الرأس. إذا كان العنوان موجودا، تكون الاستجابة من وحدة الاستماع.
| الرمز | خطأ | الوصف |
|---|---|---|
| 404 | غير موجود | مسار الاتصال المختلط غير صحيح أو تم تكوين عنوان URL الأساسي بشكل غير صحيح. |
| 401 | غير مصرح به | رمز الأمان مفقود أو غير صحيح أو غير صالح. |
| 403 | محظور | رمز الأمان غير صالح لهذا المسار ولهذا الإجراء. |
| 500 | خطأ داخلي | حدث خطأ ما في الخدمة. |
| 503 | بوابة غير صالحة | تعذر توجيه الطلب إلى أي وحدة استماع. |
| 504 | مهلة البوابة | تم توجيه الطلب إلى وحدة استماع، ولكن المستمع لم يقر بالإيصال في الوقت المطلوب. |