如何搭配 Azure APIM 使用 Azure SignalR Service

Azure APIM 是跨所有環境適用於 API 的混合式多重雲端管理平台。 本文會示範如何使用 Azure APIM 和 Azure SignalR Service，將即時功能新增至您的應用程式。

建立資源

• 遵循快速入門：使用 ARM 範本來部署 Azure SignalR 以建立 SignalR Service 執行個體 ASRS1

• 請遵循快速入門：使用 ARM 範本來部署 Azure APIM 以建立 APIM 執行個體 APIM1

設定 API

限制

SignalR 用戶端有兩種類型的要求：

• 交涉要求：對 <APIM-URL>/client/negotiate/ 的 HTTP POST 要求
• 連線要求：對 <APIM-URL>/client/ 的要求，可能是 WebSocket 或 ServerSentEvent 或 LongPolling，視 SignalR 用戶端的傳輸類型而定

連線要求的類型會根據 SignalR 用戶端的傳輸類型而有所不同。 就目前而言，APIM 尚未支援具有相同尾碼的不同 API 類型。 由於這項限制，在使用 APIM 時，您的 SignalR 用戶端不支援從 WebSocket 傳輸類型後援到其他傳輸類型。 支援從 ServerSentEvent 到 LongPolling 的後援。 下列各節說明不同傳輸類型的詳細組態。

當用戶端與 WebSocket 傳輸連線時設定 API

本章節會說明當 SignalR 用戶端與 WebSocket 傳輸連線時，設定 APIM 的步驟。 當 SignalR 用戶端與 WebSocket 傳輸連線時，涉及三種類型的要求：

1. 交涉的 OPTIONS 預檢 HTTP 要求
2. 交涉的 POST HTTP 要求
3. 連線的 WebSocket 要求

讓我們從入口網站設定 APIM。

1. 在入口網站中移至 [API] 索引標籤以取得 APIM 執行個體 APIM1，選取 [新增 API]，然後選擇 [HTTP]，使用下列參數 [建立]：
   • 顯示名稱：SignalR negotiate
   • Web 服務 URL：https://<your-signalr-service-url>/client/negotiate/
   • API URL 尾碼：client/negotiate/
2. 選取已建立的 SignalR negotiate API，並使用下列設定 [儲存]：
   1. 在 [設計] 索引標籤中
      1. 選取 [新增作業]，並使用下列參數 [儲存]：
         • 顯示名稱：negotiate preflight
         • URL： OPTIONS /
      2. 選取 [新增作業]，並使用下列參數 [儲存]：
         • 顯示名稱：negotiate
         • URL： POST /
   2. 切換至 [設定] 索引標籤，然後取消核取 [所需的訂用帳戶] 以快速示範
3. 選取 [新增 API]，然後選擇 [WebSocket]、使用下列參數 [建立]：
   • 顯示名稱：SignalR connect
   • WebSocket URL：wss://<your-signalr-service-url>/client/
   • API URL 尾碼：client/
4. 選取已建立的 SignalR connect API，並使用下列設定 [儲存]：
   1. 切換至 [設定] 索引標籤，然後取消核取 [所需的訂用帳戶] 以快速示範

現在，APIM 已成功設定為支援具有 WebSocket 傳輸功能的 SignalR 用戶端。

當用戶端與 ServerSentEvents 或 LongPolling 傳輸連線時設定 API

本章節會說明當 SignalR 用戶端與 ServerSentEvents 或 LongPolling 傳輸類型連線時，設定 APIM 的步驟。 當 SignalR 用戶端與 ServerSentEvents 或 LongPolling 傳輸連線時，涉及五種類型的要求：

1. 交涉的 OPTIONS 預檢 HTTP 要求
2. 交涉的 POST HTTP 要求
3. 連線的 OPTIONS 預檢 HTTP 要求
4. 連線的 POST HTTP 要求
5. 連線的 GET HTTP 要求

現在讓我們從入口網站設定 APIM。

