Azure SignalR 服务中的连接字符串

连接字符串包含有关如何连接到Azure SignalR 服务的信息。 本文介绍连接字符串的基本知识，以及如何在应用程序中配置连接字符串。

什么是连接字符串

当应用程序需要连接到Azure SignalR 服务时，它需要以下信息：

• Azure SignalR 服务实例的 HTTP 终结点
• 使用服务终结点进行身份验证的方式

Connection String包含此类信息。

连接字符串的格式是什么样的

Connection string 由一系列以分号 (;) 分隔的键/值对组成。 该字符串使用等号 (=) 连接每个键及其值。 键不区分大小写。

典型的连接字符串可能如以下示例所示：

Endpoint=https://<resource_name>.signalr.azure.cn;AccessKey=<access_key>;Version=1.0;

连接字符串包含：

• Endpoint=https://<resource_name>.signalr.azure.cn：资源的终结点 URL。
• AccessKey=<access_key>：用于向服务进行身份验证的密钥。 在连接字符串中指定访问密钥时，Azure SignalR 服务 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 都需要将 a Microsoft Entra 应用程序与服务主体一起使用。

  • 如果连接字符串使用 ，该服务将使用 clientSecret：

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

  • 如果连接字符串使用 ，该服务将使用 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>.signalr.azure.cn;AccessKey=<access_key>;Version=1.0;

Azure CLI

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

使用 Microsoft Entra 应用程序进行连接

可以使用 Microsoft Entra 应用程序连接到 Azure SignalR 服务 实例。 如果应用程序有权访问Azure SignalR 服务，则不需要访问密钥。

若要使用Microsoft Entra身份验证，需要从连接字符串中删除 AccessKey，并添加 AuthType=azure.app。 您还需要指定 Microsoft Entra 应用程序的凭据，包括客户端 ID、客户端密码和租户 ID。 连接字符串的格式如下示例所示：

Endpoint=https://<resource_name>.signalr.azure.cn;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>.signalr.azure.cn;AuthType=azure.msi;Version=1.0;

Azure SignalR 服务 SDK 会自动使用应用服务器的标识。

若要使用用户分配的标识，请在连接字符串中包含托管标识的客户端 ID：

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

有关如何配置托管标识的详细信息，请参阅使用Microsoft Entra托管标识对 SignalR 资源的请求进行身份验证。

使用连接字符串生成器

手动生成连接字符串可能比较繁琐且容易出错。 为避免错误，Azure SignalR 服务提供了一个连接字符串生成器来帮助生成包含Microsoft Entra标识（如 clientId 和 tenantId）的连接字符串。 若要使用该工具，请在Azure门户中打开Azure SignalR 服务实例，然后从左侧菜单中选择Connection 字符串。

在此页上，可以选择身份验证类型（访问密钥、托管标识或Microsoft Entra应用程序），并输入客户端终结点、客户端 ID 和客户端密码等信息。 然后自动生成连接字符串。 可以复制它并在应用程序中使用。

有关如何生成和验证访问令牌的详细信息，请参阅Azure SignalR 服务数据平面 REST API 参考中的 Authenticate via Microsoft Entra token 部分。

提供客户端和服务器端点

连接字符串包含应用服务器连接到 Azure SignalR 服务的 HTTP 终结点。 服务器在协商响应中将 HTTP 终结点返回给客户端，以便客户端可以连接到服务。

在某些应用程序中，Azure SignalR 服务前面可能有一个额外的组件。 所有客户端连接都需要首先通过该组件。 例如，Azure 应用程序网关是一种提供额外网络安全的常见服务。

在这种情况下，客户端需要连接到不同于Azure SignalR 服务的终结点。 可以将 ClientEndpoint 添加到连接字符串，而不是在客户端手动替换端点。

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

应用服务器返回对客户端协商请求的响应。 响应包含客户端要连接到的正确终结点 URL。 有关客户端连接的详细信息，请参阅 Azure SignalR 服务 internals。

同样，如果服务器尝试服务器连接或调用 REST API服务，Azure SignalR 服务也可能位于另一个服务后面，例如 Azure 应用程序网关。 在这种情况下，可以使用 ServerEndpoint 指定服务器连接和 REST API 的实际终结点：

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

在应用程序中配置连接字符串

本文中出现的原始连接字符串仅用于演示目的。 在生产环境中，请始终保护访问密钥。 使用 Azure 密钥保管库 安全地管理和轮换密钥，并使用 Microsoft Entra ID 保护您的连接字符串，同时使用 Microsoft Entra ID 授权访问。

在应用程序中配置连接字符串有两种方法。

调用 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 密钥保管库 和 App Configuration。 请参阅相关文档了解如何为这些服务设置配置提供程序。

配置多个连接字符串

Azure SignalR 服务允许服务器同时连接到多个服务终结点，因此它可以处理超出服务实例限制的更多连接。 当一个服务实例关闭时，你可以使用其他服务实例作为后备实例。 有关如何使用多个实例的详细信息，请参阅具有多个实例的 Scale SignalR 服务。

可以通过两种方式配置多个实例：

• 通过编写代码：

  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>