连接字符串

项目
09/24/2024

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

概述

注意

以下文档依赖于 Application Insights 经典 API。 Application Insights 的长期计划是使用 OpenTelemetry 收集数据。有关详细信息，请参阅为 .NET、Node.js、Python 和 Java 应用程序启用 Azure Monitor OpenTelemetry 和我们的 OpenTelemetry 路线图。迁移指导适用于 .NET、Node.js 和 Python。

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

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

注意

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

方案概述

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

防火墙例外或代理重定向：

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

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

入门

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

查找连接字符串

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

架构

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

最大长度

连接的受支持的最大长度为 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

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

有效的前缀

遥测引入：dc
实时指标：live
探查器：profiler
快照：snapshot

连接字符串是否为机密？

连接字符串包含 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

代码示例

在 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/"
    }
}

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

设置属性 TelemetryConfiguration.ConnectionString 或 ApplicationInsightsServiceOptions.ConnectionString。

通过代码显式设置连接字符串：

var configuration = new TelemetryConfiguration
{
    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/"
};

使用配置文件设置连接字符串：

<?xml version="1.0" encoding="utf-8"?>
<ApplicationInsights xmlns="http://schemas.microsoft.com/ApplicationInsights/2013/Settings">
    <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/</ConnectionString>
</ApplicationInsights>

可以在 applicationinsights.json 配置文件中设置连接字符串：

{
  "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/"
}

有关详细信息，请参阅连接字符串配置。

JavaScript 不支持使用环境变量。可以使用两个选项：

要使用 JavaScript (Web) SDK 加载程序脚本，请参阅 JavaScript (Web) SDK 加载程序脚本。

手动设置：

import { ApplicationInsights } from '@microsoft/applicationinsights-web'

const appInsights = new ApplicationInsights({ config: {
   connectionString: 'InstrumentationKey=00000000-0000-0000-0000-000000000000;EndpointSuffix=applicationinsights.azure.cn;'
   /* ...Other Configuration Options... */
} });
appInsights.loadAppInsights();
appInsights.trackPageView();

const appInsights = require("applicationinsights");
appInsights.setup("InstrumentationKey=00000000-0000-0000-0000-000000000000;EndpointSuffix=applicationinsights.azure.cn;IngestionEndpoint=https://{region}.in.applicationinsights.azure.cn/;LiveEndpoint=https://{region}.livediagnostics.monitor.azure.cn/");
appInsights.start();

我们建议用户设置环境变量。

若要显式设置连接字符串，请执行以下代码：

from opencensus.ext.azure.trace_exporter import AzureExporter
from opencensus.trace.samplers import ProbabilitySampler
from opencensus.trace.tracer import Tracer

tracer = Tracer(exporter=AzureExporter(connection_string='InstrumentationKey=00000000-0000-0000-0000-000000000000;EndpointSuffix=applicationinsights.azure.cn;IngestionEndpoint=https://{region}.in.applicationinsights.azure.cn/;LiveEndpoint=https://{region}.livediagnostics.monitor.azure.cn/'), sampler=ProbabilitySampler(1.0))

常见问题

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

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

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

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

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

后续步骤

在运行时开始使用：

在开发时开始使用：

通过