連接字串

本文說明如何使用連接字串。

概觀

注意

下列文件以 Application Insights 傳統 API 為依據。 Application Insights 的長期計劃是使用 OpenTelemetry 收集資料。 如需詳細資訊，請參閱啟用適用於 .NET、Node.js、Python 和 JAVA 應用程式的 Azure 監視器 OpenTelemetry 和我們的 OpenTelemetry 藍圖。 移轉指導適用於 .NET、Node.js 和 Python。

連接字串會定義傳送遙測資料的位置。

機碼值組提供一種便利方式，讓使用者可針對每個 Application Insights 服務或產品定義首碼尾碼組合。

注意

針對檢測金鑰擷取的支援將在 2025 年 3 月 31 日結束。 檢測金鑰擷取將會繼續運作，但我們不再提供該功能的更新或支援。 轉換至連接字串以利用新功能。

案例概觀

受這項變更影響最大的案例為：

• 防火牆例外狀況或 Proxy 重新導向：

  如需監視內部網路 Web 伺服器，我們先前的解決方案會要求您將個別服務端點新增至設定。 如需詳細資訊，請參閱我是否可以監視內部網路 Web 伺服器？。 連接字串將此工作減少為單一設定，進而提供了更好的替代方案。 一項簡單的首碼尾碼增修條款允許所有端點自動母體擴展，並重新導向至正確的服務。

• 主權或混合式雲端環境：

  使用者可以將資料傳送至已定義的 Azure Government 區域。 藉由使用連接字串，您可以針對內部網路伺服器或混合式雲端設定定義端點設定。

開始使用

請檢閱下列各節以開始使用。

尋找您的連接字串

您的連接字串會出現在 Application Insights 資源的 [概觀] 區段上。

結構描述

下列各節將說明結構描述元素。

最大長度

連線的最大支援長度為 4,096 個字元。

索引鍵/值組

連接字串由以分號分隔的機碼值組表示的設定清單所組成：key1=value1;key2=value2;key3=value3

語法

• InstrumentationKey (例如，00000000-0000-0000-0000-000000000000)。 InstrumentationKey 是必要欄位。
• Authorization (例如，ikey)。 這是選用設定，因為現今我們只支援 ikey 授權。
• EndpointSuffix (例如，applicationinsights.azure.cn)。 設定端點尾碼說明 Azure 雲端要連線至哪個 SDK。 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>

• 前置詞：定義服務。
• 後置詞：定義常見網域名稱。

有效的後置詞

• 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=ai.contoso.com;

在此範例中，連接字串會指定端點尾碼，而 SDK 會建構服務端點：

• 授權配置預設為「ikey」
• 檢測金鑰：00000000-0000-0000-0000-000000000000
• 區域服務 URI 以提供的端點尾碼為基礎：
  • 擷取：https://dc.ai.contoso.com
  • 即時計量：https://live.ai.contoso.com
  • 分析工具：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/
  • 分析工具：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

設定連接字串

下列為支援連接字串的 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

程式碼範例

.NET 5.0+

1. 設定 appsettings.json 檔案中的連接字串：

   {
     "ApplicationInsights": {
       "ConnectionString" : "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://{region}.in.applicationinsights.azure.com/;LiveEndpoint=https://{region}.livediagnostics.monitor.azure.com/"
       }
   }
   

2. 註冊 ApplicationInsightsTelemetry 服務時，擷取 Program.cs 中的連接字串：

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

.NET Framework

設定 TelemetryConfiguration.ConnectionString 或 ApplicationInsightsServiceOptions.ConnectionString 屬性。

在程式碼中明確設定連接字串：

var configuration = new TelemetryConfiguration
{
    ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://{region}.in.applicationinsights.azure.com/;LiveEndpoint=https://{region}.livediagnostics.monitor.azure.com/"
};

使用設定檔設定連接字串：

<?xml version="1.0" encoding="utf-8"?>
<ApplicationInsights xmlns="http://schemas.microsoft.com/ApplicationInsights/2013/Settings">
    <ConnectionString>InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://{region}.in.applicationinsights.azure.com/;LiveEndpoint=https://{region}.livediagnostics.monitor.azure.com/</ConnectionString>
</ApplicationInsights>

Java

您可以在 applicationinsights.json 設定檔中設定連接字串：

{
  "connectionString": "InstrumentationKey=00000000-0000-0000-0000-000000000000;IngestionEndpoint=https://{region}.in.applicationinsights.azure.com/;LiveEndpoint=https://{region}.livediagnostics.monitor.azure.com/"
}

如需詳細資訊，請參閱連接字串設定。

JavaScript

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;'
     /* ...Other Configuration Options... */
  } });
  appInsights.loadAppInsights();
  appInsights.trackPageView();
  

Node.js

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

Python

建議使用者設定環境變數。

若要明確設定連接字串：

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;IngestionEndpoint=https://{region}.in.applicationinsights.azure.com/;LiveEndpoint=https://{region}.livediagnostics.monitor.azure.com/'), sampler=ProbabilitySampler(1.0))

常見問題集

本節提供常見問題的答案。

新的 Azure 區域是否需要使用連接字串？

新的 Azure 區域需要使用連接字串而不是檢測金鑰。 連接字串可識別您想要與遙測資料建立關聯的資源。 其也可讓您修改資源用來作為遙測目的地的端點。 請複製連接字串，並將其新增至應用程式的程式碼或新增至環境變數。

我應該使用連接字串或檢測金鑰？

我們建議您使用連接字串，而非檢測金鑰。

下一步

在執行階段開始使用︰

• Azure VM 和 Azure 虛擬機器擴展集 IIS 裝載的應用程式
• IIS 伺服器
• Azure App Service 中的 Web Apps 功能

在開發階段開始使用︰

• ASP.NET
• ASP.NET Core
• Java
• Node.js
• Python