Chaînes de connexion

Cet article explique comment utiliser des chaînes de connexion.

Vue d’ensemble

Les chaînes de connexion définissent l’emplacement vers lequel envoyer les données de télémétrie.

Les paires clé-valeur permettent aux utilisateurs de définir facilement une combinaison préfixe-suffixe pour chaque service ou produit Application Insights.

Notes

Le support de l’ingestion de clé d’instrumentation prendra fin le 31 mars 2025. L’ingestion de clé d’instrumentation continuera de fonctionner, mais nous ne fournirons plus de mises à jour ni de support pour la fonctionnalité. Passez aux chaînes de connexion pour tirer parti des nouvelles fonctionnalités.

Présentation du scénario

Scénarios les plus affectés par cette modification :

• Exceptions de pare-feu et redirections de proxy :

  Quand le monitoring d’un serveur web intranet était nécessaire, notre solution antérieure vous demandait d’ajouter des points de terminaison de service individuels à votre configuration. Pour plus d'informations, reportez-vous à Puis-je surveiller un serveur web intranet ? Les chaînes de connexion offrent une meilleure alternative en réduisant cet effort à un seul paramètre. La simple modification d’un préfixe et d’un suffixe permet de renseigner automatiquement tous les points de terminaison et de les rediriger vers les services appropriés.

• Environnements cloud souverains et hybrides :

  Les utilisateurs peuvent envoyer des données à une région Azure Government définie. À l’aide de chaînes de connexion, vous avez la possibilité de définir des paramètres de point de terminaison pour vos serveurs intranet ou des paramètres cloud hybrides.

Bien démarrer

Passez en revue les sections suivantes pour commencer.

Rechercher votre chaîne de connexion

Votre chaîne de connexion s’affiche dans la section Vue d’ensemble de votre ressource Application Insights.

schéma

Les éléments de schéma sont expliqués dans les sections suivantes.

Longueur maximale

La longueur maximale prise en charge pour la connexion s’élève à 4 096 caractères.

Paires clé-valeur

Une chaîne de connexion se compose d’une liste de paramètres représentés sous forme de paires clé-valeur séparées par un point-virgule : key1=value1;key2=value2;key3=value3.

Syntaxe

