Azure 轉送混合式連線通訊協定
Azure 轉送是 Azure 服務匯流排平台的重要功能支柱。 轉送的新「混合式連線」功能是以 HTTP 和 Websocket 為基礎的安全、開放式通訊協定演化。 它會取代其前身，也就是建置在專屬通訊協定基礎上、名為「BizTalk 服務」的功能。 整合到 Azure 應用程式服務的混合式連線會繼續如往常般運作。
「混合式連線」可在網路上的兩個應用程式之間，建立雙向、要求-回應和二進位串流通訊，以及簡單的資料包流程。 讓其中一方或雙方都能位於 NAT 或防火牆之後。
本文說明用戶端為了與擔任接聽程式和傳送者角色的用戶端連線而與混合式連線轉送進行的互動。 也會說明接聽程式如何接受新的連線和要求。
互動模型
混合式連線轉送會藉由在雙方均可探索到，並可由自己的網路觀點連線到的 Azure 雲端提供會合點，來讓雙方連線。 在本文件和其他文件、在 API 以及在 Azure 入口網站中，該會合點稱為「混合式連線」。 本文其餘地方將混合式連線服務端點稱為「服務」。
此服務允許轉送 Web Socket 連線及 HTTP(S) 要求和回應。
互動模型仰賴其他許多網路 API 所建立的專門用語。 有接聽程式會先指出已準備好可以處理連入連線，接著在連線抵達時予以接受。 而在另一端，用戶端會連線到接聽程式，並預期該連線會被接受，以便能夠建立雙向通訊路徑。 您可在大部分通訊端 API 中發現「連線」、「接聽」、「接受」等同義詞彙。
任何轉送的通訊模型中有任一方對服務端點進行輸出連線。 這會使「接聽程式」也成為口語使用中的「用戶端」，也可能導致其他術語多載。 因此，用於混合式連線的精確術語如下︰
連線兩端的程式稱為「用戶端」，因為兩者皆為服務的用戶端。 等候並接受連線的用戶端為「接聽程式」，或稱為擔任「接聽程式角色」。透過服務對接聽程式起始新連線的用戶端則稱為「傳送者」或擔任「傳送者角色」。
接聽程式互動
接聽程式會與服務進行五種互動；本文稍後的參考資料章節會詳述所有連線細節。
接聽、接受和要求訊息都是接收自服務。 接聽程式不會傳送 Renew 和 Ping 作業。
接聽訊息
為了讓服務知道接聽程式已準備好接受連線，它會建立輸出 WebSocket 連線。 連線交握會攜帶轉送命名空間中所設定的混合式連線名稱，以及對該名稱授予「接聽」權限的安全性權杖。
服務接受 WebSocket 時，註冊便已完成，所建立的 WebSocket 會保持運作，以作為用來啟用所有後續互動的「控制通道」。 在混合式連線中，服務最多允許 25 個並行接聽程式。 AppHooks 的配額有待決定。
對於混合式連線，如果有 2 個以上的作用中接聽程式，則會將連入連線隨機平衡分配給這些接聽程式；嘗試盡力達到公平分配。
接受訊息
當傳送者在服務上開啟新的連線時，服務就會選擇並通知混合式連線中的其中一個作用中接聽程式。 此通知會以 JSON 訊息的形式，透過開啟的控制通道傳送給接聽程式。 此訊息包含接聽程式為了接受連線所必須連線到之 WebSocket 端點的 URL。
此 URL 可以且必須由接聽程式直接使用，不得再行加工。 編碼資訊的有效期間很短，基本上就是傳送者願意等待兩端建立連線的時間。 採用的上限為 30 秒。 URL 只能用於進行一次成功的連線嘗試。 一旦建立了具有會合 URL 的 WebSocket 連線，此 WebSocket 上的所有後續活動就會由傳送者來回轉送。 但是服務不必再介入或解譯此行為。
要求訊息
除了 WebSocket 連線，接聽程式也可以從傳送者接收 HTTP 要求框架 (如果已在混合式連線上明確啟用這項功能)。
透過 HTTP 支援連結至混合式連線的接聽程式必須處理 request 舉動。 服務未來可能會將未處理 request 並因此在連線時造成重複逾時錯誤的接聽程式進行封鎖。
HTTP 框架標題中繼資料會轉譯為 JSON，以便接聽程式架構進行更簡單的處理，也是因為 HTTP 標題剖析程式庫比 JSON 剖析器更少見。 系統不會轉寄只對傳送者與轉送 HTTP 閘道之間關係有意義的 HTTP 中繼資料 (包括授權資訊)。 HTTP 要求主體會以二進位 WebSocket 框架的形式透明傳輸。
接聽程式可以使用對等的回應舉動來回應 HTTP 要求。
依預設，要求/回應流程會使用控制通道，但是可以視需要「升級」到相異的會合 WebSocket。 相異的 WebSocket 連線可改善每個用戶端對話的輸送量，但是會使接聽程式加重負擔而需要處理更多連線，輕量級用戶端可能不希望如此。
在控制通道上，要求和回應主體的大小均受限為最多 64 kB。 HTTP 標題中繼資料的總計受限於 32KB。 如果要求或回應超過該閾值，接聽程式必須使用相當於處理 Accept 的舉動來升級至會合 WebSocket。
對於要求，服務會決定是否要透過控制通道路由傳送要求。 這包括但不限於要求超過 64 kB (標題加上主體) 的情況，或者如果透過「區塊式」傳輸編碼傳送要求，服務就有理由預期要求會超過 64 kB 或讀取要求不是瞬間完成的。 如果服務選擇透過會合通道傳遞要求，它只會將會合位址傳遞給接聽程式。 然後，接聽程式必須建立會合 WebSocket，而服務會透過會合 WebSocket 立即傳遞完整的要求 (包括主體)。 回應也必須使用會合 WebSocket。
對於透過控制通道送達的要求，接聽程式會決定要透過控制通道還是透過會合通道進行回應。 服務必須包含會合位址，並透過控制通道路由傳送每個要求。 此位址只適用於從目前的要求升級。
如果接聽程式選擇升級，它會透過所建立的會合通訊端連線並立即傳遞回應。
建立會合 WebSocket 之後，接聽程式應該加以維護，以便進一步處理來自相同用戶端的要求和回應。 只要 HTTPS 通訊端與傳送者持續連線，服務就會維護 WebSocket，並將透過所維護的 WebSocket 路由傳送來自該傳送者的所有後續要求。 如果接聽程式選擇從它那一端捨棄會合 WebSocket ，則服務也會捨棄與傳送者的連線，不論後續要求是否可能已在進行中。
更新作業
必須用來註冊接聽程式和維護控制通道的安全性權杖，可能會在接聽程式作用期間過期。 權杖過期不會影響進行中的連線，但會導致服務在權杖過期當下或隨後立即捨棄控制通道。 「更新」作業是一則 JSON 訊息，接聽程式傳送此訊息以取代與控制通道相關聯的權杖，讓控制通道可以延長維持運作時間。
Ping 作業
如果控制通道長時間閒置，途中的媒介 (例如負載平衡器或 NAT) 可能會捨棄 TCP 連線。 「Ping」作業可避免該現象，其憑藉方法為在通道上傳送少量資料，提醒網路路由上的所有人此連線是為了讓通道保持運作，並同時測試接聽程式是否仍作用中。 如果 ping 失敗，則應將控制通道視為無法使用，接聽程式應重新連線。
傳送者互動
傳送者會與服務進行兩項互動：連線 Web Socket，或透過 HTTPS 傳送要求。 無法由傳送者角色透過 Web Socket 傳送要求。
連線作業
「連線」作業會在服務上開啟 WebSocket，提供混合式連線名稱和 (選擇性，但預設為必要) 會在查詢字串中授予「傳送」權限的安全性權杖。 服務接著會以先前所述方式和接聽程式互動，並讓接聽程式建立會與此 WebSocket 一起加入的會合連線。 WebSocket 獲得接受後，將會與已連線的接聽程式進行所有後續互動。
要求作業
對於尚未啟用此功能的混合式連線，傳送者可以將大致不受限的 HTTP 要求傳送至接聽程式。
除了內嵌於查詢字串或位於要求 HTTP 標題中的轉送存取權杖，轉送會完全透明呈現轉送位址上的所有 HTTP 作業和轉送位址路徑的所有尾碼，讓接聽程式得以完全控制端對端授權和 HTTP 擴充功能 (例如CORS)。
預設會開啟向轉送端點取得傳送者授權，但為選擇性。 混合式連線的擁有者可以選擇允許匿名傳送者。 服務會攔截、檢查和移除授權資訊，如下所示：
- 如果查詢字串包含
sb-hc-token運算式，此運算式「一律」會從查詢字串中移除。 如果已開啟轉送授權，將會進行其評估。 - 如果要求標題包含
ServiceBusAuthorization標題，則標題運算式「一律」會從標題集合中移除。 如果已開啟轉送授權，將會進行其評估。 - 唯有開啟轉送授權，要求標題包含
Authorization標題，而且先前的運算式都不存在，才會評估並移除此標題。 否則，一律會如往常般傳遞Authorization。
如果沒有任何作用中的接聽程式，則服務會傳回 502「錯誤的閘道」錯誤碼。 如果服務不想處理要求，則服務會在 60 秒之後傳回 504「閘道逾時」。
互動摘要
此互動模型的結果是傳送者用戶端會產生具有「乾淨」WebSocket 的交握，該通訊端連線到接聽程式，並且不需要再進行前序編碼或準備。 實際上，這可讓任何現有 WebSocket 用戶端實作輕易利用混合式連線服務，只需要對其 WebSocket 用戶端層提供正確建構的 URL。
接聽程式透過接受互動所取得的會合連線 WebSocket 也是乾淨的，您只需要另外進行點擷取動作即可遞交給任何現有 WebSocket 伺服器實作，此動作是為了區分其架構之區域網路接聽程式上的「接受」作業與混合式連線的遠端「接受」作業。
HTTP 要求/回應模型為傳送者提供大致不受限且具有選擇性授權層的 HTTP 通訊協定介面區。 接聽程式可使用帶有 HTTP 主體的二進位框架，取得預先剖析的 HTTP 要求標題區段，該區段可變回下游 HTTP 要求或依現狀處理。 回應會使用相同的格式。 透過可供所有傳送者共用的單一 Web Socket，可以處理與小於 64 KB 的要求和回應主體所做的互動。 使用會合模型，可以處理較大型的要求和回應。
通訊協定參考資料
本節描述上述通訊協定互動的詳細資料。
所有 WebSocket 連線都是在連接埠 443 上進行以作為從 HTTPS 1.1 (經常遭到某些 WebSocket 架構或 API 擷取) 開始的升級。 此處的描述不偏袒任何實作，不會建議您採用特定架構。
接聽程式通訊協定
接聽程式通訊協定是由兩個連線舉動和三項訊息作業所組成。
接聽程式控制通道連線
控制通道開啟時，會對下列位置建立 WebSocket 連線︰
wss://{namespace-address}/$hc/{path}?sb-hc-action=...[&sb-hc-id=...]&sb-hc-token=...
namespace-address 是裝載混合式連線之 Azure 轉送命名空間的完整網域名稱，其格式通常為 {myname}.servicebus.windows.net。
查詢字串參數選項如下。
| 參數 | 必要 | 描述: |
|---|---|---|
sb-hc-action |
Yes | 接聽程式角色的參數必須是 sb-hc-action=listen |
{path} |
Yes | 用來註冊此接聽程式之預先設定混合式連線的 URL 編碼命名空間路徑。 此運算式會附加至固定的 $hc/ 路徑部分。 |
sb-hc-token |
是* | 針對授予接聽權限的命名空間或混合式連線，接聽程式必須提供有效且以 URL 編碼的服務匯流排共用存取權杖。 |
sb-hc-id |
No | 用戶端提供的這個選擇性識別碼可讓您進行端對端診斷追蹤。 |
如果因為混合式連線路徑未註冊、權杖無效或遺失或是其他某些錯誤，導致 WebSocket 連線失敗，將使用一般的 HTTP 1.1 狀態回饋模型提供錯誤回饋。 狀態描述會包含錯誤追蹤識別碼，以供您告知 Azure 支援人員︰
| 代碼 | 錯誤 | 描述 |
|---|---|---|
| 404 | 找不到 | 混合式連線路徑無效或基底 URL 的格式不正確。 |
| 401 | 未經授權 | 安全性權杖遺失、格式不正確或無效。 |
| 403 | 禁止 | 對於此動作來說，此路徑的安全性權杖無效。 |
| 500 | 內部錯誤 | 服務發生錯誤。 |
如果 WebSocket 連線在最初設定過後遭到服務刻意關閉，服務會使用適當的 WebSocket 通訊協定錯誤碼以及同時含有追蹤識別碼的錯誤描述訊息告知您這麼做的原因。 服務不會在沒有發生錯誤狀況時關閉控制通道。 至於正常關機則為用戶端所為。
| WS 狀態 | 描述 |
|---|---|
| 1001 | 混合式連線路徑已遭到刪除或停用。 |
| 1008 | 安全性權杖已過期，因此違反授權原則。 |
| 1011 | 服務發生錯誤。 |
接受交握
服務會透過先前建立的控制通道，在 WebSocket 文字框中以 JSON 訊息的形式對接聽程式傳送「accept」通知。 沒有針對此訊息的任何回覆。
訊息中包含名為 "accept" 的 JSON 物件，其在此階段會定義下列屬性︰
- 位址 – 用來對服務建立 WebSocket 以接受連入連線的 URL 字串。
- 識別碼 – 此連線的唯一識別碼。 如果識別碼為傳送者用戶端所提供，則為傳送者提供的值，否則會是系統產生的值。
- 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" : "..."
}
}
}
接聽程式會使用 JSON 訊息中提供的位址 URL 來建立 WebSocket，以接受或拒絕傳送者通訊端。
接受通訊端
為了接受，接聽程式會對提供的位址建立 WebSocket 連線。
如果「accept」訊息執行 Sec-WebSocket-Protocol 標題，則接聽程式只接受支援該通訊協定的 WebSocket。 此外，會在建立 WebSocket 時設定標題。
對 Sec-WebSocket-Extensions 標題同樣適用。 如果架構支援擴充功能，其應將標題設定為擴充功能所需 Sec-WebSocket-Extensions 交握的伺服器端回覆。
URL 必須保持原樣以用來建立接受通訊端，但要包含下列參數︰
| 參數 | 必要 | 描述: |
|---|---|---|
sb-hc-action |
Yes | 若要接受通訊端，參數必須是 sb-hc-action=accept |
{path} |
Yes | (請參閱下列段落) |
sb-hc-id |
No | 請參閱先前的識別碼描述。 |
{path} 是用來註冊此接聽程式之預先設定混合式連線的 URL 編碼命名空間路徑。 此運算式會附加至固定的 $hc/ 路徑部分。
path 運算式可能會使用後置字元與接在分隔斜線後之已登錄名稱的查詢字串運算式進行擴充。
此參數可讓寄件者用戶端在不可能包括 HTTP 標題時，將分派引數傳遞至接受接聽程式。 預期為接聽程式架構會剖析固定的路徑部分和路徑中的已註冊名稱，並提供其餘部分，可能是不含前置詞為 sb- 的任何查詢字串引數，可供應用程式決定是否要接受連線。
如需詳細資訊，請參閱「寄件者通訊協定」一節。
如果發生錯誤，服務會有如下回覆：
| 代碼 | 錯誤 | 描述 |
|---|---|---|
| 403 | 禁止 | URL 無效。 |
| 500 | 內部錯誤 | 服務發生錯誤 |
連線建立後，伺服器會在傳送者 WebSocket 關閉時，或是具有下列狀態時關閉 WebSocket：
| WS 狀態 | 描述 |
|---|---|
| 1001 | 傳送者用戶端關閉連線。 |
| 1001 | 混合式連線路徑已遭到刪除或停用。 |
| 1008 | 安全性權杖已過期，因此違反授權原則。 |
| 1011 | 服務發生錯誤。 |
拒絕通訊端
在檢查 accept 訊息之後拒絕通訊端需要類似的交握，因此會對傳送者回傳可告知拒絕原因的狀態碼和狀態描述。
在這裡，通訊協定的設計選擇是使用 WebSocket 交握 (其設計是要以定義的錯誤狀態來結束)，以便讓接聽程式用戶端實作可以繼續依賴 WebSocket 用戶端，而不必另外運用裸機 HTTP 用戶端。
若要拒絕通訊端，用戶端會從 accept 訊息取得位址 URI，並對其附加兩個查詢字串參數，如下所示︰
| Param | 必要 | 描述 |
|---|---|---|
| sb-hc-statusCode | Yes | 數字型 HTTP 狀態碼。 |
| sb-hc-statusDescription | Yes | 使用者可以看懂的拒絕原因。 |
接著會使用產生的 URI 來建立 WebSocket 連線。
當正確完成時，因為尚未建立任何 WebSocket，此交握會刻意失敗，而其 HTTP 錯誤碼為 410。 如果發生錯誤，下列程式碼會描述錯誤：
| 代碼 | 錯誤 | 描述 |
|---|---|---|
| 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 內容如下所示：
address - URI 字串。 這是要用於此要求的會合位址。 如果傳入的要求大於 64 kB，則此訊息的其餘部分會保持空白，而且用戶端必須啟始相當於如下所述之
accept作業的會合交握。 服務會接著將完整request至於已建立的Web Socket 上。 如果可預期回應會超過 64 kB，則接聽程式也必須起始會合交握，然後透過所建立的 Web Socket 傳輸此回應。id – 字串。 此要求的唯一識別碼。
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-前置參數。method - 字串。 依據 RFC7231 第 4 節，這是要求的方法。 不得使用
CONNECT方法。body – 布林值。 指出一或多個二進位內容框架是否遵循。
{
"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 秒內回應每個要求，否則系統會將此傳遞回報為失敗。 在服務收到 response 框架前，系統會計算 60 秒的期限。 具有多個二進位框架的進行中回應不能閒置超過 60 秒，否則就會終止。
如果透過控制通道接收要求，則回應必須是在接收要求的控制通道上傳送，或者必須透過會合通道傳送。
回應是名為 "response" 的 JSON 物件。 用於處理主體內容與 request 訊息的規則完全一樣，並且以 body 屬性為基礎。
- requestId – 字串。 「必要」。 所回應之
request訊息的id屬性值。 - statusCode – 數字。 「必要」。 表示通知結果的數值 HTTP 狀態碼。 允許 RFC7231 第 6 節的所有狀態碼，但 502「錯誤的閘道」和 504「閘道逾時」除外。
- statusDescription - 字串。 選擇性。 依據 RFC7230 的 3.1.2 節，這是 HTTP status-code 的原因描述。
- responseHeaders – 要在外部 HTTP 回覆中設定的 HTTP 標題。
如同
request一樣，不得使用 RFC7230 定義的標題。 - body – 布林值。 指出二進位主體框架是否遵循。
----- 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 kB 的回應，則必須透過會合通訊端傳遞回應。 此外，如果要求超過 64 kB，而且 request 只包含位址欄位，則必須建立會合通訊端來取得 request。 一旦建立會合通訊端，對於個別用戶端的回應以及來自該個別用戶端的後續要求都必須透過現有的會合通訊端傳遞。
request 中的 address URL 必須保持原樣以用來建立會合通訊端，但要包含下列參數︰
| 參數 | 必要 | 描述: |
|---|---|---|
sb-hc-action |
Yes | 若要接受通訊端，參數必須是 sb-hc-action=request |
如果發生錯誤，服務會有如下回覆：
| 代碼 | 錯誤 | Description |
|---|---|---|
| 400 | 要求無效 | 無法辨識的動作或 URL 無效。 |
| 403 | 禁止 | URL 已到期。 |
| 500 | 內部錯誤 | 服務發生錯誤 |
建立連線後，伺服器會在用戶端的 HTTP 通訊端關閉時，或是具有下列狀態時關閉 WebSocket：
| WS 狀態 | 描述 |
|---|---|
| 1001 | 傳送者用戶端關閉連線。 |
| 1001 | 混合式連線路徑已遭到刪除或停用。 |
| 1008 | 安全性權杖已過期，因此違反授權原則。 |
| 1011 | 服務發生錯誤。 |
接聽程式權杖更新
接聽程式權杖即將到期時，透過所建立的控制通道對服務傳送文字框訊息即可加以取代。 訊息中包含名為 renewToken 的 JSON 物件，其在此階段會定義下列屬性︰
- 權杖 – 針對授予接聽權限的命名空間或混合式連線，有效且以 URL 編碼的服務匯流排共用存取權杖。
{
"renewToken": {
"token":
"SharedAccessSignature sr=http%3a%2f%2fcontoso.servicebus.windows.net%2fhyco%2f&sig=XXXXXXXXXX%3d&se=1471633754&skn=SasKeyName"
}
}
如果權杖驗證失敗，存取會遭到拒絕，而且雲端服務會關閉控制通道 Websocket 並產生錯誤。 否則不會有回覆。
| WS 狀態 | 描述 |
|---|---|
| 1008 | 安全性權杖已過期，因此違反授權原則。 |
Web Socket Connect 通訊協定
傳送者通訊協定的效果等同於接聽程式的建立方式。 其目標是讓端對端 WebSocket 擁有最大透明度。 要連線到的位址與接聽程式的情況相同，但其「動作」不同，而且權杖需要不同的權限︰
wss://{namespace-address}/$hc/{path}?sb-hc-action=...&sb-hc-id=...&sb-hc-token=...
namespace-address 是裝載混合式連線之 Azure 轉送命名空間的完整網域名稱，其格式通常為 {myname}.servicebus.windows.net。
要求會包含任意的額外 HTTP 標題，包括應用程式所定義的標題。 提供的所有標題都會流向接聽程式，而且可以在 accept 控制訊息的 connectHeader 物件中找到。
查詢字串參數選項如下：
| Param | 是必要的嗎？ | 描述 |
|---|---|---|
sb-hc-action |
Yes | 傳送者角色的參數必須是 sb-hc-action=connect。 |
{path} |
Yes | (請參閱下列段落) |
sb-hc-token |
是* | 針對授予傳送權限的命名空間或混合式連線，接聽程式必須提供有效且以 URL 編碼的服務匯流排共用存取權杖。 |
sb-hc-id |
No | 選擇性的識別碼，允許進行端對端診斷追蹤，並可供接聽程式在接受交握期間使用。 |
{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 運算式會傳遞至「accept」控制訊息所包含之位址 URI 中的接聽程式。
如果因為混合式連線路徑未註冊、權杖無效或遺失或是其他某些錯誤，導致 WebSocket 連線失敗，將使用一般的 HTTP 1.1 狀態回饋模型提供錯誤回饋。 狀態描述會包含錯誤追蹤識別碼，以供您告知 Azure 支援人員︰
| 代碼 | 錯誤 | 描述 |
|---|---|---|
| 404 | 找不到 | 混合式連線路徑無效或基底 URL 的格式不正確。 |
| 401 | 未經授權 | 安全性權杖遺失、格式不正確或無效。 |
| 403 | 禁止 | 對於此動作來說，此路徑的安全性權杖無效。 |
| 500 | 內部錯誤 | 服務發生錯誤。 |
如果 WebSocket 連線在最初設定過後遭到服務刻意關閉，服務會使用適當的 WebSocket 通訊協定錯誤碼以及同時含有追蹤識別碼的錯誤描述訊息告知您這麼做的原因。
| WS 狀態 | 描述 |
|---|---|
| 1000 | 接聽程式關閉通訊端。 |
| 1001 | 混合式連線路徑已遭到刪除或停用。 |
| 1008 | 安全性權杖已過期，因此違反授權原則。 |
| 1011 | 服務發生錯誤。 |
HTTP 要求通訊協定
HTTP 要求通訊協定允許任意的 HTTP 要求，但通訊協定升級除外。 HTTP 要求會指向於實體的一般執行階段位址，但沒有用於混合式連線 WebSocket 用戶端的 $hc 中置詞。
https://{namespace-address}/{path}?sb-hc-token=...
namespace-address 是裝載混合式連線之 Azure 轉送命名空間的完整網域名稱，其格式通常為 {myname}.servicebus.windows.net。
要求會包含任意的額外 HTTP 標題，包括應用程式所定義的標題。 提供的所有標題 (直接在 RFC7230 中定義的標題除外，請參閱要求訊息) 都會流向接聽程式，而且可以在 request 訊息的 requestHeader 物件上找到。
查詢字串參數選項如下：
| Param | 是必要的嗎？ | 描述 |
|---|---|---|
sb-hc-token |
是* | 針對授予傳送權限的命名空間或混合式連線，接聽程式必須提供有效且以 URL 編碼的服務匯流排共用存取權杖。 |
ServiceBusAuthorization 或 Authorization HTTP 標題中也可以帶有權杖。 如果混合式連線設定為允許匿名要求，則可以省略此權杖。
因為服務實際上作為 Proxy (即使不是作為真正的 HTTP Proxy)，它會新增 Via 標題或標註符合 RFC7230 的 5.7.1 節規範的現有 Via。
服務會將轉送命名空間主機名稱新增至 Via。
| 代碼 | 訊息 | 描述 |
|---|---|---|
| 200 | 確定 | 至少有一個接聽程式已處理要求。 |
| 202 | 已接受 | 至少有一個接聽程式已接受要求。 |
如果發生錯誤，服務會有如下回覆。 不論是來自服務或來自接聽程式的回應，都可以透過 Via 標題加以識別。 如果標題存在，則回應是來自接聽程式。
| 代碼 | 錯誤 | 描述 |
|---|---|---|
| 404 | 找不到 | 混合式連線路徑無效或基底 URL 的格式不正確。 |
| 401 | 未經授權 | 安全性權杖遺失、格式不正確或無效。 |
| 403 | 禁止 | 對於此動作來說，此路徑的安全性權杖無效。 |
| 500 | 內部錯誤 | 服務發生錯誤。 |
| 503 | 錯誤的閘道 | 無法將要求路由傳送至任何接聽程式。 |
| 504 | 閘道逾時 | 要求已路由傳送至接聽程式，但是接聽程式並未在所需的時間內認可回條。 |
下一步
意見反應
即將登場：在 2024 年，我們將逐步淘汰 GitHub 問題作為內容的意見反應機制，並將它取代為新的意見反應系統。 如需詳細資訊，請參閱：https://aka.ms/ContentUserFeedback。
提交並檢視相關的意見反應