Azure SignalR Service 中的連接字串

發行項
08/09/2024

連接字串包含如何連線至 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 APIM。	No	`null`	`https://foo.bar`
`AuthType`	驗證類型。根據預設，服務會使用 `AccessKey` 來授權要求。不區分大小寫。	No	`null`	`Azure`、、 `azure.msiazure.app`

使用 AccessKey

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

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

使用 Microsoft Entra ID

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

關鍵	描述	必要	預設值	範例值
`ClientId`	Azure 應用程式或 Azure 身分識別的 GUID。	No	`null`	`00000000-0000-0000-0000-000000000000`
`TenantId`	Microsoft Entra ID 中組織的 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

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 進行驗證，因為其較存取金鑰更安全。如果您未使用存取金鑰進行驗證，請考慮在 Azure 入口網站中加以完全停用 (選取 [金鑰]>[存取金鑰]>[停用])。

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

使用連接字串產生器

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

顯示 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;

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

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

您可以在呼叫 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 和應用程式組態。請參閱其文件，以了解如何設定這些服務的組態提供者。

注意

即使您使用程式碼直接設定連接字串，也不建議您在原始程式碼中硬式編碼連接字串。相反地，從 Key Vault 等秘密存放區讀取連接字串，並將其傳遞至 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>

共用方式為