• InstrumentationKey (par exemple 00000000-0000-0000-0000-000000000000). InstrumentationKey est un champ obligatoire.
• Authorization (par exemple ikey). Ce paramètre est facultatif, car seule l’autorisation ikey est prise en charge à l’heure actuelle.
• EndpointSuffix (par exemple applicationinsights.azure.cn). La définition du suffixe du point de terminaison indique au SDK à quel cloud Azure se connecter. Le SDK assemble le reste du point de terminaison pour les services individuels.
• Points de terminaison explicites. Tout service peut être substitué explicitement dans la chaîne de connexion :
  • IngestionEndpoint (par exemple, https://dc.applicationinsights.azure.com)
  • LiveEndpoint (par exemple, https://live.applicationinsights.azure.com)
  • ProfilerEndpoint (par exemple, https://profiler.monitor.azure.com)
  • SnapshotEndpoint (par exemple, https://snapshot.monitor.azure.com)

Schéma de point de terminaison

<prefix>.<suffix>

• Préfixe : Définit un service.
• Suffixe : Définit le nom de domaine commun.

Suffixes valides

• applicationinsights.azure.cn
• applicationinsights.us

Pour plus d’informations, consultez Régions qui exigent une modification du point de terminaison.

Préfixes valides

• Ingestion de données de télémétrie : dc
• Métriques temps réel : live
• Profiler: profiler
• Capture instantanée : snapshot

La chaîne de connexion constitue-t-elle un secret ?

La chaîne de connexion contient une clé ikey, un identificateur unique utilisé par le service d’ingestion pour associer la télémétrie à une ressource Application Insights spécifique. Ces identificateurs uniques ikey ne sont pas des jetons de sécurité ni des clés de sécurité. Si vous souhaitez protéger votre ressource IA contre une mauvaise utilisation, le point de terminaison d’ingestion fournit des options d’ingestion de télémétrie authentifiées basées sur Microsoft Entra ID.

Remarque

Le kit SDK JavaScript Application Insights exige que la chaîne de connexion soit transmise pendant l’initialisation et la configuration. Elle est visible en texte brut dans les navigateurs clients. Il n’existe aucun moyen simple d’utiliser l’authentification basée sur Microsoft Entra ID pour la télémétrie du navigateur. Nous vous recommandons de créer une ressource Application Insights distincte pour la télémétrie du navigateur si vous devez sécuriser les données de télémétrie du service.

Exemples de chaînes de connexion courantes

Voici quelques exemples de chaînes de connexion.

Chaîne de connexion avec suffixe de point de terminaison

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

Dans cet exemple, la chaîne de connexion spécifie le suffixe du point de terminaison et le SDK construit des points de terminaison de service :

• Le schéma d’autorisation est défini par défaut sur « ikey »
• Clé d’instrumentation : 00000000-0000-0000-0000-000000000000
• Les URI de services régionaux se basent sur le suffixe du point de terminaison fourni :
  • Ingestion : https://dc.ai.contoso.com
  • Métriques temps réel : https://live.ai.contoso.com
  • Profiler : https://profiler.ai.contoso.com
  • Débogueur : https://snapshot.ai.contoso.com

Chaîne de connexion avec des substitutions de points de terminaison explicites

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

Dans cet exemple, la chaîne de connexion spécifie des substitutions explicites pour chaque service. Le SDK utilise les points de terminaison exacts fournis sans modification :

• Le schéma d’autorisation est défini par défaut sur « ikey »
• Clé d’instrumentation : 00000000-0000-0000-0000-000000000000
• Les URI de services régionaux se basent sur les valeurs de remplacement explicites :
  • Ingestion : https://custom.com:111/
  • Métriques temps réel : https://custom.com:222/
  • Profiler : https://custom.com:333/
  • Débogueur : https://custom.com:444/

Chaîne de connexion avec région explicite

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

Dans cet exemple, la chaîne de connexion spécifie la région USA Centre Sud :

• Le schéma d’autorisation est défini par défaut sur « ikey »
• Clé d’instrumentation : 00000000-0000-0000-0000-000000000000
• Les URI de services régionaux se basent sur les valeurs de remplacement explicites :
  • Ingestion : https://southcentralus.in.applicationinsights.azure.com/

Exécutez la commande suivante dans Azure CLI pour obtenir la liste des régions disponibles :

az account list-locations -o table

Définition d’une chaîne de connexion

Les chaînes de connexion sont prises en charge dans les versions suivantes du kit SDK :

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

Il est possible de définir une chaîne de connexion dans du code, ou à l’aide d’une variable d’environnement ou d’un fichier de configuration.

Variable d’environnement

Chaîne de connexion : APPLICATIONINSIGHTS_CONNECTION_STRING

Exemples de code

.NET 5.0+

1. Définissez la chaîne de connexion dans le fichier 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. Récupérez la chaîne de connexion dans Program.cs lors de l’enregistrement du service ApplicationInsightsTelemetry :

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

.NET Framework

Définissez la propriété TelemetryConfiguration.ConnectionString ou ApplicationInsightsServiceOptions.ConnectionString.

Définissez explicitement la chaîne de connexion dans le code :

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

Définissez la chaîne de connexion à l’aide d’un fichier de configuration :

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

Vous pouvez définir la chaîne de connexion de votre fichier de configuration applicationinsights.json :

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

Pour plus d’informations, consultez Configuration de la chaîne de connexion.

JavaScript

JavaScript ne prend pas en charge les variables d’environnement. Deux options s'offrent à vous :

• Pour utiliser le script de chargement du kit de développement logiciel (SDK) JavaScript (web), consultez Script de chargement du kit de développement logiciel (SDK) JavaScript (web).
• Configuration manuelle :

  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

Nous recommandons aux utilisateurs de définir la variable d’environnement.

Pour définir explicitement la chaîne de connexion :

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

Forum aux questions

Cette section fournit des réponses aux questions fréquentes.

Les nouvelles régions Azure exigent-elles l’utilisation de chaînes de connexion ?

Les nouvelles régions Azure exigent l’utilisation de chaînes de connexion au lieu de clés d’instrumentation. Une chaîne de connexion identifie la ressource que vous voulez associer à vos données de télémétrie. Elle vous permet également de modifier les points de terminaison que votre ressource utilisera comme destination pour votre télémétrie. Copiez la chaîne de connexion et ajoutez-la au code de votre application ou à une variable d’environnement.

Dois-je utiliser des chaînes de connexion ou des clés d’instrumentation ?

Nous vous recommandons d’utiliser des chaînes de connexion plutôt que des clés d’instrumentation.

Étapes suivantes

Prise en main lors de l’exécution avec :

• Applications hébergées par IIS sur une machine virtuelle Azure et Azure Virtual Machine Scale Sets
• Serveur IIS
• Fonctionnalité Web Apps d’Azure App Service

Prise en main pendant le développement avec :

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