Azure SignalR Service 中的連接字串

連接字串包含如何連線至 Azure SignalR Service 的資訊。 在本文中，您會了解連接字串的基本概念，以及如何在應用程式中設定連接字串。

連接字串是什麼

當應用程式需要連線到 Azure SignalR Service 時，需要下列資訊：

• Azure SignalR Service 執行個體的 HTTP 端點
• 向服務端點進行驗證的方式

連接字串包含這類資訊。

連接字串是什麼樣子

連接字串是由分號 (;) 分隔的一系列金鑰/值組。 字串會使用等號 (=) 來連接每個金鑰及其值。 索引鍵不區分大小寫。

一般連接字串看起來可能像下列範例：

Endpoint=https://<resource_name>.service.signalr.net;AccessKey=<access_key>;Version=1.0;

連接字串包含：

• Endpoint=https://<resource_name>.service.signalr.net：是資源的端點 URL。
• AccessKey=<access_key>：向服務進行驗證的金鑰。 當您在連接字串中指定存取金鑰時，Azure SignalR Service SDK 會將其用來產生服務所驗證的權杖。
• Version：連接字串的版本。 預設值是 1.0。

下表列出連接字串中索引鍵/值組的所有有效名稱。

使用 AccessKey

當 AuthType 設定為 null 時，服務會使用本機驗證方法。

使用 Microsoft Entra ID

當 AuthType 設定為 azure、azure.app 或 azure.msi 時，服務會使用 Microsoft Entra 驗證方法。

服務會使用不同的 TokenCredential 值來產生 Microsoft Entra 權杖，視您提供的參數而定：

• type=azure

  • 此服務是使用 DefaultAzureCredential：

    Endpoint=xxx;AuthType=azure
    

• type=azure.msi

  • 如果連接字串使用 clientId，則服務會使用使用者指派的受控識別 (ManagedIdentityCredential(clientId))：

    Endpoint=xxx;AuthType=azure.msi;ClientId=<client_id>
    

  • 服務會使用系統指派的受控識別 (ManagedIdentityCredential())：

    Endpoint=xxx;AuthType=azure.msi;
    

• type=azure.app

  clientId 和 tenantId 都必須搭配服務主體使用 Microsoft Entra 應用程式。

  • 如果連接字串使用 clientSecret，則服務會使用 ClientSecretCredential(clientId, tenantId, clientSecret)

    Endpoint=xxx;AuthType=azure.msi;ClientId=<client_id>;clientSecret=<client_secret>>
    

  • 如果連接字串使用 clientCertPath，則服務會使用 ClientCertificateCredential(clientId, tenantId, clientCertPath)：

    Endpoint=xxx;AuthType=azure.msi;ClientId=<client_id>;TenantId=<tenant_id>;clientCertPath=</path/to/cert>
    

如何取得連接字串

您可以使用 Azure 入口網站或 Azure CLI 來取得連接字串。

Azure 入口網站

在 Azure 入口網站中，開啟您的 Azure SignalR Service 資源。 [金鑰] 索引標籤會顯示兩個連接字串 (主要和次要)，格式如下：

Endpoint=https://<resource_name>.service.signalr.net;AccessKey=<access_key>;Version=1.0;

Azure CLI

az signalr key list -g <resource_group> -n <resource_name>

使用 Microsoft Entra 應用程式進行連線

您可以使用 Microsoft Entra 應用程式來連線到您的 Azure SignalR Service 執行個體。 如果應用程式有權限可存取 Azure SignalR Service，就不需要存取金鑰。

若要使用 Microsoft Entra 驗證，您必須從連接字串中移除 AccessKey，並新增 AuthType=azure.app。 您還必須指定 Microsoft Entra 應用程式的認證，包括用戶端識別碼、用戶端密碼和租用戶識別碼。 連接字串看起來像下列範例：

Endpoint=https://<resource_name>.service.signalr.net;AuthType=azure.app;ClientId=<client_id>;ClientSecret=<client_secret>;TenantId=<tenant_id>;Version=1.0;

如需如何使用 Microsoft Entra 應用程式進行驗證的詳細資訊，請參閱使用 Microsoft Entra 應用程式授權對 SignalR 資源的要求。

使用受控識別進行驗證

您可以使用系統指派或使用者指派的受控識別，向 Azure SignalR Service 進行驗證。

若要使用系統指派的身分識別，請將 AuthType=azure.msi 新增至連接字串：

Endpoint=https://<resource_name>.service.signalr.net;AuthType=azure.msi;Version=1.0;

Azure SignalR Service SDK 會自動使用應用程式伺服器的身分識別。

若要使用使用者指派的身分識別，請在連接字串中包含受控識別的用戶端識別碼：

Endpoint=https://<resource_name>.service.signalr.net;AuthType=azure.msi;ClientId=<client_id>;Version=1.0;

如需如何設定受控識別的詳細資訊，請參閱使用 Microsoft Entra 受控識別授權 SignalR 資源的要求。

使用連接字串產生器

