Share via

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

Azure SignalR 服务中的连接字符串

  • 项目

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

什么是连接字符串

当应用程序需要连接到 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 反向代理的 URI，例如Azure 应用程序网关或 Azure API 管理。 否 null https://foo.bar
AuthType 身份验证类型。 默认情况下，服务用于 AccessKey 授权请求。 该自变量不区分大小写。 否 null Azure, azure.msi, azure.app

使用 AccessKey

服务将本地身份验证方法 AuthType 设置为 null..

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

使用 Microsoft Entra ID

服务在设置为azure或azure.appazure.msi设置为 时AuthType使用 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 令牌，具体取决于你提供的参数：

如何获取连接字符串

可以使用 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 服务实例。 如果应用程序有权访问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 服务实例，并从左侧菜单中选择连接字符串。

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

在此页上，可以选择身份验证类型（访问密钥、托管标识或 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;

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

可以通过两种方式在应用程序中配置连接字符串。

调用 API 时AddAzureSignalR()，可以设置连接字符串：

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>