Application Insights 中的连接字符串

项目
2025-05-12

连接字符串指定被检测的应用程序要将遥测数据发送到哪个 Application Insights 资源。连接字符串由多个设置组成，每个设置以键值对的形式表示并用分号分隔。这种整合的配置方法消除了对多个代理设置的需要，因而简化了设置过程。

重要说明

连接字符串包含 ikey 和 ApplicationId。

ikey 是引入服务用于将遥测与特定 Application Insights 资源关联的唯一标识符。 Ikey 唯一标识符不是安全令牌或安全密钥，也不被视为机密。通过添加 ApplicationId 值来增强连接字符串。此更新是一项新功能，支持自动检测使用 Open Telemetry SDK 的方案。如果你要防止 Application Insights 资源遭到滥用，请使用引入终结点，它提供基于 Microsoft Entra ID 的经身份验证的遥测引入选项。

注意

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

连接字符串功能

可靠性：连接字符串通过删除全局引入终结点上的依赖项提高遥测引入的可靠性。
安全性：连接字符串允许通过使用 Application Insights 的 Microsoft Entra 身份验证引入经过身份验证的遥测。
自定义终结点（主权或混合云环境）：终结点设置允许将数据发送到特定的 Azure 政府区域。（请参阅示例。）
隐私（区域终结点）：连接字符串通过将数据发送到区域终结点来解决隐私问题，从而确保数据不会离开某一地理区域。

查找连接字符串

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

架构

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

最大长度

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

键值对

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

提示

本文档介绍了可配置的键值对。某些键值对不可配置，并且会自动设置，例如 ApplicationId。如果在环境中观察到这些对，可以安全地忽略它们。

语法

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

终结点架构

<prefix>.<suffix>

前缀：定义某个服务。
后缀：定义公共域名。

有效后缀

Azure 应用见解 (applicationinsights.azure.cn)
applicationinsights.us

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

有效的前缀

遥测引入：dc
实时指标：live
适用于 .NET 的 Profiler：profiler
快照：snapshot

连接字符串示例

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

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

InstrumentationKey=00000000-0000-0000-0000-000000000000;EndpointSuffix=ai.contoso.com;

在本例中，连接字符串指定终结点后缀，SDK 构造服务终结点：

授权方案默认为“ikey”
检测密钥：00000000-0000-0000-0000-000000000000
区域服务统一资源标识符 (URI) 基于提供的终结点后缀：
- 引入：https://dc.ai.contoso.com
- 实时指标：https://live.ai.contoso.com
- 适用于 .NET 的 Profiler：https://profiler.ai.contoso.com
- 调试程序：https://snapshot.ai.contoso.com

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

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/
- 适用于 .NET 的 Profiler：https://custom.com:333/
- 调试程序：https://custom.com:444/

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

InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://southcentralus.in.applicationinsights.azure.com/

在此示例中，连接字符串指定“美国中南部”区域：

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

若要列出可用性区域，请在 Azure CLI 中运行以下命令：

az account list-locations -o table

设置连接字符串

我们的所有 OpenTelemetry 产品/服务和以下 SDK 版本均支持连接字符串：

.NET v2.12.0
JavaScript v2.3.0
NodeJS v1.5.0
Python v1.0.0
Java v3.1.1

可以使用环境变量或配置文件在代码中设置连接字符串。

环境变量

连接字符串：APPLICATIONINSIGHTS_CONNECTION_STRING

代码示例

语言	经典 API	OpenTelemetry
ASP.NET Core	Application Insights SDK	AzMon OTel 发行版
.NET 框架	Application Insights SDK	AzMon 导出程序
爪哇岛	空值	Java 代理
Javascript	JavaScript (Web) SDK 加载程序脚本	空值
Node.js	Application Insights SDK	AzMon OTel 发行版
Python语言	OpenCensus Python SDK	AzMon OTel 发行版

常见问题

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

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

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

我应使用连接字符串还是检测密钥？

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

何时需要设置环境变量？

在所有系统未自动提供 APPLICATIONINSIGHTS_CONNECTION_STRING 的场景中，手动设置它。这些方案包括但不限于：使用 ASP.NET Core 集成的本地开发和 .NET 独立函数。在这些情况下，环境变量可确保 OpenTelemetry 管道可以将遥测数据发送到 Application Insights。有关使用环境变量配置连接字符串的详细信息，请参阅在 Application Insights 中配置 OpenTelemetry。

常见问题解答：如何检测全球 Web 应用程序以满足区域数据合规性要求？

若要满足区域数据符合性要求，请使用区域 Application Insights 终结点而不是全局终结点。全局终结点不保证数据保留在特定区域中。区域终结点有助于确保来自受管制区域中的用户的遥测仅发送到这些区域中的数据中心。

若要为全球web应用程序配置地区合规性，请执行以下步骤：

为每个区域创建一个 Application Insights 资源，其中包含严格的符合性要求，例如欧盟或美国。
为所有其他区域中的用户创建另一个 Application Insights 资源。
将应用程序配置为根据每个用户的区域将遥测数据发送到相应的 Application Insights 资源。使用 IP 地址、帐户元数据或位置设置等信号确定区域。
如果需要跨区域提供统一的查询体验，请将所有 Application Insights 资源连接到 Log Analytics 工作区。

例如：

使用区域 A 连接字符串将数据从区域 A 用户发送到区域 A Application Insights 资源。
使用区域 B 连接字符串将数据从区域 B 用户发送到区域 B Application Insights 资源。
使用其他连接字符串将所有其他用户数据发送到常规用途 Application Insights 资源。