你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure SignalR 服务中的连接字符串

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

重要

本文中出现的原始连接字符串仅用于演示目的。

连接字符串包括应用程序访问 Azure Web PubSub 服务所需的授权信息。 连接字符串中的访问密钥类似于服务的根密码。 在生产环境中，请始终保护访问密钥。 使用 Azure Key Vault 安全地管理和轮换密钥，使用 Microsoft Entra ID 保护连接字符串，并使用 Microsoft Entra ID 授权访问。

避免将访问密钥分发给其他用户、对其进行硬编码或将其以纯文本形式保存在其他人可以访问的任何位置。 如果你认为访问密钥可能已泄露，请轮换密钥。

连接字符串是什么

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

• Azure SignalR 服务实例的 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 服务 SDK 将使用它来生成服务验证的令牌。
• Version：连接字符串的版本。 默认值为 1.0。

下表列出了连接字符串中键/值对的所有有效名称。

密钥	说明	必须	默认值	示例值
Endpoint	Azure SignalR 服务实例的 URL。	是	不适用	https://foo.service.signalr.net
Port	Azure SignalR 服务实例正在侦听的端口。	否	80 或 443，具体取决于终结点 URI 架构	8080
Version	连接字符串的版本。	否	1.0	1.0
ClientEndpoint	反向代理（例如 Azure 应用程序网关或 Azure API 管理）的 URI。	否	null	https://foo.bar
AuthType	身份验证类型。 默认情况下，服务使用 AccessKey 来授权请求。 该自变量不区分大小写。	否	null	Azure、azure.msi、azure.app

使用 AccessKey

当 AuthType 设置为 null 时，服务将使用本地身份验证方法。

密钥	说明	必须	默认值	示例值
AccessKey	Base64 格式的密钥字符串，用于生成访问令牌。	是	null	ABCDEFGHIJKLMNOPQRSTUVWEXYZ0123456789+=/

使用 Microsoft Entra ID

当 AuthType 设置为 azure、azure.app 或 azure.msi 时，服务将使用 Microsoft Entra 身份验证方法。

密钥	说明	必须	默认值	示例值
ClientId	Azure 应用程序或 Azure 标识的 GUID。	否	null	00000000-0000-0000-0000-000000000000
TenantId	Microsoft Entra ID 中组织的 GUID。	否	null	00000000-0000-0000-0000-000000000000
ClientSecret	Azure 应用程序实例的密码。	否	null	***********************.****************
ClientCertPath	客户端证书文件在 Azure 应用程序实例上的绝对路径。	否	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 门户中打开你的 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 服务实例。 如果应用程序有权访问 Azure SignalR 服务，则不需要访问密钥。

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

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 服务 SDK 自动使用你的应用服务器的标识。

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

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

有关如何配置托管标识的详细信息，请参阅使用 Microsoft Entra 托管标识授权对 SignalR 资源的请求。

注意

强烈建议使用托管标识向 Azure SignalR 服务进行身份验证，因为它们比访问密钥更安全。 如果不使用访问密钥进行身份验证，请考虑在 Azure 门户中完全禁用它们（选择“密钥”>“访问密钥”>“禁用”）。

如果你决定使用访问密钥，建议定期轮换它们。 有关详细信息，请参阅轮换 Azure SignalR 服务的访问密钥。

使用连接字符串生成器

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

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

注意

离开页面后，输入的信息不会保存。 需要复制并保存你的连接字符串，以便在应用程序中使用。

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

提供客户端和服务器终结点

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

在某些应用程序中，Azure SignalR 服务的前面可能有一个额外的组件。 所有客户端连接都需要首先通过该组件。 例如，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 服务内部。

同样，如果服务器尝试建立与服务的服务器连接或调用服务的 REST API，则 Azure SignalR 服务还可能在其他服务（例如 Azure 应用程序网关）后面。 在这种情况下，可以使用 ServerEndpoint 指定服务器连接和 REST API 的实际终结点：

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

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

本文中出现的原始连接字符串仅用于演示目的。 在生产环境中，请始终保护访问密钥。 使用 Azure Key Vault 安全地管理和轮换密钥，使用 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 服务来管理配置和机密。 请参阅相关文档了解如何为这些服务设置配置提供程序。

注意

即使直接使用代码设置连接字符串，也不建议在源代码中对连接字符串进行硬编码。 应该从密钥保管库等机密存储读取连接字符串，并将其传递给 AddAzureSignalR()。

配置多个连接字符串

Azure SignalR 服务允许服务器同时连接到多个服务终结点，以便处理更多连接（超出一个服务实例的限制）。 当一个服务实例关闭时，你可以使用其他服务实例作为后备实例。 有关如何使用多个实例的详细信息，请参阅使用多个实例扩展 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>