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, consultez FAQ sur Azure Monitor. 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). La chaîne de connexion constitue 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 de point de terminaison indique au kit SDK sur 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. Elle n’est pas considérée comme un jeton de sécurité ni une clé. Si vous voulez protéger votre ressource IA contre les mauvaises utilisations, le point de terminaison d’ingestion fournit des options d’ingestion de télémétrie authentifiées basées sur Azure Active Directory (Azure AD).

Notes

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 Azure AD 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 de point de terminaison. Le kit SDK construit les 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 kit SDK utilise tels quels les points de terminaison fournis sans apporter de 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 clé d’instrumentation dans le fichier appsettings.json :

   {
     "ApplicationInsights": {
       "InstrumentationKey" : "InstrumentationKey=00000000-0000-0000-0000-000000000000;"
       }
   }
   

2. Récupérez la clé d’instrumentation dans Program.cs lors de l’inscription du service ApplicationInsightsTelemetry :

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

Notes

Lorsque vous déployez des applications vers Azure dans des scénarios de production, envisagez de placer des clés d’instrumentation ou d’autres secrets de configuration dans des emplacements sécurisés tels que des paramètres de configuration App Service ou Azure Key Vault. Évitez d’inclure des secrets dans le code de votre application ou de les archiver dans le contrôle de code source où ils peuvent être exposés ou utilisés de manière incorrecte. L’exemple de code précédent fonctionne également si la clé d’instrumentation est stockée dans les paramètre de configuration du service App Service. Si vous souhaitez en savoir plus sur la configuration des paramètres App Service.

.NET Framework

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

Définissez explicitement la clé d’instrumentation dans le code :

var configuration = new TelemetryConfiguration
{
    ConnectionString = "InstrumentationKey=00000000-0000-0000-0000-000000000000;"
};

Définissez la clé d’instrumentation à 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</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"
}

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 du loader SDK, consultez Script du loader SDK.
• 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;");
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'), sampler=ProbabilitySampler(1.0))

É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