匯入 WebSocket API

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

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

注意

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

WebSocket API 可以藉由將 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 交握要求傳送至閘道，叫用 onHandshake 作業
2. API 管理 閘道會套用已設定的原則，並將 WebSocket 交握要求傳送至對應的後端服務。
3. 後端服務會升級 WebSocket 的連線。
4. 閘道會將對應的連線升級至 WebSocket。
5. 建立連線配對之後，API 管理 用戶端應用程式與後端服務之間來回訊息代理程式。
6. 用戶端應用程式會將訊息傳送至閘道。
7. 閘道會將訊息轉送至後端服務。
8. 後端服務會將訊息傳送至閘道。
9. 閘道會將訊息轉送至用戶端應用程式。
10. 當任一端中斷連線時，API 管理 終止對應的連線。

注意

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

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