String koneksi

Artikel ini menunjukkan cara menggunakan string koneksi.

Gambaran Umum

Catatan

Dokumentasi berikut bergantung pada API klasik Application Insights. Rencana jangka panjang untuk Application Insights adalah mengumpulkan data menggunakan OpenTelemetry. Untuk informasi selengkapnya, lihat Mengaktifkan Azure Monitor OpenTelemetry untuk aplikasi .NET, Node.js, Python, dan Java.

String koneksi menentukan tempat mengirim data telemetri.

Pasangan nilai kunci menyediakan cara mudah bagi pengguna untuk menentukan kombinasi akhiran awalan untuk setiap layanan atau produk Application Insights.

Catatan

Pada tanggal 31 Maret 2025, dukungan untuk penyerapan kunci instrumentasi akan berakhir. Penyerapan kunci instrumentasi akan berjalan terus, namun kami tidak akan lagi menyediakan pembaruan atau dukungan terhadap fitur tersebut. Transisi ke string koneksi untuk memanfaatkan kemampuan baru.

Gambaran umum skenario

Skenario yang paling terpengaruh oleh perubahan ini:

• Pengecualian firewall atau pengalihan proksi:

  Dalam kasus di mana pemantauan untuk server web intranet diperlukan, solusi kami sebelumnya meminta Anda untuk menambahkan titik akhir layanan individual ke konfigurasi Anda. Untuk informasi selengkapnya, lihat Dapatkah saya memantau server web intranet?. String koneksi menawarkan alternatif yang lebih baik dengan mengurangi upaya ini ke satu pengaturan. Awalan sederhana, amandemen akhiran, memungkinkan populasi otomatis dan pengalihan semua titik akhir ke layanan yang tepat.

• Lingkungan cloud Sovereign atau Hibrid:

  Pengguna dapat mengirim data ke wilayah Azure Government yang ditentukan. Dengan menggunakan string koneksi, Anda dapat menentukan pengaturan titik akhir untuk server intranet atau pengaturan cloud hibrid Anda.

Memulai

Meninjau bagian berikut untuk memulai.

Menemukan string koneksi Anda

String koneksi Anda muncul di bagian Gambaran Umum sumber daya Application Insights Anda.

Skema

Elemen skema dijelaskan di bagian berikut.

Panjang maksimum

Koneksi memiliki panjang maksimum yang didukung yaitu 4.096 karakter.

Pasangan kunci-nilai

String koneksi terdiri dari daftar pengaturan yang direpresentasikan sebagai pasangan nilai kunci yang dipisahkan oleh titik koma: key1=value1;key2=value2;key3=value3

Sintaks

