Azure 轉送混合式連線通訊協定
Azure 轉播是Azure 服務匯流排平臺的重要功能要素之一。 轉送的新 混合式連線 功能是以 HTTP 和 WebSocket 為基礎的安全開放通訊協定演進。 它取代了前者，同樣命名 的BizTalk 服務 功能，其建置在專屬通訊協定基礎上。 混合式連線整合至Azure App 服務會繼續依目前運作。
混合式連線可啟用雙向、要求-回應和二進位資料流程通訊，以及兩個網路應用程式之間的簡單資料包流程。 或雙方都可以位於 NAT 或防火牆後方。
本文說明與混合式連線轉送的用戶端互動，以連接接聽程式和傳送者角色中的用戶端。 它也描述接聽程式如何接受新的連線和要求。
互動模型
混合式連線轉送會藉由在 Azure 雲端中提供會合點來連接兩方，雙方可以從自己的網路觀點探索和連線。 這個和其他檔中的交集點稱為「混合式連線」、API，以及Azure 入口網站。 混合式連線服務端點稱為本文其餘部分的「服務」。
服務允許轉送 Web 通訊端連線和 HTTP（S） 要求和回應。
互動模型依賴許多其他網路 API 所建立的命名法。 有一個接聽程式會先指出處理連入連線的整備程度，並在抵達時接受它們。 另一方面，用戶端會連線到接聽程式，預期會接受該連線來建立雙向通訊路徑。 「連線」、「接聽」和「接受」是您在大部分通訊端 API 中找到的相同詞彙。
任何轉接的通訊模型都有任何一方對服務端點進行輸出連線。 這會使「接聽程式」在口語使用中也是「用戶端」，而且也可能造成其他術語超載。 因此，用於混合式連線的精確術語如下：
連線兩端的程式稱為「用戶端」，因為它們是服務的用戶端。 等候並接受連線的用戶端是「接聽程式」，或稱為「接聽程式」角色。透過服務起始對接聽程式的新連線的用戶端稱為「傳送者」，或位於「傳送者」角色中。
接聽程式互動
接聽程式與服務有五個互動：本文章稍後會在參考一節中說明所有線路詳細資料。
接聽、接受和要求訊息會從服務接收。 接聽程式會傳送更新和 Ping 作業。
接聽訊息
若要指出接聽程式已準備好接受連線的服務，它會建立輸出 WebSocket 連線。 連線交握會攜帶在轉送命名空間上設定的混合式連線名稱，以及授與該名稱上「接聽」許可權的安全性權杖。
當服務接受 WebSocket 時，註冊就會完成，且已建立的 WebSocket 會保持運作為啟用所有後續互動的「控制通道」。 服務允許最多 25 個並行接聽程式進行一個混合式連線。 要決定 AppHook 的配額。
針對混合式連線，如果有兩個以上的使用中接聽程式，傳入的連線會以隨機順序平衡;會以最佳方式嘗試公平散發。
接受訊息
當傳送者在服務上開啟新的連線時，服務會選擇並通知混合式連線ion 上的其中一個作用中接聽程式。 此通知會以 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 標頭中繼資料限制為總計 32 kB。 如果要求或回應超過該閾值，接聽程式必須使用相當於處理 Accept 的 手勢升級至會合 WebSocket。
對於要求，服務會決定是否要透過控制通道路由要求。 這包括，但可能不限於要求完全超過 64 kB（標頭加上本文）的情況，或如果要求是以 「區塊化」傳輸編碼 傳送，且服務有理由預期要求超過 64 kB 或讀取要求並非瞬間。 如果服務選擇透過交集傳遞要求，它只會將會合位址傳遞至接聽程式。 接聽程式接著必須建立會合 WebSocket，而服務會立即傳遞完整要求，包括會合 WebSocket 上的主體。 回應 MUST 也會使用會合 WebSocket。
對於透過控制通道抵達的要求，接聽程式會決定是否要透過控制通道或透過交集回應。 服務必須包含會合位址，且每個要求都透過控制通道路由傳送。 此位址僅適用于從目前要求升級。
如果接聽程式選擇升級，它會連線並立即透過已建立的會合通訊端傳遞回應。
建立會合 WebSocket 之後，接聽程式應該會維護它，以便進一步處理來自相同用戶端的要求和回應。 只要與寄件者的 HTTPS 通訊端連線持續存在，服務就會維護 WebSocket，並且會透過維護的 WebSocket 路由傳送來自該寄件者的所有後續要求。 如果接聽程式選擇從其端卸載會合 WebSocket，服務也會卸載與傳送者的連線，而不論後續的要求是否已經在進行中。
更新作業
必須用來註冊接聽程式並維護控制通道的安全性權杖，在接聽程式作用中時可能會過期。 權杖到期不會影響進行中的連線，但它確實會導致服務在到期時或不久卸載控制通道。 「更新」作業是一則 JSON 訊息，接聽程式可以傳送以取代與控制通道相關聯的權杖，以便長時間維護控制通道。
Ping 作業
如果控制通道長時間處於閒置狀態，則傳輸方可能會卸載 TCP 連線，例如負載平衡器或 NAT。 「ping」作業可避免在通道上傳送少量資料，以提醒網路路由上的每個人都知道連線應該運作，而且也會做為接聽程式的「即時」測試。 如果 Ping 失敗，控制項通道應該視為無法使用，而接聽程式應該重新連線。
寄件者互動
傳送者與服務有兩個互動：它會連線 Web 通訊端，或透過 HTTPS 傳送要求。 無法從傳送者角色透過 Web 通訊端傳送要求。
連線作業
「連線」作業會在服務上開啟 WebSocket，提供混合式連線的名稱，以及安全性權杖在查詢字串中授與「傳送」許可權。 服務接著會以先前所述的方式與接聽程式互動，接聽程式會建立與這個 WebSocket 聯結的會合連線。 接受 WebSocket 之後，該 WebSocket 上的所有進一步互動都會與已連線的接聽程式搭配使用。
要求作業
針對已啟用此功能的混合式連線，傳送者可以將基本上不受限制的 HTTP 要求傳送給接聽程式。
除了內嵌在查詢字串或要求 HTTP 標頭中的轉送存取權杖之外，轉送對轉送位址上的所有 HTTP 作業和轉送位址路徑的所有尾碼完全透明，讓接聽程式完全控制端對端授權，甚至是 CORS 等 HTTP 擴充功能。
轉送端點的寄件者授權預設為開啟，但為選擇性。 混合式連線ion 的擁有者可以選擇允許匿名寄件者。 服務會攔截、檢查及移除授權資訊，如下所示：
- 如果查詢字串包含
sb-hc-token運算式，則一律會從查詢字串中移除運算式。 如果開啟轉送授權，則會評估它。 - 如果要求標頭包含
ServiceBusAuthorization標頭，標頭運算式一律會從標頭集合中移除。 如果開啟轉送授權，則會評估它。 - 只有開啟轉送授權，而且如果要求標頭包含
Authorization標頭，而且先前的運算式都不存在，則會評估並移除標頭。 否則，Authorization一律會依目前方式傳遞 。
如果沒有作用中的接聽程式，服務會傳回 502「不正確的閘道」錯誤碼。 如果服務似乎未處理要求，服務會在 60 秒後傳回 504「閘道逾時」。
互動摘要
此互動模型的結果是，傳送者用戶端會從與「乾淨」WebSocket 的交握中取出，而該 WebSocket 會連線到接聽程式，而且不需要進一步的前置詞或準備。 此模型可讓任何現有的 WebSocket 用戶端實作，藉由將正確建構的 URL 提供給其 WebSocket 用戶端層，以輕鬆利用混合式連線服務。
接聽程式透過接受互動取得的交集連線 WebSocket 也是簡潔的，而且可以交給任何現有的 WebSocket 伺服器實作，其基本抽象概念可區分其架構區域網路接聽程式和混合式連線遠端「接受」作業上的「接受」作業。
HTTP 要求/回應模型會為傳送者提供基本不受限制的 HTTP 通訊協定介面區與選擇性授權層。 接聽程式會取得預先剖析的 HTTP 要求標頭區段，該區段可以轉回下游 HTTP 要求，或依往常處理，二進位框架會攜帶 HTTP 主體。 回應會使用相同的格式。 透過針對所有寄件者共用的單一 Web 通訊端，可以處理與少於 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是裝載混合式連線ion 之 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 | 找不到 | 混合式連線ion 路徑無效，或基底 URL 格式不正確。 |
| 401 | 未經授權 | 安全性權杖遺失或格式不正確或無效。 |
| 403 | 禁止 | 此動作的安全性權杖對這個路徑無效。 |
| 500 | 內部錯誤 | 服務發生錯誤。 |
如果最初設定 WebSocket 連線之後，服務會刻意關閉，則這樣做的原因會使用適當的 WebSocket 通訊協定錯誤碼以及同時包含追蹤識別碼的描述性錯誤訊息進行通訊。 服務不會關閉控制通道，而不會遇到錯誤狀況。 任何清除關機都是由用戶端控制。
| WS 狀態 | 描述 |
|---|---|
| 1001 | 混合式連線路徑已刪除或停用。 |
| 1008 | 安全性權杖已過期，因此違反授權原則。 |
| 1011 | 服務發生錯誤。 |
接受交握
服務會透過先前建立的控制通道，將「接受」通知傳送給接聽程式，做為 WebSocket 文字圖文框中的 JSON 訊息。 此訊息沒有回復。
訊息包含名為 「accept」 的 JSON 物件，此物件目前會定義下列屬性：
- address – 要用來建立 WebSocket 至服務的 URL 字串，以接受連入連線。
- id – 此連線的唯一識別碼。 如果識別碼是由傳送者用戶端所提供，則為傳送者提供的值，否則為系統產生的值。
- 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 連線。
如果「接受」訊息攜帶 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 連線。
正確完成時，此交握會刻意失敗，並出現 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 內容如下所示：
address - URI 字串。 這是用於此要求的會合位址。 如果連入要求大於 64 kB，則此訊息的其餘部分會保留空白，而用戶端 MUST 起始與下面所述的作業相等
accept的交握。 服務接著會將完成request放在已建立的 Web 通訊端上。 如果回應預期超過 64 kB，接聽程式「必須」也會起始會合交握，然後透過已建立的 Web 通訊端傳輸回應。id – 字串。 此要求的唯一識別碼。
requestHeaders – 此物件包含傳送者提供給端點的所有 HTTP 標頭，但上述授權資訊 除外，以及嚴格與閘道連線相關的標頭。 具體而言，在 RFC7230 中 定義或保留的所有標頭，但 除外
Via，會移除且未轉送：Connection（第6.1條RFC7230）Content-Length（第3.3.2條RFC7230）Host（第5.4條RFC7230）TE（第4.3條RFC7230）Trailer（第4.4條RFC7230）Transfer-Encoding（第3.3.1條RFC7230）Upgrade（第6.7條RFC7230）Close（第8.1條RFC7230）
requestTarget – string。 此屬性保留要求的 「要求目標」（RFC7230第 5.3 節）。 它包含查詢字串部分，其會移除 ALL
sb-hc-前置詞參數。方法 - 字串。 這是要求的方法，每個 RFC7231第 4 節。
CONNECT必須使用方法 MUST NOT。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 – 字串。 必填。
id正在回應之request訊息的 屬性值。 - statusCode – number。 必填。 表示通知結果的數值 HTTP 狀態碼。 除了 502「不正確的閘道」和 504「閘道逾時 」 以外， 允許RFC7231區段 6 的所有狀態碼 。
- statusDescription - string。 選擇性。 每個 RFC7230的 HTTP 狀態碼原因片語，第 3.1.2 節
- responseHeaders – 要設定于外部 HTTP 回復中的 HTTP 標頭。
如同
request，RFC7230定義的標頭不可使用。 - body – 布林值。 指出二進位本文框架是否跟隨（s）。
----- 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 。 建立會合通訊端之後，對個別用戶端的回應和來自該個別用戶端的後續要求必須在保存時透過交集通訊端傳遞。
address中的 request URL 必須如常使用，才能建立會合通訊端，但包含下列參數：
| 參數 | 必要 | 描述: |
|---|---|---|
sb-hc-action |
Yes | 若要接受通訊端，參數必須是 sb-hc-action=request |
如果發生錯誤，服務可以回復，如下所示：
| 代碼 | 錯誤 | Description |
|---|---|---|
| 400 | 不正確要求 | 無法辨識的動作或 URL 無效。 |
| 403 | 禁止 | URL 已過期。 |
| 500 | 內部錯誤 | 服務發生錯誤 |
建立連線之後，當用戶端的 HTTP 通訊端關閉或具有下列狀態時，伺服器會關閉 WebSocket：
| WS 狀態 | 描述 |
|---|---|
| 1001 | 傳送者用戶端會關閉連線。 |
| 1001 | 混合式連線路徑已刪除或停用。 |
| 1008 | 安全性權杖已過期，因此違反授權原則。 |
| 1011 | 服務發生錯誤。 |
接聽程式權杖更新
當接聽程式權杖即將到期時，可以透過已建立的控制通道將文字圖文框訊息傳送至服務來取代它。 訊息包含名為 renewToken 的 JSON 物件，此物件目前會定義下列屬性：
- token – 命名空間或混合 式連線授與接聽 權的有效 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 通訊端連線通訊協定
傳送者通訊協定實際上與建立接聽程式的方式相同。 目標是端對端 WebSocket 的最大透明度。 要連線的位址與接聽程式相同，但「動作」不同，權杖需要不同的許可權：
wss://{namespace-address}/$hc/{path}?sb-hc-action=...&sb-hc-id=...&sb-hc-token=...
命名空間 位址 是裝載混合式連線之 Azure 轉送命名空間的完整功能變數名稱，通常是 格式 {myname}.servicebus.windows.net 。
要求可以包含任意額外的 HTTP 標頭，包括應用程式定義的標頭。 所有提供的標頭都會流向接聽程式，而且可以在接受 控制項訊息的物件 上 connectHeader 找到。
查詢字串參數選項如下所示：
| Param | 是必要的嗎? | 描述 |
|---|---|---|
sb-hc-action |
Yes | 對於傳送者角色，參數必須是 sb-hc-action=connect 。 |
{path} |
Yes | （請參閱下列段落） |
sb-hc-token |
是* | 接聽程式必須針對授 與傳送 許可權的命名空間或混合式連線，提供有效的 URL 編碼服務匯流排共用存取權杖。 |
sb-hc-id |
No | 選擇性識別碼，可啟用端對端診斷追蹤，並在接受交握期間提供給接聽程式使用。 |
{path}是預先設定混合式連線的 URL 編碼命名空間路徑，要在其中註冊此接聽程式。 運算式 path 可以使用尾碼和查詢字串運算式來擴充，以便進一步通訊。 如果在路徑 hycopath 下註冊混合式連線，則運算式後面可以 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 連線因為未註冊混合式連線ion 路徑、無效或遺失權杖或其他錯誤而失敗，則會使用一般 HTTP 1.1 狀態意見反應模型來提供錯誤意見反應。 狀態原因包含可以與Azure 支援人員通訊的錯誤追蹤識別碼：
| 代碼 | 錯誤 | 描述 |
|---|---|---|
| 404 | 找不到 | 混合式連線ion 路徑無效，或基底 URL 格式不正確。 |
| 401 | 未經授權 | 安全性權杖遺失或格式不正確或無效。 |
| 403 | 禁止 | 此路徑和此動作的安全性權杖無效。 |
| 500 | 內部錯誤 | 服務發生錯誤。 |
如果一開始設定 WebSocket 連線之後，服務會刻意關閉它，則這樣做的原因會使用適當的 WebSocket 通訊協定錯誤碼以及同時包含追蹤識別碼的描述性錯誤訊息進行通訊。
| WS 狀態 | 描述 |
|---|---|
| 1000 | 接聽程式關閉通訊端。 |
| 1001 | 混合式連線路徑已刪除或停用。 |
| 1008 | 安全性權杖已過期，因此違反授權原則。 |
| 1011 | 服務發生錯誤。 |
HTTP 要求通訊協定
HTTP 要求通訊協定允許任意 HTTP 要求，但通訊協定升級除外。 HTTP 要求會指向實體的一般執行時間位址，而不需要用於混合式連線 WebSocket 用戶端的$hc infix。
https://{namespace-address}/{path}?sb-hc-token=...
命名空間 位址 是裝載混合式連線之 Azure 轉送命名空間的完整功能變數名稱，通常是 格式 {myname}.servicebus.windows.net 。
要求可以包含任意額外的 HTTP 標頭，包括應用程式定義的標頭。 所有提供的標頭，除了直接定義于 RFC7230 （請參閱 要求訊息 ） 流程到接聽程式，而且可以在要求 訊息的物件 上 requestHeader 找到。
查詢字串參數選項如下所示：
| Param | 是必要的嗎? | 描述 |
|---|---|---|
sb-hc-token |
是* | 接聽程式必須針對授 與傳送 許可權的命名空間或混合式連線，提供有效的 URL 編碼服務匯流排共用存取權杖。 |
權杖也可以包含在 或 Authorization HTTP 標頭中 ServiceBusAuthorization 。 如果混合式連線設定為允許匿名要求，則可以省略權杖。
因為服務實際上會作為 Proxy，即使不是真正的 HTTP Proxy，它也會新增 Via 標頭或標注與 RFC7230第 5.7.1 節 5.7.1 相容的現有 Via 標頭。
服務會將轉寄命名空間主機名稱新增至 Via 。
| 代碼 | 訊息 | 描述 |
|---|---|---|
| 200 | 確定 | 要求已由至少一個接聽程式處理。 |
| 202 | 已接受 | 至少一個接聽程式已接受要求。 |
如果發生錯誤，服務可以回復，如下所示。 回應是否來自服務或接聽程式，可透過標頭是否存在 Via 來識別。 如果標頭存在，回應會來自接聽程式。
| 代碼 | 錯誤 | 描述 |
|---|---|---|
| 404 | 找不到 | 混合式連線ion 路徑無效，或基底 URL 格式不正確。 |
| 401 | 未經授權 | 安全性權杖遺失或格式不正確或無效。 |
| 403 | 禁止 | 此路徑和此動作的安全性權杖無效。 |
| 500 | 內部錯誤 | 服務發生錯誤。 |
| 503 | 錯誤的閘道 | 無法將要求路由傳送至任何接聽程式。 |
| 504 | 閘道逾時 | 要求已路由傳送至接聽程式，但接聽程式未在必要時間內確認收到。 |