Cadenas de conexión

En este artículo se muestra cómo usar cadenas de conexión.

Información general

Nota:

La siguiente documentación se basa en la API clásica de Application Insights. El plan a largo plazo de Application Insights consiste en recopilar datos mediante OpenTelemetry. Para más información, consulte Habilitación de Azure Monitor OpenTelemetry para aplicaciones de .NET, Node.js, Python y Java.

Las cadenas de conexión definen dónde enviar datos de telemetría.

Los pares clave-valor proporcionan a los usuarios una manera fácil de definir una combinación de sufijo y prefijo para cada servicio o producto de Application Insights.

Nota

El 31 de marzo de 2025 finalizará la compatibilidad con la ingesta de claves de instrumentación. La ingesta de claves de instrumentación seguirá funcionando, pero la característica ya no recibirá actualizaciones ni soporte técnico. Transición a las cadenas de conexión para aprovechar las nuevas funcionalidades.

Información general de escenario

Escenarios más afectados por este cambio:

• Excepciones de firewall o redirecciones de proxy:

  En los casos en los que es necesario supervisar el servidor web de la intranet, nuestra solución anterior le solicitaba que agregara puntos de conexión de servicio individuales a la configuración. Para obtener más información, consulte ¿Puedo supervisar un servidor web de una intranet?. Las cadenas de conexión ofrecen una mejor alternativa, ya que reducen esta labor a una única configuración. Una corrección de sufijos y prefijos simple permite el rellenado y la redirección automáticos de todos los puntos de conexión a los servicios adecuados.

• Entornos de nube soberana o híbrida:

  Los usuarios pueden enviar datos a una región de Azure Government definida. El usa de las cadenas de conexión puede definir la configuración de punto de conexión de los servidores de la intranet o la configuración de la nube híbrida.

Introducción

Revise las siguientes secciones para comenzar.

Búsqueda de la cadena de conexión

La cadena de conexión aparece en la sección de información general del recurso de Application Insights.

Esquema

Los elementos de esquema se explican en las siguientes secciones.

Longitud máxima

La conexión tiene una longitud máxima admitida de 4,096 caracteres.

Pares de clave-valor

Una cadena de conexión consta de una lista de valores de configuración representados como pares de clave-valor separados por punto y coma: key1=value1;key2=value2;key3=value3

Sintaxis