1. 在入口網站中移至 [API] 索引標籤以取得 APIM 執行個體 APIM1，選取 [新增 API]，然後選擇 [HTTP]，使用下列參數 [建立]：
   • 顯示名稱：SignalR
   • Web 服務 URL：https://<your-signalr-service-url>/client/
   • API URL 尾碼：client/
2. 選取已建立的 SignalR API，並使用下列設定 [儲存]：
   1. 在 [設計] 索引標籤中
      1. 選取 [新增作業]，並使用下列參數 [儲存]：
         • 顯示名稱：negotiate preflight
         • URL： OPTIONS /negotiate
      2. 選取 [新增作業]，並使用下列參數 [儲存]：
         • 顯示名稱：negotiate
         • URL： POST /negotiate
      3. 選取 [新增作業]，並使用下列參數 [儲存]：
         • 顯示名稱：connect preflight
         • URL： OPTIONS /
      4. 選取 [新增作業]，並使用下列參數 [儲存]：
         • 顯示名稱：connect
         • URL： POST /
      5. 選取 [新增作業]，並使用下列參數 [儲存]：
         • 顯示名稱：connect get
         • URL： GET /
      6. 選取新增的連線取得作業，然後編輯後端原則以停用 ServerSentEvents 的緩衝處理，請參閱這裡以取得更多詳細資料。

         <backend>
             <forward-request buffer-response="false" />
         </backend>
         

   2. 切換至 [設定] 索引標籤，然後取消核取 [所需的訂用帳戶] 以快速示範

現在，APIM 已成功設定為支援具有 ServerSentEvents 或 LongPolling 傳輸功能的 SignalR 用戶端。

執行聊天

現在，流量可以透過 APIM 到達 SignalR Service。 讓我們使用此聊天應用程式作為範例。 讓我們從在本機執行它開始。

原始 連接字串 只會出現在本文中，僅供示範之用。 在生產環境中，請一律保護您的存取金鑰。 使用 Azure 金鑰保存庫，使用 Microsoft Entra 識別碼安全地管理和輪替密鑰，並保護您的 連接字串，並使用 Microsoft Entra 識別符授權存取權。

• 首先，讓我們取得 ASRS1 的連接字串

  • 在 ASRS1 的 [連接字串] 索引標籤上
    • 用戶端端點：使用 APIM1的閘道 URL 輸入 URL，例如 https://apim1.azure-api.net。 這是使用反向 Proxy 時的連接字串產生器，下次回到此索引標籤時，不會保留此值。輸入值時，連接字串會附加 ClientEndpoint 區段。
    • 複製連接字串

• 複製 GitHub 存放庫 https://github.com/aspnet/AzureSignalR-samples

• 移至 samples/Chatroom 資料夾：

• 設定複製的連接字串並在本機執行應用程式，您可以看到 ConnectionString 中有一個 ClientEndpoint 區段。

  cd samples/Chatroom
  dotnet restore
  dotnet user-secrets set Azure:SignalR:ConnectionString "<copied-connection-string-with-client-endpoint>"
  dotnet run
  

• 設定用戶端的傳輸類型

  在資料夾 wwwroot 下開啟 index.html，並在建立 connection 時尋找程式碼，將其更新以指定傳輸類型。

  例如，若要指定使用伺服器傳送事件或長時間輪詢的連線，請將程式碼更新為：

  const connection = new signalR.HubConnectionBuilder()
    .withUrl(
      "/chat",
      signalR.HttpTransportType.ServerSentEvents |
        signalR.HttpTransportType.LongPolling
    )
    .build();
  

  若要指定使用 WebSockets 的連線，請將程式碼更新為：

  const connection = new signalR.HubConnectionBuilder()
    .withUrl("/chat", signalR.HttpTransportType.WebSockets)
    .build();
  

• 從瀏覽器開啟 http://localhost:5000 並使用 F12 來檢視網路追蹤，您可以看到連線是透過 APIM1 來建立的

下一步

現在，您已使用 Azure SignalR 成功將即時功能新增至 APIM。 深入瞭解 SignalR Service。