匯入 WebSocket API

適用於：開發人員 |基本 |基本 v2 |標準 |標準 v2 |Premium |進階 v2

透過 API 管理的 WebSocket API 解決方案，API 發行者可以透過 Azure 入口網站、Azure CLI、Azure PowerShell 和其他 Azure 工具，在 API 管理中快速新增 WebSocket API。

注意

目前，此功能無法在工作區中使用。

您可以套用現有的存取控制原則，例如 JWT 驗證來保護 WebSocket API。 您也可以在 Azure 入口網站和開發人員入口網站中使用 API 測試主控台來測試 WebSocket API。 以現有的可檢視性功能為基礎，API 管理提供監視和疑難排解 WebSocket API 的計量和記錄。

在本文中，您將：

• 瞭解 WebSocket 傳遞流程。
• 將 WebSocket API 新增至 API 管理執行個體。
• 測試您的 WebSocket API。
• 檢視 WebSocket API 的計量和記錄。
• 了解 WebSocket API 的限制。

必要條件

• 現有的 API 管理執行個體。 若您還沒有執行個體，請加以建立。
• WebSocket API。
• Azure CLI

WebSocket 傳遞

API 管理支援 WebSocket 傳遞。

在 WebSocket 傳遞期間，用戶端應用程式會建立與 API 管理閘道的 WebSocket 連線，然後建立對應後端服務的連線。 接下來 API 管理會為 WebSocket 用戶端-伺服器訊息提供 Proxy。

1. 用戶端應用程式會將 WebSocket 交握要求傳送至 APIM 閘道來叫用 onHandshake 作業。
2. APIM 閘道會將 WebSocket 交握要求傳送至對應的後端服務。
3. 後端服務會升級 WebSocket 的連線。
4. APIM 閘道會將對應的連線升級至 WebSocket。
5. 連線配對建立之後，APIM 會在用戶端應用程式與後端服務之間來回代理訊息。
6. 用戶端應用程式會將訊息傳送至 APIM 閘道。
7. APIM 閘道會將訊息轉接至後端服務。
8. 後端服務會將訊息傳送至 APIM 閘道。
9. APIM 閘道會將訊息轉接至用戶端應用程式。
10. 當任一端中斷連線時，APIM 會終止對應的連線。

注意

用戶端和後端連線是由一對一對應所組成。

onHandshake 作業

根據 WebSocket 通訊協定，當用戶端應用程式嘗試建立與後端服務的 WebSocket 連線時，它會先傳送開啟交握要求。 API 管理中的每個 WebSocket API 都有 onHandshake 作業。 onHandshake 是不可變、無法移動且自動建立的系統作業。 onHandshake 作業可讓 API 發行者攔截這些交握要求，並將 API 管理原則套用其上。

新增 WebSocket API。

入口網站

1. 1. 在 Azure 入口網站中，瀏覽至您的 API 管理執行個體。

2. 在左側功能表中，選取 [API] > [+ 新增 API]。

3. 在 [定義新的 API] 底下，選取 WebSocket。

4. 在對話方塊中，選取 [完整]，然後完成必要的表單欄位。

   欄位	描述
   Display name	WebSocket API 的顯示名稱。
   名稱	WebSocket API 的原始名稱。 當您輸入顯示名稱時，會自動填入。
   WebSocket URL	Websocket 名稱的基底 URL。 例如：ws://example.com/your-socket-name
   URL 配置	接受預設值
   API URL 尾碼	新增 URL 尾碼，以在此 APIM 執行個體中識別此特定 API。 它在這個 APIM 執行個體中必須是唯一的。
   產品	建立 WebSocket API 與產品的關聯以將其發佈。
   閘道	建立 WebSocket API 與現有閘道的關聯。

5. 按一下 [建立]。

測試您的 WebSocket API。

1. 瀏覽至您的 WebSocket API。

2. 在您的 WebSocket API 中，選取 onHandshake 作業。

3. 選取 [測試] 索引標籤以存取測試主控台。

4. 或者，提供 WebSocket 交握所需的查詢字串參數。

   

5. 按一下 連線。

6. 在 [輸出] 中檢視連線狀態。

7. 在 [承載] 中輸入值。

8. 按一下 傳送。

9. 在 [輸出] 中檢視收到的訊息。

10. 重複上述步驟以測試不同的承載。

11. 測試完成時，請選取 [中斷連線]。

檢視計量和記錄

使用標準 API 管理和 Azure 監視器功能來監視 WebSocket API：

• 檢視 Azure 監視器中的 API 計量
• 選擇是否啟用診斷設定來收集和檢視 API 管理閘道記錄，其中包括 WebSocket API 作業

例如，下列螢幕擷取畫面顯示最近來自 ApiManagementGatewayLogs 資料表中程式碼為 101 的 WebSocket API 回應。 這些結果表示要求已成功從 TCP 切換到 WebSocket 通訊協定。

限制

以下是 API 管理中 WebSocket 支援的目前限制：

• 使用量層尚不支援 WebSocket API。
• WebSocket API 支援下列訊息的有效緩衝區類型：Close、BinaryFragment、BinaryMessage、UTF8Fragment 和 UTF8Message。
• 目前，設定標頭原則不支援變更 onHandshake 要求中的特定已知標頭，包括 Host 標頭。
• 在 TLS 與 WebSocket 後端進行交握期間，API 管理會驗證伺服器憑證是否受信任，以及其主體名稱是否符合主機名稱。 使用 HTTP API，API 管理會驗證憑證是否受信任，但不會驗證主機名稱和主體是否相符。

如需 WebSocket 連線限制，請參閱 API 管理限制。

不支援的原則

下列原則不受支援，而且無法套用至 onHandshake 作業：

• 模擬回應
• 從快取中取得
• 儲存至快取
• 允許跨網域呼叫
• CORS
• JSONP
• 設定要求方法
• 設定本文
• 將 XML 轉換成 JSON
• 將 JSON 轉換成 XML
• 使用 XSLT 轉換 XML
• 驗證內容
• 驗證參數
• 驗證標頭
• 驗證狀態碼

注意

如果您在較高層級的範圍套用原則 (例如全域或產品)，而且這些原則是透過原則來由 WebSocket API 所繼承，則會在執行階段略過這些原則。

相關主題

• API 匯入限制
• 匯入 OpenAPI 規格
• 匯入 SOAP API
• 匯入 SOAP API 並轉換為 REST
• 匯入 App Service API
• 匯入容器應用程式 API
• 匯入 WebSocket API
• 匯入 GraphQL API
• 匯入 GraphQL 結構描述並設定欄位解析器
• 匯入 Azure 函式應用程式
• 匯入 Azure 邏輯應用程式
• 匯入 Service Fabric 服務
• 匯入 Azure OpenAI API
• 匯入 OData API
• 匯入 SAP OData 中繼資料
• 匯入 gRPC API
• 編輯 API

下一步

轉換及保護已發佈的 API