Protokol Koneksi Hibrid Azure Relay
Azure Relay adalah salah satu pilar kemampuan utama platform Azure Service Bus. Kemampuan Koneksi Hibrid baru Relay adalah evolusi protokol terbuka yang aman berdasarkan HTTP dan WebSocket. Ini menggantikan fitur BizTalk Services yang sebelumnya, sama-sama bernama yang dibangun di atas fondasi protokol milik. Integrasi Koneksi Hibrid ke dalam Azure App Services akan terus berfungsi apa adanya.
Koneksi Hibrid memungkinkan komunikasi aliran dua arah, respons permintaan, dan aliran biner, dan aliran datagram sederhana antara dua aplikasi berjaringan. Salah satu atau kedua belah pihak dapat berada di belakang NATs atau firewall.
Artikel ini menjelaskan interaksi pihak klien dengan relai Koneksi Hibrid untuk menghubungkan klien dalam peran pendengar dan pengirim. Ini juga menjelaskan bagaimana pendengar menerima koneksi dan permintaan baru.
Model interaksi
Relai Hybrid Connections menghubungkan dua pihak dengan menyediakan titik pertemuan di cloud Azure yang dapat ditemukan dan disambungkan oleh pihak-pihak dari perspektif jaringan mereka sendiri. Titik pertemuan disebut "Koneksi Hibrid" dalam dokumentasi ini dan lainnya, di API, dan juga di portal Microsoft Azure. Titik akhir layanan Koneksi Hibrid disebut sebagai "layanan" untuk sisa artikel ini.
Layanan ini memungkinkan untuk menyampaikan koneksi Web Socket dan permintaan dan respons HTTP(S).
Model interaksi bersandar pada nomenklatur yang ditetapkan oleh banyak API jaringan lainnya. Ada pendengar yang pertama kali menunjukkan kesiapan untuk menangani koneksi masuk, dan kemudian menerimanya saat mereka tiba. Di sisi lain, klien terhubung ke arah pendengar, mengharapkan koneksi itu diterima untuk membuat jalur komunikasi dua arah. "Hubungkan", "Dengar", dan "Terima" adalah istilah yang sama dengan yang Anda temukan di sebagian besar API soket.
Setiap model komunikasi yang disampaikan memiliki salah satu pihak yang membuat koneksi keluar menuju titik akhir layanan. Ini membuat "pendengar" juga menjadi "klien" dalam penggunaan sehari-hari, dan juga dapat menyebabkan kelebihan terminologi lainnya. Oleh karena itu terminologi yang tepat digunakan untuk Koneksi Hibrid adalah sebagai berikut:
Program di kedua sisi koneksi disebut "klien," karena mereka klien ke layanan. Klien yang menunggu dan menerima koneksi adalah "listener," atau dikatakan berada dalam "peran pendengar." Klien yang memulai koneksi baru ke arah pendengar melalui layanan disebut "pengirim," atau berada dalam "peran pengirim."
Interaksi pendengar
Pendengar memiliki lima interaksi dengan layanan; semua detail kawat dijelaskan nanti di artikel ini di bagian referensi.
Pesan Dengar, Terima, dan Permintaan diterima dari layanan. Operasi Perpanjangan, dan Ping dikirim oleh pendengar.
Mendengarkan pesan
Untuk menunjukkan kesiapan pada layanan bahwa pendengar siap menerima koneksi, ia membuat koneksi WebSocket keluar. Jabat tangan koneksi membawa nama Koneksi Hibrid yang dikonfigurasi pada namespace Relay, dan token keamanan yang menganugerahkan "Dengar" langsung pada nama itu.
Ketika WebSocket diterima oleh layanan, pendaftaran selesai dan WebSocket yang ditetapkan tetap hidup sebagai "saluran kontrol" untuk memungkinkan semua interaksi berikutnya. Layanan ini memungkinkan hingga 25 pendengar bersamaan untuk satu Koneksi Hibrid. Kuota untuk AppHooks harus ditentukan.
Untuk Koneksi Hibrid, jika ada dua pendengar aktif atau lebih, koneksi masuk diseimbangkan di seluruhnya secara acak; distribusi yang adil dicoba dengan upaya terbaik.
Menerima pesan
Ketika pengirim membuka koneksi baru pada layanan, layanan memilih dan memberi tahu salah satu pendengar aktif pada Koneksi Hibrid. Pemberitahuan ini dikirim ke pendengar melalui saluran kontrol terbuka sebagai pesan JSON. Pesan berisi URL titik akhir WebSocket yang harus disambungkan pendengar untuk menerima koneksi.
URL dapat dan harus digunakan langsung oleh pendengar tanpa pekerjaan tambahan. Informasi yang dikodekan hanya berlaku untuk waktu yang singkat, pada dasarnya selama pengirim bersedia menunggu koneksi dibuat secara ujung-ke-ujung. Maksimum yang harus diasumsikan adalah 30 detik. URL hanya dapat digunakan untuk satu upaya koneksi yang berhasil. Segera setelah koneksi WebSocket dengan URL pertemuan ditetapkan, semua aktivitas lebih lanjut di WebSocket ini disampaikan dari dan ke pengirim. Perilaku ini terjadi tanpa intervensi atau interpretasi oleh layanan.
Pesan permintaan
Selain koneksi WebSocket, pendengar juga dapat menerima bingkai permintaan HTTP dari pengirim, jika kemampuan ini diaktifkan secara eksplisit pada Koneksi Hibrid.
Pendengar yang melampirkan ke Koneksi Hibrid dengan dukungan HTTP HARUS menangani gerakan request. Pendengar yang tidak menangani request dan karenanya menyebabkan kesalahan waktu habis berulang saat terhubung MUNGKIN diblokir oleh layanan di masa mendatang.
Metadata header bingkai HTTP diterjemahkan ke dalam JSON untuk penanganan yang lebih sederhana oleh kerangka kerja pendengar, juga karena pustaka penguraian header HTTP lebih jarang daripada pengurai JSON. Metadata HTTP yang hanya relevan untuk hubungan antara pengirim dan gateway HTTP Relay, termasuk informasi otorisasi, tidak diteruskan. Badan permintaan HTTP secara transparan ditransfer sebagai bingkai WebSocket biner.
Pendengar dapat menanggapi permintaan HTTP menggunakan gerakan respons yang setara.
Alur permintaan/respons menggunakan saluran kontrol secara default, tetapi dapat "ditingkatkan" ke WebSocket pertemuan yang berbeda kapan pun diperlukan. Koneksi WebSocket yang berbeda meningkatkan keluaran untuk setiap percakapan klien, tetapi mereka membebani pendengar dengan lebih banyak koneksi yang perlu ditangani, yang mungkin tidak diinginkan untuk klien yang ringan.
Pada saluran kontrol, badan permintaan dan respons dibatasi paling banyak 64 kB dalam ukuran. Metadata header HTTP dibatasi hingga total 32 kB. Jika permintaan atau respons melebihi ambang batas tersebut, pendengar HARUS meningkatkan ke WebSocket pertemuan menggunakan gerakan yang setara dengan menangani Menerima.
Untuk permintaan, layanan memutuskan apakah akan merutekan permintaan melalui saluran kontrol. Ini termasuk, tetapi mungkin tidak terbatas pada kasus di mana permintaan melebihi 64 kB (header plus tubuh) langsung, atau jika permintaan dikirim dengan pengkodean transfer "dipotong" dan layanan memiliki alasan untuk mengharapkan permintaan melebihi 64 kB atau membaca permintaan tidak instan. Jika layanan memilih untuk mengirimkan permintaan melalui pertemuan, itu hanya meneruskan alamat pertemuan kepada pendengar. Pendengar kemudian HARUS mendirikan WebSocket pertemuan dan layanan segera memberikan permintaan penuh termasuk badan di atas WebSocket pertemuan. Tanggapannya juga HARUS menggunakan WebSocket pertemuan.
Untuk permintaan yang sampai di saluran kontrol, pendengar memutuskan apakah akan merespons melalui saluran kontrol atau melalui pertemuan. Layanan HARUS mencakup alamat pertemuan dengan setiap permintaan yang dirutekan melalui saluran kontrol. Alamat ini hanya berlaku untuk pemutakhiran dari permintaan saat ini.
Jika pendengar memilih untuk meningkatkan, pendengar akan terhubung dan segera memberikan respons atas soket pertemuan yang ditetapkan.
Setelah WebSocket pertemuan ditetapkan, pendengar HARUS mempertahankannya untuk penanganan lebih lanjut permintaan dan tanggapan dari klien yang sama. Layanan ini akan mempertahankan WebSocket selama koneksi soket HTTPS dengan pengirim tetap ada dan akan merutekan semua permintaan berikutnya dari pengirim tersebut melalui WebSocket yang dikelola. Jika pendengar memilih untuk menjatuhkan WebSocket pertemuan dari sisinya, layanan juga akan menjatuhkan koneksi ke pengirim, terlepas dari apakah permintaan berikutnya mungkin sudah berlangsung.
Operasi perpanjangan
Token keamanan yang harus digunakan untuk mendaftarkan pendengar dan mempertahankan saluran kontrol dapat kedaluwarsa saat pendengar aktif. Kedaluwarsa token tidak memengaruhi koneksi yang sedang berlangsung, tetapi itu menyebabkan saluran kontrol dihilangkan oleh layanan pada atau segera setelah saat kedaluwarsa. Operasi "perbarui" adalah pesan JSON yang dapat dikirim pendengar untuk mengganti token yang terkait dengan saluran kontrol, sehingga saluran kontrol dapat dipertahankan untuk jangka waktu yang lama.
Operasi Ping
Jika saluran kontrol tetap menganggur untuk waktu yang lama, perantara dalam perjalanan, seperti penyeimbang beban atau NATs dapat menjatuhkan koneksi TCP. Operasi "ping" menghindari itu dengan mengirim sejumlah kecil data di saluran yang mengingatkan semua orang di rute jaringan bahwa koneksi dimaksudkan untuk hidup, dan itu juga berfungsi sebagai tes "langsung" untuk pendengar. Jika ping gagal, saluran kontrol harus dianggap tidak dapat digunakan dan pendengar harus terhubung kembali.
Interaksi pengirim
Pengirim memiliki dua interaksi dengan layanan: menghubungkan Soket Web atau mengirim permintaan melalui HTTPS. Permintaan tidak dapat dikirim melalui Soket Web dari peran pengirim.
Operasi Sambungkan
Operasi "sambungkan" membuka WebSocket pada layanan, memberikan nama Koneksi Hibrid dan (opsional, tetapi diperlukan secara default) token keamanan yang memberikan izin "Kirim" dalam string kueri. Layanan kemudian berinteraksi dengan pendengar dengan cara yang dijelaskan sebelumnya, dan pendengar membuat koneksi pertemuan yang bergabung dengan WebSocket ini. Setelah WebSocket diterima, semua interaksi lebih lanjut tentang WebSocket tersebut adalah dengan pendengar yang terhubung.
Operasi permintaan
Untuk Koneksi Hibrid yang fiturnya telah diaktifkan, pengirim dapat mengirim permintaan HTTP yang sebagian besar tidak terbatas kepada pendengar.
Kecuali untuk token akses Relay yang disematkan dalam string kueri atau di header HTTP permintaan, Relay sepenuhnya transparan untuk semua operasi HTTP pada alamat Relay dan semua akhiran jalur alamat Relay, meninggalkan pendengar sepenuhnya mengendalikan otorisasi ujung-ke-ujung dan bahkan fitur ekstensi HTTP seperti CORS.
Otorisasi pengirim dengan titik akhir Relay diaktifkan secara default, tetapi OPSIONAL. Pemilik Sambungan Hibrid dapat memilih untuk memperbolehkan pengirim anonim. Layanan ini akan mencegat, memeriksa, dan menghapus informasi otorisasi sebagai berikut:
- Jika string kueri berisi
sb-hc-tokenekspresi, ekspresinya akan SELALU dilucuti dari string kueri. Ini akan dievaluasi jika otorisasi Relay diaktifkan. - Jika header permintaan berisi
ServiceBusAuthorizationheader, ekspresi header akan SELALU dilucuti dari kumpulan header. Ini akan dievaluasi jika otorisasi Relay diaktifkan. - Hanya jika otorisasi Relay diaktifkan, dan jika header permintaan berisi
Authorizationheader, dan tidak ada ekspresi sebelumnya, header akan dievaluasi dan dilucuti. Jika tidak,Authorizationselalu diteruskan apa adanya.
Jika tidak ada pendengar aktif, layanan akan mengembalikan kode kesalahan "Gateway Buruk" 502. Jika layanan tampaknya tidak menangani permintaan, layanan akan mengembalikan 504 "Batas Waktu Gateway" setelah 60 detik.
Ringkasan interaksi
Hasil dari model interaksi ini adalah bahwa klien pengirim keluar dari jabat tangan dengan WebSocket "bersih", yang terhubung ke pendengar dan yang tidak perlu pembukaan atau persiapan lebih lanjut. Model ini memungkinkan hampir semua implementasi klien WebSocket yang ada untuk dengan mudah memanfaatkan layanan Koneksi Hibrid dengan memasok URL yang dibangun dengan benar ke dalam lapisan klien WebSocket mereka.
Koneksi pertemuan WebSocket yang diperoleh pendengar melalui interaksi yang diterima juga bersih dan dapat diserahkan ke implementasi server WebSocket yang ada dengan beberapa abstraksi ekstra minimal yang membedakan antara operasi "terima" pada pendengar jaringan lokal kerangka kerja mereka dan koneksi hibrida operasi "terima" jarak jauh.
Model permintaan/respons HTTP memberi pengirim area permukaan protokol HTTP yang sebagian besar tidak dibatasi dengan lapisan otorisasi OPSIONAL. Pendengar mendapatkan bagian header permintaan HTTP sebelum diurai yang dapat diubah kembali menjadi permintaan HTTP hilir atau ditangani apa adanya, dengan bingkai biner yang membawa badan HTTP. Respons menggunakan format yang sama. Interaksi dengan kurang dari 64 KB badan permintaan dan respons dapat ditangani melalui satu Soket Web yang dibagikan untuk semua pengirim. Permintaan dan respons yang lebih besar dapat ditangani menggunakan model pertemuan.
Referensi protokol
Bagian ini menjelaskan detail interaksi protokol yang dijelaskan sebelumnya.
Semua koneksi WebSocket dibuat pada port 443 sebagai peningkatan dari HTTPS 1.1, yang umumnya diabstraksi oleh beberapa kerangka kerja WebSocket atau API. Deskripsi di sini menjaga implementasi tetap netral, tanpa menyarankan kerangka kerja tertentu.
Protokol pendengar
Protokol pendengar terdiri dari dua gerakan koneksi dan tiga operasi pesan.
Koneksi saluran kontrol pendengar
Saluran kontrol dibuka dengan membuat koneksi WebSocket ke:
wss://{namespace-address}/$hc/{path}?sb-hc-action=...[&sb-hc-id=...]&sb-hc-token=...
namespace-address Ini adalah nama domain yang sepenuhnya memenuhi syarat dari ruang nama Azure Relay yang menghosting Koneksi Hibrid, biasanya dari formulir {myname}.servicebus.windows.net.
Opsi parameter string kueri adalah sebagai berikut.
| Parameter | Wajib | Deskripsi |
|---|---|---|
sb-hc-action |
Ya | Untuk peran pendengar, parameter harus sb-hc-aksi=mendengarkan |
{path} |
Ya | Jalur ruang nama yang dikodekan URL dari Sambungan Hibrid yang telah dikonfigurasi sebelumnya untuk mendaftarkan pendengar ini. Ekspresi ini ditambahkan ke $hc/bagian jalur tetap. |
sb-hc-token |
Ya* | Pendengar harus menyediakan Token Akses Bersama Bus Layanan yang valid dan dikodekan URL untuk ruang nama atau Koneksi Hibrid yang menganugerahkan hak Dengar. |
sb-hc-id |
Tidak | ID opsional yang disediakan klien ini memungkinkan pelacakan diagnostik ujung-ke-ujung. |
Jika koneksi WebSocket gagal karena jalur Koneksi Hibrid tidak terdaftar, atau token yang tidak valid atau hilang, atau beberapa kesalahan lainnya, umpan balik kesalahan diberikan menggunakan model umpan balik status HTTP 1.1 reguler. Deskripsi status berisi id pelacakan kesalahan yang dapat dikomunikasikan kepada personel dukungan Azure:
| Kode | Kesalahan | Deskripsi |
|---|---|---|
| 404 | Tidak Ditemukan | Jalur Sambungan Hibrid tidak sah atau URL dasarnya salah bentuk. |
| 401 | Tidak diizinkan | Token keamanan hilang atau cacat atau tidak valid. |
| 403 | Terlarang | Token keamanan tidak sah untuk jalur ini untuk aksi ini. |
| 500 | Kesalahan Internal | Ada yang tidak beres dalam pelayanan. |
Jika koneksi WebSocket sengaja dimatikan oleh layanan setelah awalnya disiapkan, alasan untuk melakukannya dikomunikasikan menggunakan kode kesalahan protokol WebSocket yang sesuai bersama dengan pesan kesalahan deskriptif yang juga menyertakan ID pelacakan. Layanan tidak akan mematikan saluran kontrol tanpa mengalami kondisi kesalahan. Setiap pematian lancar dikontrol oleh klien.
| Status WS | Deskripsi |
|---|---|
| 1001 | Jalur Sambungan Hibrid telah dihapus atau dinonaktifkan. |
| 1008 | Token keamanan telah kedaluwarsa, oleh karena itu kebijakan otorisasi dilanggar. |
| 1011 | Ada yang tidak beres dalam pelayanan. |
Menerima jabat tangan
Pemberitahuan "terima" dikirim oleh layanan kepada pendengar melalui saluran kontrol yang ditetapkan sebelumnya sebagai pesan JSON dalam bingkai teks WebSocket. Tidak ada balasan untuk pesan ini.
Pesan berisi objek JSON bernama "terima", yang mendefinisikan properti berikut saat ini:
- alamat – string URL yang akan digunakan untuk membuat WebSocket ke layanan untuk menerima koneksi masuk.
- id – pengidentifikasi unik untuk koneksi ini. Jika ID disediakan oleh klien pengirim, id tersebut adalah nilai yang disediakan pengirim, jika tidak, itu adalah nilai yang dihasilkan sistem.
- connectHeaders - semua header HTTP yang telah diberikan ke titik akhir Relay oleh pengirim, yang juga menyertakan Sec-WebSocket-Protocol dan header 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 alamat yang disediakan dalam pesan JSON digunakan oleh pendengar untuk membuat WebSocket untuk menerima atau menolak soket pengirim.
Menerima soket
Untuk menerima, pendengar membuat koneksi WebSocket ke alamat yang disediakan.
Jika pesan "terima" membawa Sec-WebSocket-Protocol header, diharapkan pendengar hanya menerima WebSocket jika mendukung protokol tersebut. Selain itu, ini mengatur header sebagai WebSocket dibuat.
Hal yang sama berlaku untuk Sec-WebSocket-Extensions header. Jika kerangka kerja mendukung ekstensi, itu harus mengatur header ke balasan sisi server dari Sec-WebSocket-Extensions jabat tangan yang diperlukan untuk ekstensi.
URL harus digunakan apa adanya untuk membuat soket terima, tetapi berisi parameter berikut:
| Parameter | Wajib | Deskripsi |
|---|---|---|
sb-hc-action |
Ya | Untuk menerima soket, parameter harus sb-hc-action=accept |
{path} |
Ya | (lihat paragraf berikut) |
sb-hc-id |
Tidak | Lihat deskripsi id sebelumnya. |
{path} adalah jalur ruang nama yang dikodekan URL dari Koneksi Hibrid yang telah dikonfigurasi sebelumnya untuk mendaftarkan pendengar ini. Ekspresi ini ditambahkan ke $hc/bagian jalur tetap.
path Ekspresi dapat diperluas dengan akhiran dan ekspresi string kueri yang mengikuti nama terdaftar setelah garis miring yang memisahkan.
Parameter ini memungkinkan klien pengirim untuk meneruskan argumen pengiriman ke pendengar yang menerima ketika tidak mungkin menyertakan header HTTP. Harapannya adalah bahwa kerangka kerja pendengar menguraikan bagian jalur tetap dan nama terdaftar dari jalur dan membuat sisanya, mungkin tanpa argumen string kueri yang diasingkan oleh sb-, tersedia untuk aplikasi untuk memutuskan apakah akan menerima koneksi.
Untuk informasi selengkapnya, lihat bagian "Protokol Pengirim" berikut ini.
Jika ada kesalahan, layanan dapat membalas sebagai berikut:
| Kode | Kesalahan | Deskripsi |
|---|---|---|
| 403 | Terlarang | URL tidak valid. |
| 500 | Kesalahan Internal | Ada yang tidak beres dalam layanan |
Setelah koneksi dibuat, server akan mematikan WebSocket ketika WebSocket pengirim dimatikan, atau dengan status berikut:
| Status WS | Deskripsi |
|---|---|
| 1001 | Klien pengirim mematikan sambungan. |
| 1001 | Jalur Sambungan Hibrid telah dihapus atau dinonaktifkan. |
| 1008 | Token keamanan telah kedaluwarsa, oleh karena itu kebijakan otorisasi dilanggar. |
| 1011 | Ada yang tidak beres dalam pelayanan. |
Menolak soket
Menolak soket setelah memeriksa pesan accept memerlukan jabat tangan serupa sehingga kode status dan deskripsi status yang mengkomunikasikan alasan penolakan dapat mengalir kembali ke pengirim.
Pilihan desain protokol di sini adalah menggunakan jabat tangan WebSocket (yang dirancang untuk berakhir dalam keadaan kesalahan yang ditentukan) sehingga implementasi klien pendengar dapat terus mengandalkan klien WebSocket dan tidak perlu menggunakan klien HTTP tambahan yang telanjang.
Untuk menolak soket, klien mengambil URI alamat dari accept pesan dan menambahkan dua parameter string kueri ke dalamnya, sebagai berikut:
| Param | Wajib | Deskripsi |
|---|---|---|
| sb-hc-statusCode | Ya | Kode status HTTP numerik. |
| sb-hc-statusDeskripsi | Ya | Alasan yang mudah dibaca manusia untuk penolakan itu. |
URI yang dihasilkan kemudian digunakan untuk membuat koneksi WebSocket.
Ketika menyelesaikan dengan benar, jabat tangan ini sengaja gagal dengan kode kesalahan HTTP 410, karena tidak ada WebSocket yang telah ditetapkan. Jika ada yang tidak beres, kode berikut menjelaskan kesalahan:
| Kode | Kesalahan | Deskripsi |
|---|---|---|
| 403 | Terlarang | URL tidak valid. |
| 500 | Kesalahan Internal | Ada yang tidak beres dalam pelayanan. |
Pesan permintaan
requestPesan dikirim oleh layanan ke pendengar melalui saluran kontrol. Pesan yang sama juga dikirim melalui WebSocket pertemuan yang pernah didirikan.
request Terdiri dari dua bagian: header dan bingkai badan biner.
Jika tidak ada tubuh, bingkai tubuh dihilangkan. body Property boolean menunjukkan apakah ada badan dalam pesan permintaan.
Untuk permintaan dengan badan permintaan, strukturnya mungkin terlihat seperti ini:
----- Web Socket text frame ----
{
"request" :
{
"body" : true,
...
}
}
----- Web Socket binary frame ----
FEFEFEFEFEFEFEFEFEFEF...
----- Web Socket binary frame ----
FEFEFEFEFEFEFEFEFEFEF...
----- Web Socket binary frame -FIN
FEFEFEFEFEFEFEFEFEFEF...
----------------------------------
Pendengar HARUS menangani penerimaan file permintaan dibagi di beberapa bingkai biner (lihat fragmen WebSocket). Permintaan berakhir ketika bingkai biner dengan kumpulan bendera FIN telah diterima.
Untuk permintaan tanpa isi, hanya ada satu bingkai teks.
----- Web Socket text frame ----
{
"request" :
{
"body" : false,
...
}
}
----------------------------------
Konten JSON untuk request adalah sebagai berikut:
alamat - string URI. Ini adalah alamat pertemuan untuk digunakan untuk permintaan ini. Jika permintaan masuk lebih besar dari 64 kB, sisa pesan ini dibiarkan kosong, dan klien HARUS memulai jabat tangan pertemuan yang setara dengan
acceptoperasi yang dijelaskan di bawah ini. Layanan kemudian akan menempatkan lengkaprequestpada soket Web yang ditetapkan. Jika respons dapat diharapkan melebihi 64 kB, pendengar HARUS juga memulai jabat tangan pertemuan, dan kemudian mentransfer respons melalui soket Web yang ditetapkan.id – untai (karakter). Pengidentifikasi unik untuk permintaan ini.
requestHeaders - objek ini berisi semua header HTTP yang telah diberikan ke titik akhir oleh pengirim, dengan pengecualian informasi otorisasi seperti yang dijelaskan di atas, dan header yang secara ketat berhubungan dengan koneksi dengan gateway. Secara khusus, SEMUA header yang didefinisikan atau dicadangkan dalam RFC7230, kecuali
Via, dilucuti dan tidak diteruskan:Connection(RFC7230, Bagian 6.1)Content-Length(RFC7230, Bagian 3.3.2)Host(RFC7230, Bagian 5.4)TE(RFC7230, Bagian 4.3)Trailer(RFC7230, Bagian 4.4)Transfer-Encoding(RFC7230, Bagian 3.3.1)Upgrade(RFC7230, Bagian 6.7)Close(RFC7230, Bagian 8.1)
requestTarget –untai (karakter). Properti ini memiliki "Target Permintaan" (RFC7230, Bagian 5.3) dari permintaan. Ini termasuk bagian untai (karakter) kueri, yang dilucuti dari
sb-hc-semua parameter awalan.metoda - untai (karakter). Ini adalah metode permintaan, per RFC7231, Bagian 4.
CONNECTMetode ini TIDAK BOLEH digunakan.badan - boolean. Menunjukkan apakah satu atau beberapa bingkai badan biner mengikuti.
{
"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
}
}
Menanggapi permintaan
Penerima HARUS merespons. Kegagalan berulang untuk menanggapi permintaan sambil mempertahankan koneksi dapat mengakibatkan pendengar diblokir.
Tanggapan dapat dikirim dalam urutan apa pun, tetapi setiap permintaan harus direspons dalam waktu 60 detik atau pengiriman akan dilaporkan gagal. Tenggat waktu 60 detik dihitung sampai response bingkai telah diterima oleh layanan. Respons berkelanjutan dengan beberapa bingkai biner tidak dapat menganggur selama lebih dari 60 detik atau dihentikan.
Jika permintaan diterima melalui saluran kontrol, respons HARUS dikirim ke saluran kontrol dari tempat permintaan diterima atau harus dikirim melalui saluran pertemuan.
Responsnya adalah objek JSON bernama "respons". Aturan untuk menangani konten tubuh persis seperti dengan request pesan dan berdasarkan body properti.
- requestId – untai (karakter). DIPERLUKAN.
idNilai propertirequestpesan yang ditanggapi. - statusCode – nomor. DIPERLUKAN. kode status HTTP numerik yang menunjukkan hasil pemberitahuan. Semua kode status RFC7231, Bagian 6 diizinkan, kecuali untuk 502 "Gateway Buruk" dan 504 "Gateway Timeout".
- statusDeskripsi - untai (karakter). OPSIONAL. HTTP status-kode alasan frasa per RFC7230, Bagian 3.1.2
- responseHeaders - Header HTTP yang akan diatur dalam balasan HTTP eksternal.
Seperti halnya
requestheader yang ditentukan RFC7230 TIDAK BOLEH digunakan. - badan - boolean. Menunjukkan apakah bingkai tubuh biner mengikuti.
----- 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" }
----------------------------------
Merespons melalui pertemuan
Untuk tanggapan yang melebihi 64 kB, respons HARUS disampaikan melalui soket pertemuan. Juga, jika permintaan melebihi 64 kB, dan request satu-satunya berisi bidang alamat, soket pertemuan harus ditetapkan untuk mendapatkan request. Setelah soket pertemuan ditetapkan, tanggapan terhadap klien masing-masing dan permintaan berikutnya dari klien masing-masing HARUS dikirimkan melalui soket pertemuan sementara itu berlanjut.
address URL di dalam request harus digunakan apa adanya untuk membuat soket pertemuan, tetapi berisi parameter berikut:
| Parameter | Wajib | Deskripsi |
|---|---|---|
sb-hc-action |
Ya | Untuk menerima soket, parameter harus sb-hc-action=request |
Jika ada kesalahan, layanan dapat membalas sebagai berikut:
| Kode | Kesalahan | Deskripsi |
|---|---|---|
| 400 | Permintaan Tidak sah | Aksi atau URL tak dikenal tidak sah. |
| 403 | Terlarang | URL telah kedaluwarsa. |
| 500 | Kesalahan Internal | Ada yang tidak beres dalam layanan |
Setelah koneksi dibuat, server akan mematikan WebSocket ketika soket HTTP klien dimatikan, atau dengan status berikut:
| Status WS | Deskripsi |
|---|---|
| 1001 | Klien pengirim mematikan sambungan. |
| 1001 | Jalur Sambungan Hibrid telah dihapus atau dinonaktifkan. |
| 1008 | Token keamanan telah kedaluwarsa, oleh karena itu kebijakan otorisasi dilanggar. |
| 1011 | Ada yang tidak beres dalam pelayanan. |
Pembaruan token pendengar
Ketika token pendengar akan kedaluwarsa, token dapat menggantinya dengan mengirim pesan bingkai teks ke layanan melalui saluran kontrol yang ditetapkan. Pesan berisi objek JSON yang disebut renewToken, yang mendefinisikan properti berikut saat ini:
- token – token Akses Bersama Bus Layanan yang valid dan dikodekan URL untuk namespace atau Koneksi Hibrid yang menganugerahkan hak Dengar.
{
"renewToken": {
"token":
"SharedAccessSignature sr=http%3a%2f%2fcontoso.servicebus.windows.net%2fhyco%2f&sig=XXXXXXXXXX%3d&se=1471633754&skn=SasKeyName"
}
}
Jika validasi token gagal, akses ditolak, dan layanan cloud menutup saluran kontrol WebSocket dengan kesalahan. Jika tidak, tidak ada balasan.
| Status WS | Deskripsi |
|---|---|
| 1008 | Token keamanan telah kedaluwarsa, oleh karena itu kebijakan otorisasi dilanggar. |
Protokol sambung soket Web
Protokol pengirim secara efektif identik dengan cara pendengar didirikan. Tujuannya adalah transparansi maksimum untuk WebSocket ujung-ke-ujung. Alamat untuk disambungkan sama dengan pendengar, tetapi "tindakan" berbeda dan token memerlukan izin yang berbeda:
wss://{namespace-address}/$hc/{path}?sb-hc-action=...&sb-hc-id=...&sb-hc-token=...
Namespace-address adalah nama domain yang sepenuhnya memenuhi syarat dari namespace layanan Azure Relay yang menghosting Koneksi Hibrid, biasanya dari bentuk {myname}.servicebus.windows.net.
Permintaan dapat berisi header HTTP tambahan semaunya, termasuk yang ditentukan aplikasi. Semua header yang diberikan mengalir ke pendengar dan dapat ditemukan pada connectHeader objek pesan kontrol terima.
Opsi parameter untai (karakter) kueri adalah sebagai berikut:
| Param | Wajib diisi? | Deskripsi |
|---|---|---|
sb-hc-action |
Ya | Untuk peran pengirim, parameternya harus sb-hc-action=connect. |
{path} |
Ya | (lihat paragraf berikut) |
sb-hc-token |
Ya* | Pendengar harus menyediakan Token Akses Bersama Bus Layanan yang valid dan dikodekan URL untuk ruang nama atau Koneksi Hibrid yang menganugerahkan hak Kirim. |
sb-hc-id |
Tidak | ID opsional yang memungkinkan pelacakan diagnostik ujung-ke-ujung dan tersedia untuk pendengar selama jabat tangan terima. |
Ini {path} adalah jalur ruang nama yang dikodekan URL dari Koneksi Hibrid yang telah dikonfigurasi sebelumnya untuk mendaftarkan pendengar ini. Ekspresi path dapat diperluas dengan akhiran dan ekspresi untai (karakter) kueri untuk berkomunikasi lebih lanjut. Jika Koneksi Hibrid terdaftar di bawah jalur hyco, path ekspresi dapat hyco/suffix?param=value&... diikuti oleh parameter untai (karakter) kueri yang ditentukan di sini. Sebuah ekspresi lengkap kemudian mungkin sebagai berikut:
wss://{namespace-address}/$hc/hyco/suffix?param=value&sb-hc-action=...[&sb-hc-id=...&]sb-hc-token=...
path Ekspresi diteruskan ke pendengar di alamat URI yang terkandung dalam pesan kontrol "terima".
Jika koneksi WebSocket gagal karena jalur Koneksi Hibrid tidak terdaftar, token yang tidak valid atau hilang, atau beberapa kesalahan lainnya, umpan balik kesalahan diberikan menggunakan model umpan balik status HTTP 1.1 reguler. Deskripsi status berisi ID pelacakan kesalahan yang dapat dikomunikasikan kepada personel dukungan Azure:
| Kode | Kesalahan | Deskripsi |
|---|---|---|
| 404 | Tidak Ditemukan | Jalur Sambungan Hibrid tidak sah atau URL dasarnya salah bentuk. |
| 401 | Tidak diizinkan | Token keamanan hilang atau cacat atau tidak valid. |
| 403 | Terlarang | Token keamanan tidak sah untuk jalur ini dan untuk aksi ini. |
| 500 | Kesalahan Internal | Ada yang tidak beres dalam pelayanan. |
Jika koneksi WebSocket sengaja dimatikan oleh layanan setelah awalnya disiapkan, alasan untuk melakukannya dikomunikasikan menggunakan kode galat protokol WebSocket yang sesuai bersama dengan pesan kesalahan deskriptif yang juga menyertakan ID pelacakan.
| Status WS | Deskripsi |
|---|---|
| 1000 | Pendengar mematikan soket. |
| 1001 | Jalur Sambungan Hibrid telah dihapus atau dinonaktifkan. |
| 1008 | Token keamanan telah kedaluwarsa, sehingga kebijakan otorisasi dilanggar. |
| 1011 | Ada yang tidak beres dalam pelayanan. |
Protokol permintaan HTTP
Protokol permintaan HTTP memungkinkan permintaan HTTP semaunya, kecuali peningkatan protokol. Permintaan HTTP ditunjukkan pada alamat runtime reguler entitas, tanpa infiks $hc yang digunakan untuk koneksi hibrid klien WebSocket.
https://{namespace-address}/{path}?sb-hc-token=...
Namespace-address adalah nama domain yang sepenuhnya memenuhi syarat dari namespace layanan Azure Relay yang menghosting Koneksi Hibrid, biasanya dari bentuk {myname}.servicebus.windows.net.
Permintaan dapat berisi header HTTP tambahan semaunya, termasuk yang ditentukan aplikasi. Semua header yang disediakan, kecuali yang secara langsung didefinisikan dalam RFC7230 (lihat Meminta pesan) mengalir ke pendengar dan dapat ditemukan pada requestHeader objek pesan permintaan.
Opsi parameter untai (karakter) kueri adalah sebagai berikut:
| Param | Wajib diisi? | Deskripsi |
|---|---|---|
sb-hc-token |
Ya* | Pendengar harus menyediakan Token Akses Bersama Bus Layanan yang valid dan dikodekan URL untuk ruang nama atau Koneksi Hibrid yang menganugerahkan hak Kirim. |
Token juga dapat dibawa baik di ServiceBusAuthorization atau Authorization header HTTP. Token dapat dihilangkan jika Koneksi Hibrid dikonfigurasi untuk mengizinkan permintaan anonim.
Karena layanan secara efektif bertindak sebagai proksi, bahkan jika bukan sebagai proksi HTTP sejati, layanan ini menambahkan Via header atau membuat anotasi header yang ada Via sesuai dengan RFC7230, Bagian 5.7.1.
Layanan menambahkan nama host namespace Relay ke Via.
| Kode | Pesan | Deskripsi |
|---|---|---|
| 200 | OK | Permintaan telah ditangani oleh setidaknya satu pendengar. |
| 202 | Diterima | Permintaan telah diterima oleh setidaknya satu pendengar. |
Jika ada kesalahan, layanan dapat membalas sebagai berikut. Apakah respons berasal dari layanan atau dari pendengar dapat diidentifikasi melalui kehadiran Via header. Jika header ada, responsnya adalah dari pendengar.
| Kode | Kesalahan | Deskripsi |
|---|---|---|
| 404 | Tidak Ditemukan | Jalur Sambungan Hibrid tidak sah atau URL dasarnya salah bentuk. |
| 401 | Tidak diizinkan | Token keamanan hilang atau cacat atau tidak valid. |
| 403 | Terlarang | Token keamanan tidak sah untuk jalur ini dan untuk aksi ini. |
| 500 | Kesalahan Internal | Ada yang tidak beres dalam pelayanan. |
| 503 | Gateway buruk | Permintaan tidak dapat dialihkan ke pendengar mana pun. |
| 504 | Waktu Tunggu Gateway Habis | Permintaan dialihkan ke pendengar, tetapi pendengar tidak mengakui tanda terima dalam waktu yang diperlukan. |