匯入 WebSocket API

透過 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 的限制。

先決條件

WebSocket 傳遞

API 管理支援 WebSocket 傳遞。

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 管理原則套用其上。

onHandshake 畫面範例

新增 WebSocket API。

    1. Azure 入口網站中,瀏覽至您的 API 管理執行個體。
  1. 在左側功能表中,選取 [API] > [+ 新增 API]。

  2. 在 [定義新的 API] 底下,選取 WebSocket

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

    欄位 說明
    顯示名稱 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 與現有閘道的關聯。
  4. 按一下 [建立]。

測試您的 WebSocket API。

  1. 瀏覽至您的 WebSocket API。

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

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

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

    測試 API 範例

  5. 按一下 [ 連接]。

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

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

  8. 按一下 [ 傳送]。

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

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

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

檢視計量和記錄

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

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

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

WebSocket API 要求的查詢記錄

限制

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

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

不支援的原則

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

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

注意

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

後續步驟