手動建置連接字串可能會很麻煩且容易出錯。 為避免錯誤，Azure SignalR Service 提供連接字串產生器，以協助您產生包含 clientId 和 tenantId 等 Microsoft Entra 身分識別的連接字串。 若要使用此工具，請在 Azure 入口網站中開啟您的 Azure SignalR Service 執行個體，然後從左側功能表中選取 [連接字串]。

在此頁面上，您可以選擇驗證類型 (存取金鑰、受控識別或 Microsoft Entra 應用程式)，並輸入用戶端端點、用戶端識別碼和用戶端密碼等資訊。 然後會自動產生連接字串。 您可以複製連接字串，並用於應用程式。

如需如何產生及驗證存取權杖的詳細資訊，請參閱 Azure SignalR Service 資料平面 REST API 參考中的透過 Microsoft Entra 權杖進行驗證一節。

提供用戶端和伺服器端點

連接字串包含要連接 Azure SignalR Service 的應用程式伺服器 HTTP 端點。 伺服器會在交涉回應中將 HTTP 端點傳回給用戶端，讓用戶端可以連線到服務。

在某些應用程式中，Azure SignalR Service 前面可能會有額外的元件。 所有用戶端連線都必須先通過該元件。 例如，Azure 應用程式閘道是提供其他網路安全性的常見服務。

在這種情況下，用戶端必須連線到不同於 Azure SignalR Service 的端點。 您可以將 ClientEndpoint 新增至連接字串，而不是手動取代用戶端的端點：

Endpoint=https://<resource_name>.service.signalr.net;AccessKey=<access_key>;ClientEndpoint=https://<url_to_app_gateway>;Version=1.0;

應用程式伺服器會傳回用戶端交涉要求的回應。 回應包含用戶端所連線的正確端點 URL。 如需用戶端連線的詳細資訊，請參閱 Azure SignalR Service 內部。

同樣地，如果伺服器嘗試建立伺服器連線或呼叫 REST API 服務，Azure SignalR Service 也可能位於另一個服務後方，例如 Azure 應用程式閘道。 在此情況下，您可以使用 ServerEndpoint 來指定伺服器連線和 REST API 的實際端點：

Endpoint=https://<resource_name>.service.signalr.net;AccessKey=<access_key>;ServerEndpoint=https://<url_to_app_gateway>;Version=1.0;

在應用程式中設定連接字串

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

有兩種方式可在應用程式中設定連接字串。

您可以在呼叫 AddAzureSignalR() API 時設定連接字串：

services.AddSignalR().AddAzureSignalR("<connection_string>");

或者，您可以呼叫 AddAzureSignalR() 而不使用任何引數。 服務 SDK 會從組態提供者中名為 Azure:SignalR:ConnectionString 的組態傳回連接字串。

在本機開發環境中，組態會儲存在檔案 (appsettings.json 或 secrets.json) 中，或儲存在環境變數中。 您可以使用下列其中一種方式來設定連接字串：

• 使用 .NET 祕密管理員 (dotnet user-secrets set Azure:SignalR:ConnectionString "<connection_string>")。
• 將名為 Azure__SignalR__ConnectionString 的環境變數設定為連接字串。 必須以環境變數組態提供者中的雙底線取代冒號。

在實際執行環境中，您可以使用其他 Azure 服務來管理設定和秘密，例如 Azure Key Vault 和應用程式組態。 請參閱其文件，以了解如何設定這些服務的組態提供者。

設定多個連接字串

Azure SignalR Service 也允許伺服器同時連接多個服務端點，因此其可以處理連線數超過一個服務執行個體的限制。 當某一服務執行個體已關閉時，您可以使用其他服務執行個體當做備份。 如需關於如何使用多個執行個體的詳細資訊，請參閱使用多個執行個體來調整 SignalR Service。

有兩種方式可以設定多個執行個體：

• 透過程式碼：

  services.AddSignalR().AddAzureSignalR(options =>
      {
          options.Endpoints = new ServiceEndpoint[]
          {
              new ServiceEndpoint("<connection_string_1>", name: "name_a"),
              new ServiceEndpoint("<connection_string_2>", name: "name_b", type: EndpointType.Primary),
              new ServiceEndpoint("<connection_string_3>", name: "name_c", type: EndpointType.Secondary),
          };
      });
  

  您可以將名稱和類型指派給每個服務端點，以便稍後加以區別。

• 透過組態：

  您可以使用任何支援的設定提供者 (例如，秘密管理員、環境變數或金鑰保存庫) 來儲存連接字串。 以下是使用祕密管理員的範例：

  dotnet user-secrets set Azure:SignalR:ConnectionString:name_a <connection_string_1>
  dotnet user-secrets set Azure:SignalR:ConnectionString:name_b:primary <connection_string_2>
  dotnet user-secrets set Azure:SignalR:ConnectionString:name_c:secondary <connection_string_3>
  

  您可以使用採用下列格式的不同設定名稱，將名稱和類型指派給每個端點：

  Azure:SignalR:ConnectionString:<name>:<type>