Azure SignalR Service 中的連線字串

發行項
10/24/2023

連接字串包含如何連線至 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。

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

機碼	描述	必要	預設值	範例值
`Endpoint`	Azure SignalR Service 實例的 URL。	Yes	不適用	`https://foo.service.signalr.net`
`Port`	Azure SignalR Service 實例正在接聽的埠。	No	`80` 或 `443` ，視端點 URI 架構而定	`8080`
`Version`	連接字串的版本。	No	`1.0`	`1.0`
`ClientEndpoint`	反向 Proxy 的 URI，例如Azure 應用程式閘道或 Azure API 管理。	No	`null`	`https://foo.bar`
`AuthType`	驗證類型。根據預設，服務會使用 `AccessKey` 來授權要求。不區分大小寫。	No	`null`	`Azure`, `azure.msi`, `azure.app`

使用 AccessKey

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

機碼	描述	必要	預設值	範例值
`AccessKey`	基底64 格式的金鑰字串，用於建置存取權杖。	Yes	`null`	`ABCDEFGHIJKLMNOPQRSTUVWEXYZ0123456789+=/`

使用 Microsoft Entra ID

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

機碼	描述	必要	預設值	範例值
`ClientId`	Azure 應用程式或 Azure 身分識別的 GUID。	No	`null`	`00000000-0000-0000-0000-000000000000`
`TenantId`	Microsoft Entra 識別碼中組織的 GUID。	No	`null`	`00000000-0000-0000-0000-000000000000`
`ClientSecret`	Azure 應用程式實例的密碼。	No	`null`	`*********************.**************`
`ClientCertPath`	用戶端憑證檔案至 Azure 應用程式實例的絕對路徑。	No	`null`	`/usr/local/cert/app.cert`

服務會使用不同的 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

和 clientIdtenantId 都必須搭配服務主體使用 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 服務資源。 [金鑰] 索引標籤會以下列格式顯示兩個連接字串（主要和次要）：

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 服務的正確許可權，則不需要存取金鑰。

若要使用 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 服務進行驗證。

若要使用系統指派的身分識別，請將新增 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 進行驗證，因為它們比存取金鑰更安全。如果您未使用存取金鑰進行驗證，請考慮在Azure 入口網站中完全停用它們（選取 [金鑰 > 存取金鑰 > 停用]。

如果您決定使用存取金鑰，建議您定期輪替它們。如需詳細資訊，請參閱輪替 Azure SignalR 服務的存取金鑰。

使用連接字串產生器

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

Screenshot that shows the connection string generator for Azure SignalR Service in the Azure portal.

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

注意

離開頁面之後，不會儲存您輸入的資訊。您必須複製並儲存連接字串，才能在應用程式中使用它。

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

提供用戶端和伺服器端點

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

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

在這種情況下，用戶端必須連線到不同于 Azure SignalR 服務的端點。您可以新增 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;

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

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

您可以在呼叫 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 金鑰保存庫和應用程式組態。請參閱其檔，以瞭解如何為這些服務設定設定提供者。

注意

即使您使用程式碼直接設定連接字串，也不建議您在原始程式碼中將連接字串硬式編碼。相反地，從金鑰保存庫等秘密存放區讀取連接字串，並將其傳遞至 AddAzureSignalR() 。

設定多個連接字串

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>

Share via