• InstrumentationKey (por ejemplo, 00000000-0000-0000-0000-000000000000). InstrumentationKey es un campo obligatorio.
• Authorization (por ejemplo, ikey). Este valor es opcional porque actualmente no se admite la autorización mediante ikey.
• EndpointSuffix (por ejemplo, applicationinsights.azure.cn). Al establecer el sufijo del punto de conexión, se indicará al SDK a qué nube de Azure se conectará. El SDK ensamblará el resto del punto de conexión para los servicios individuales.
• Puntos de conexión explícitos. Cualquier servicio se puede invalidar explícitamente en la cadena de conexión:
  • IngestionEndpoint (por ejemplo, https://dc.applicationinsights.azure.com)
  • LiveEndpoint (por ejemplo, https://live.applicationinsights.azure.com)
  • ProfilerEndpoint (por ejemplo, https://profiler.monitor.azure.com)
  • SnapshotEndpoint (por ejemplo, https://snapshot.monitor.azure.com)

Esquema del punto de conexión

<prefix>.<suffix>

• Prefijo: define un servicio.
• Sufijo: define el nombre de dominio común.

Sufijos válidos

• applicationinsights.azure.cn
• applicationinsights.us

Para obtener más información, consulte Regiones que requieren modificación del punto de conexión.

Prefijos válidos

• Ingesta de telemetría: dc
• Live Metrics: live
• Profiler: profiler
• Instantánea: snapshot

¿La cadena de conexión es un secreto?

La cadena de conexión contiene una iKey, que es un identificador único que usa el servicio de ingesta para asociar la telemetría a un recurso específico de Application Insights. Estos identificadores únicos ikey no son tokens ni claves de seguridad. Si desea proteger su recurso de IA contra el uso indebido, el punto de conexión de ingesta proporciona opciones de ingesta de telemetría autenticadas basadas en Microsoft Entra ID.

Nota:

El SDK de JavaScript de Application Insights requiere que la cadena de conexión se pase durante la inicialización y configuración. Se puede ver en texto sin formato en exploradores cliente. No hay ninguna manera fácil de usar la autenticación basada en Microsoft Entra ID para la telemetría del explorador. Recomendamos que se considere la posibilidad de crear un recurso de Application Insights independiente para la telemetría del explorador si se necesita proteger la telemetría del servicio.

Ejemplos de cadena de conexión

A continuación, se incluyen algunos ejemplos de cadenas de conexión.

Cadena de conexión con sufijo de punto de conexión

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

En este ejemplo, la cadena de conexión especifica el sufijo del punto final y el SDK construye los puntos finales del servicio:

• El esquema de autorización tiene como valor predeterminado "ikey".
• Clave de instrumentación: 00000000-0000-0000-0000-000000000000
• Los identificadores URI de servicio regional se basan en el sufijo de punto de conexión proporcionado:
  • Ingesta: https://dc.ai.contoso.com
  • Live Metrics: https://live.ai.contoso.com
  • Profiler: https://profiler.ai.contoso.com
  • Depurador: https://snapshot.ai.contoso.com

Cadena de conexión con invalidaciones explícitas del punto de conexión

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

En este ejemplo, esta cadena de conexión especifica invalidaciones explícitas para cada servicio. El SDK usará los puntos de conexión exactos proporcionados sin modificaciones:

• El esquema de autorización tiene como valor predeterminado "ikey".
• Clave de instrumentación: 00000000-0000-0000-0000-000000000000
• Los identificadores URI de servicio regional se basan en los valores de invalidación explícitos:
  • Ingesta: https://custom.com:111/
  • Live Metrics: https://custom.com:222/
  • Profiler: https://custom.com:333/
  • Depurador: https://custom.com:444/

Cadena de conexión con una región explícita

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

En este ejemplo, la cadena de conexión especifica la región Centro y Sur de EE. UU:

• El esquema de autorización tiene como valor predeterminado "ikey".
• Clave de instrumentación: 00000000-0000-0000-0000-000000000000
• Los identificadores URI de servicio regional se basan en los valores de invalidación explícitos:
  • Ingesta: https://southcentralus.in.applicationinsights.azure.com/

Ejecute el siguiente comando en la CLI de Azure para enumerar las regiones disponibles:

az account list-locations -o table

Establezca una cadena de conexión

Se admiten cadenas de conexión en las siguientes versiones del SDK:

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

Puede establecer una cadena de conexión en el código o mediante una variable de entorno o un archivo de configuración.

Variable de entorno

Cadena de conexión: APPLICATIONINSIGHTS_CONNECTION_STRING

Ejemplos de código

.NET 5.0+

1. Establezca la cadena de conexión en el archivo 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. Recupere la clave de instrumentación en Program.cs al registrar el servicio ApplicationInsightsTelemetry:

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

.NET Framework

Establezca la propiedad TelemetryConfiguration.ConnectionString o la propiedad ApplicationInsightsServiceOptions.ConnectionString.

Establezca explícitamente la cadena de conexión en el código:

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

Establezca la cadena de conexión mediante un archivo de configuración:

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

Puede establecer la cadena de conexión en el archivo de configuración applicationinsights.json:

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

Para más información, consulte Configuración de cadenas de conexión.

JavaScript

JavaScript no admite el uso de variables de entorno. Tiene dos opciones:

• Para usar el Script del cargador del SDK de JavaScript (Web), consulte Script del cargador del SDK de JavaScript (Web).
• Instalación 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

Se recomienda que los usuarios establezcan la variable de entorno.

Para establecer explícitamente la cadena de conexión:

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

Preguntas más frecuentes

Esta sección proporciona respuestas a preguntas comunes.

¿Es necesario usar cadenas de conexión en las nuevas regiones de Azure?

Las nuevas regiones de Azure requieren el uso de cadenas de conexión en lugar de claves de instrumentación. Una cadena de conexión identifica el recurso al que quiere asociar los datos de telemetría. También permite modificar los puntos de conexión que usa el recurso como destino de la telemetría. Copie la cadena de conexión y agregarla al código de la aplicación o a una variable de entorno.

¿Debo usar cadenas de conexión o claves de instrumentación?

Se recomienda usar cadenas de conexión en lugar de claves de instrumentación.

Pasos siguientes

Comience en el tiempo de ejecución con:

• Aplicaciones hospedadas en IIS en máquina virtual de Azure y Virtual Machine Scale Sets
• Servidor IIS
• Característica Web Apps de Azure App Service

Comience en el tiempo de desarrollo con:

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