• InstrumentationKey (misalnya, 00000000-0000-0000-0000-000000000000). InstrumentationKey adalah bidang yang diperlukan .
• Authorization (misalnya, ikey). Pengaturan ini opsional karena hari ini kami hanya mendukung otorisasi ikey.
• EndpointSuffix (misalnya, applicationinsights.azure.cn). Mengatur akhiran titik akhir memberi tahu SDK cloud Azure mana yang akan disambungkan. SDK merakitan sisa titik akhir untuk layanan individual.
• Titik akhir eksplisit. Layanan apa pun dapat ditimpa secara eksplisit dalam string koneksi:
  • IngestionEndpoint (misalnya, https://dc.applicationinsights.azure.com)
  • LiveEndpoint (misalnya, https://live.applicationinsights.azure.com)
  • ProfilerEndpoint (misalnya, https://profiler.monitor.azure.com)
  • SnapshotEndpoint (misalnya, https://snapshot.monitor.azure.com)

Skema titik akhir

<prefix>.<suffix>

• Awalan: Mendefinisikan layanan.
• Akhiran: Mendefinisikan nama domain umum.

Akhiran yang valid

• applicationinsights.azure.cn
• applicationinsights.us

Untuk informasi selengkapnya, lihat Wilayah yang memerlukan modifikasi titik akhir.

Awalan yang valid

• Penyerapan Telemetri: dc
• Metrik Langsung: live
• Profiler: profiler
• Rekam jepret: snapshot

Apakah string koneksi merupakan sebuah rahasia?

String koneksi berisi ikey, yang merupakan pengidentifikasi unik yang digunakan oleh layanan penyerapan untuk mengaitkan telemetri ke sumber daya Application Insights tertentu. Pengidentifikasi unik ikey ini bukan token keamanan atau kunci keamanan. Jika Anda ingin melindungi sumber daya AI dari penyalahgunaan, titik akhir penyerapan menyediakan opsi penyerapan telemetri yang diautentikasi berdasarkan ID Microsoft Entra.

Catatan

Application Insights JavaScript SDK memerlukan string koneksi untuk diteruskan selama inisialisasi dan konfigurasi. Ini dapat dilihat dalam teks biasa di browser klien. Tidak ada cara mudah untuk menggunakan autentikasi berbasis ID Microsoft Entra untuk telemetri browser. Kami menyarankan Anda mempertimbangkan untuk membuat sumber daya Application Insights terpisah untuk telemetri browser jika Anda perlu mengamankan telemetri layanan.

Contoh string koneksi

Berikut adalah beberapa contoh string koneksi.

String koneksi dengan akhiran titik akhir

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

Dalam contoh ini, string koneksi menentukan akhiran titik akhir dan titik akhir layanan konstruksi SDK:

• Default skema otorisasi ke "ikey"
• Kunci instrumentasi: 00000000-0000-0000-0000-000000000000
• URI layanan regional didasarkan pada akhiran titik akhir yang disediakan:
  • Penyerapan: https://dc.ai.contoso.com
  • Metrik langsung: https://live.ai.contoso.com
  • Profiler: https://profiler.ai.contoso.com
  • Debugger: https://snapshot.ai.contoso.com

String koneksi dengan penggantian titik akhir eksplisit

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/;

Dalam contoh ini, string koneksi menentukan pengambilalihan eksplisit untuk setiap layanan. SDK menggunakan titik akhir yang tepat yang disediakan tanpa modifikasi:

• Default skema otorisasi ke "ikey"
• Kunci instrumentasi: 00000000-0000-0000-0000-000000000000
• URI layanan regional didasarkan pada nilai penimpaan eksplisit:
  • Penyerapan: https://custom.com:111/
  • Metrik langsung: https://custom.com:222/
  • Profiler: https://custom.com:333/
  • Debugger: https://custom.com:444/

String koneksi dengan wilayah eksplisit

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

Dalam contoh ini, string koneksi menentukan wilayah US Tengah Selatan:

• Default skema otorisasi ke "ikey"
• Kunci instrumentasi: 00000000-0000-0000-0000-000000000000
• URI layanan regional didasarkan pada nilai penimpaan eksplisit:
  • Penyerapan: https://southcentralus.in.applicationinsights.azure.com/

Jalankan perintah berikut di Azure CLI untuk mencantumkan wilayah yang tersedia:

az account list-locations -o table

Mengatur string koneksi

String koneksi didukung dalam versi SDK berikut:

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

Anda dapat mengatur string koneksi dalam kode atau dengan menggunakan variabel lingkungan atau file konfigurasi.

Variabel lingkungan

String koneksi: APPLICATIONINSIGHTS_CONNECTION_STRING

Sampel kode

.NET 5.0+

1. Atur string koneksi dalam appsettings.json file:

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

2. Ambil string koneksi saat Program.cs mendaftarkan ApplicationInsightsTelemetry layanan:

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

.NET Framework

Atur properti TelemetryConfiguration.ConnectionString atau ApplicationInsightsServiceOptions.ConnectionString.

Secara eksplisit mengatur string koneksi dalam kode:

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

Atur string koneksi menggunakan file konfigurasi:

<?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

Anda dapat mengatur string koneksi di file konfigurasi applicationinsights.json:

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

Untuk informasi selengkapnya, lihat Konfigurasi string koneksi.

JavaScript

JavaScript tidak mendukung penggunaan variabel lingkungan. Anda memiliki dua pilihan:

• Untuk menggunakan Skrip Pemuat SDK JavaScript (Web), lihat Skrip Pemuat SDK JavaScript (Web).
• Penyiapan manual:

  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

Kami menyarankan agar pengguna mengatur variabel lingkungan.

Untuk mengatur string koneksi secara eksplisit:

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))

Tanya jawab umum

Bagian ini menyediakan jawaban atas pertanyaan umum.

Apakah wilayah Azure baru memerlukan penggunaan string koneksi?

Wilayah Azure baru mewajibkan penggunaan string koneksi, dan bukan kunci instrumentasi. string Koneksi ion mengidentifikasi sumber daya yang ingin Anda kaitkan dengan data telemetri Anda. Ini juga memungkinkan Anda untuk memodifikasi titik akhir yang digunakan sumber daya Anda sebagai tujuan telemetri Anda. Salin string koneksi dan tambahkan ke kode aplikasi Anda atau ke variabel lingkungan.

Haruskah saya menggunakan string koneksi atau kunci instrumentasi?

Kami menyarankan agar Anda menggunakan string koneksi alih-alih kunci instrumentasi.

Langkah berikutnya

Mulai pada runtime dengan:

• Aplikasi yang dihosting IIS Azure VM dan Azure Virtual Machine Scale Sets
• Server IIS
• Fitur Web Apps dari Azure App Service

Mulai pada waktu pengembangan dengan:

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