连接字符串

本文介绍如何使用连接字符串。

概述

连接字符串定义发送遥测数据的位置。

键值对为用户提供了一种简单的方式来为每个 Application Insights 服务或产品定义前缀后缀组合。

注意

对检测密钥引入的支持将于 2025 年 3 月 31 日结束。 检测密钥引入功能将会继续工作,但我们将不再为该功能提供更新或支持。 转换为连接字符串,以利用新功能

方案概述

受此更改影响最大的方案:

  • 防火墙例外或代理重定向:

    如果需要监视 Intranet Web 服务器,我们的早期解决方案会要求你将各个服务终结点添加到你的配置中。 有关详细信息,请参阅是否可以监视 Intranet Web 服务器?。 连接字符串只需进行单个设置,简化了此工作,因此是一种更好的选择。 简单的前缀后缀修正,允许自动填充所有终结点并将其重定向到正确的服务。

  • 主权云或混合云环境:

    用户可以将数据发送到由世纪互联区域运营的指定 Microsoft Azure。 使用连接字符串,你可以定义 Intranet 服务器或混合云设置的终结点设置。

入门

请查看以下部分,了解如何入门。

查找连接字符串

连接字符串显示在 Application Insights 资源的“概述”部分。

Screenshot that shows the Application Insights overview and connection string.

架构

以下部分对架构元素进行了说明。

最大长度

连接的受支持的最大长度为 4,096 个字符。

键值对

连接字符串包含一系列以键值对形式表示的设置(以分号分隔):key1=value1;key2=value2;key3=value3

语法

  • InstrumentationKey(例如 00000000-0000-0000-0000-000000000000)。 InstrumentationKey 是必填字段。
  • Authorization(例如 ikey)。 此设置为可选,因为目前我们仅支持 ikey 授权。
  • EndpointSuffix(例如 applicationinsights.azure.cn)。 设置终结点后缀是告知 SDK 连接到哪个 Azure 云。 SDK 会为各个服务组装终结点的其余部分。
  • 显式终结点。 任何服务均可在连接字符串中显式重写:
    • IngestionEndpoint(例如 https://dc.applicationinsights.azure.cn
    • LiveEndpoint(例如 https://live.applicationinsights.azure.cn
    • ProfilerEndpoint(例如 https://profiler.monitor.azure.cn
    • SnapshotEndpoint(例如 https://snapshot.monitor.azure.cn

终结点架构

<prefix>.<suffix>

  • 前缀:定义某个服务。
  • 后缀:定义公共域名。
有效后缀
  • applicationinsights.azure.cn
  • applicationinsights.us

有关详细信息,请参阅需要修改终结点的区域

有效的前缀

连接字符串是否为机密?

连接字符串包含 ikey,后者是引入服务用于将遥测与特定 Application Insights 资源关联的唯一标识符。 这些 ikey 唯一标识符不是安全令牌或安全密钥。 若要保护 AI 资源免受滥用,引入终结点可基于 Microsoft Entra ID 提供经过身份验证的遥测引入选项。

注意

Application Insights JavaScript SDK 要求在初始化和配置期间传入连接字符串。 可在客户端浏览器中以纯文本形式查看它。 没有一种简单的方法可以将基于 Microsoft Entra ID 的身份验证用于浏览器遥测。 如果你需要保护服务遥测,建议你考虑为浏览器遥测创建单独的 Application Insights 资源。

连接字符串示例

下面是连接字符串的一些示例。

带有终结点后缀的连接字符串

InstrumentationKey=00000000-0000-0000-0000-000000000000;EndpointSuffix=applicationinsights.azure.cn;

在此示例中,连接字符串指定世纪互联运营的 Microsoft Azure 中的终结点后缀,SDK 构建服务终结点。

  • 授权方案默认为“ikey”
  • 检测密钥:00000000-0000-0000-0000-000000000000
  • 区域服务 URI 基于所提供的终结点后缀:
    • 引入:https://dc.applicationinsights.azure.cn
    • 实时指标:https://live.applicationinsights.azure.cn
    • 探查器:https://profiler.applicationinsights.azure.cn
    • 调试程序:https://snapshot.applicationinsights.azure.cn

带有显式终结点重写的连接字符串

InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://custom.com:111/;LiveEndpoint=https://custom.com:222/;ProfilerEndpoint=https://custom.com:333/;SnapshotEndpoint=https://custom.com:444/;

在此示例中,连接字符串指定每个服务的显式重写。 SDK 使用所提供的确切终结点而不进行修改:

  • 授权方案默认为“ikey”
  • 检测密钥:00000000-0000-0000-0000-000000000000
  • 区域服务 URI 基于显式重写值:
    • 引入:https://custom.com:111/
    • 实时指标:https://custom.com:222/
    • 探查器:https://custom.com:333/
    • 调试程序:https://custom.com:444/

带有显式区域的连接字符串

InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://chinaeast2.in.applicationinsights.azure.cn/

在此示例中,连接字符串指定“中国东部 2”区域。

  • 授权方案默认为“ikey”
  • 检测密钥:00000000-0000-0000-0000-000000000000
  • 区域服务 URI 基于显式重写值:
    • 引入:https://chinaeast2.in.applicationinsights.azure.cn/

Azure CLI 中运行以下命令,列出可用区域:

az account list-locations -o table

设置连接字符串

以下 SDK 版本支持连接字符串:

  • .NET v2.12.0
  • Java v2.5.1 和 Java 3.0
  • JavaScript v2.3.0
  • NodeJS v1.5.0
  • Python v1.0.0

可以通过代码、环境变量或配置文件设置连接字符串。

环境变量

连接字符串:APPLICATIONINSIGHTS_CONNECTION_STRING

代码示例

  1. appsettings.json 文件中设置连接字符串:

    {
      "ApplicationInsights": {
        "ConnectionString" : "InstrumentationKey=00000000-0000-0000-0000-000000000000;EndpointSuffix=applicationinsights.azure.cn;IngestionEndpoint=https://{region}.in.applicationinsights.azure.cn/;LiveEndpoint=https://{region}.livediagnostics.monitor.azure.cn/"
        }
    }
    
  2. 注册 ApplicationInsightsTelemetry 服务时,在 Program.cs 中检索连接字符串:

    var options = new ApplicationInsightsServiceOptions { ConnectionString = app.Configuration["ApplicationInsights:ConnectionString"] };
    builder.Services.AddApplicationInsightsTelemetry(options: options);
    

常见问题

本部分提供常见问题的解答。

新的 Azure 区域是否需要使用连接字符串?

新的 Azure 区域要求使用连接字符串而不是检测密钥。 连接字符串会标识出要与遥测数据相关联的资源。 它还允许你修改可供你的资源将其用作遥测目标的终结点。 复制连接字符串,并将其添加到应用程序的代码或添加到环境变量中。

是否应该使用连接字符串或检测密钥?

建议使用连接字符串,而不是检测密钥。

后续步骤

在运行时开始使用:

在开发时开始使用: