Cadeias de conexão

Este artigo mostra como usar cadeias de conexão.

Visão geral

Observação

A documentação a seguir depende da API clássica do Application Insights. O plano de longo prazo do Application Insights é coletar dados usando o OpenTelemetry. Para obter mais informações, confira Habilitar o OpenTelemetry do Azure Monitor para aplicativos .NET, Node.js, Python e Java.

As cadeias de conexão definem para onde enviar dados de telemetria.

Os pares chave-valor fornecem uma maneira fácil para os usuários definirem uma combinação de sufixo e prefixo para cada serviço ou produto do Application Insights.

Observação

Em 31 de março de 31, 2025, o suporte à ingestão de chave de instrumentação será encerrado. A ingestão de chave de instrumentação continuará funcionando, mas não forneceremos mais atualizações ou suporte para o recurso. Transição para cadeias de conexão para aproveitar as novas funcionalidades.

Visão geral do cenário

Cenários mais afetados por essa alteração:

• Exceções de firewall ou redirecionamentos de proxy:

  Nos casos em que o monitoramento do servidor Web da intranet é necessário, nossa solução anterior solicitou que você adicionasse pontos de extremidade de serviço individuais à sua configuração. Para mais informações, confira Posso monitorar um servidor Web da intranet?. As cadeias de conexão oferecem uma alternativa melhor, reduzindo esse esforço para uma única configuração. Um aditamento simples de prefixo ou sufixo permite o preenchimento automático e o redirecionamento de todos os pontos de extremidade para os serviços corretos.

• Ambientes de nuvem híbrida ou soberana:

  Os usuários podem enviar dados para uma região do Azure Governamental definida. Usando as cadeias de conexão, defina configurações de ponto de extremidade para seus servidores de intranet ou configurações de nuvem híbrida.

Introdução

Examine as seções a seguir para começar.

Encontrar sua cadeia de conexão

Sua cadeia de conexão aparece na seção Visão geral do recurso do Application Insights.

Esquema

Os elementos do esquema são explicados nas seções a seguir.

Comprimento máximo

A conexão tem um comprimento com suporte máximo de 4.096 caracteres.

Pares de chave-valor

Uma cadeia de conexão consiste em uma lista de configurações representadas como pares chave-valor separados por um ponto e vírgula: key1=value1;key2=value2;key3=value3

Sintaxe

• InstrumentationKey(por exemplo, 00000000-0000-0000-0000-000000000000). InstrumentationKey é um campo exigido.
• Authorization (por exemplo, ikey). Essa configuração é opcional porque hoje só damos suporte à autorização ikey.
• EndpointSuffix (por exemplo, applicationinsights.azure.cn). A definição do sufixo do ponto de extremidade informa ao SDK a qual nuvem do Azure deve se conectar. O SDK monta o restante do ponto de extremidade para serviços individuais.
• Pontos de extremidade explícitos. Qualquer serviço pode ser explicitamente substituído na cadeia de conexão:
  • IngestionEndpoint (por exemplo, https://dc.applicationinsights.azure.com)
  • LiveEndpoint (por exemplo, https://live.applicationinsights.azure.com)
  • ProfilerEndpoint (por exemplo, https://profiler.monitor.azure.com)
  • SnapshotEndpoint (por exemplo, https://snapshot.monitor.azure.com)

Esquema do ponto de extremidade

<prefix>.<suffix>

• Prefixo: define um serviço.
• Sufixo: define o nome de domínio comum.

Sufixos válidos

• applicationinsights.azure.cn
• applicationinsights.us

Para obter mais informações, consulte as Regiões que exigem modificação de ponto de extremidade.

Prefixos válidos

• Ingestão de telemetria: dc
• Live Metrics: live
• Profiler: profiler
• Snapshot: snapshot

A cadeia de conexão é um segredo?

A cadeia de conexão contém um iKey, que é um identificador exclusivo usado pelo serviço de ingestão para associar a telemetria a um recurso específico do Application Insights. Esses identificadores exclusivos de ikey não são tokens de segurança ou chaves de segurança. Se deseja proteger seu recurso de IA contra uso indevido, o ponto de extremidade de ingestão fornece opções de ingestão de telemetria autenticada com base no Microsoft Entra ID.

Observação

O SDK do JavaScript do Application Insights requer que a cadeia de conexão seja passada durante a inicialização e a configuração. Ele é exibido em texto sem formatação nos navegadores do cliente. Não há uma maneira fácil de usar a autenticação baseada no Microsoft Entra ID para telemetria do navegador. Recomendamos que você considere criar um recurso separado do Application Insights para telemetria do navegador se precisar proteger a telemetria de serviço.

Exemplos de cadeia de conexão

Aqui estão alguns exemplos de cadeias de conexão.

Cadeia de conexão com um sufixo de ponto de extremidade

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

Neste exemplo, a cadeia de conexão especifica o sufixo do ponto de extremidade e o SDK constrói os pontos de extremidade do serviço:

• O esquema de autorização assume como padrão "ikey"
• Chave de instrumentação: 00000000-0000-0000-0000-000000000000
• Os URIs de serviço regional se baseiam no sufixo de ponto de extremidade fornecido:
  • Ingestão: https://dc.ai.contoso.com
  • Live Metrics: https://live.ai.contoso.com
  • Profiler: https://profiler.ai.contoso.com
  • Depurador: https://snapshot.ai.contoso.com

Cadeia de conexão com sobreposição de pontos de extremidade explícitos

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

Neste exemplo, a cadeia de conexão especifica substituições explícitas para cada serviço. O SDK utiliza os pontos de extremidade exatos fornecidos sem modificações:

• O esquema de autorização assume como padrão "ikey"
• Chave de instrumentação: 00000000-0000-0000-0000-000000000000
• Os URIs de serviço regional baseiam-se nos valores de substituição explícitos:
  • Ingestão: https://custom.com:111/
  • Live Metrics: https://custom.com:222/
  • Profiler: https://custom.com:333/
  • Depurador: https://custom.com:444/

Cadeia de conexão com uma região explícita

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

Neste exemplo, a cadeia de conexão especifica a região Centro-Sul dos EUA:

• O esquema de autorização assume como padrão "ikey"
• Chave de instrumentação: 00000000-0000-0000-0000-000000000000
• Os URIs de serviço regional baseiam-se nos valores de substituição explícitos:
  • Ingestão: https://southcentralus.in.applicationinsights.azure.com/

Execute o comando a seguir na CLI do Azure para listar regiões disponíveis:

az account list-locations -o table

Definir uma cadeia de conexão

Há suporte para cadeias de conexão nas seguintes versões do SDK:

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

Defina uma cadeia de conexão no código ou usando uma variável de ambiente ou um arquivo de configuração.

Variável de ambiente

Cadeia de conexão: APPLICATIONINSIGHTS_CONNECTION_STRING

Exemplos de código

.NET 5.0+

1. Defina a cadeia de conexão no arquivo 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 a cadeia de conexão no Program.cs ao registrar o serviço ApplicationInsightsTelemetry:

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

.NET Framework

Defina a propriedade TelemetryConfiguration.ConnectionString ou ApplicationInsightsServiceOptions.ConnectionString.

Defina explicitamente a cadeia de conexão no 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/"
};

Defina a cadeia de conexão usando um arquivo de configuração:

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

Defina a cadeia de conexão no arquivo de configuração applicationinsights.json:

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

Para obter mais informações, consulte Configuração da cadeia de conexão.

JavaScript

O JavaScript não dá suporte ao uso de variáveis de ambiente. Você tem duas opções:

• Para usar o Script do Carregador de SDK (Web) JavaScript, confira Script do Carregador de SDK (Web) JavaScript.
• Instalação 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

Recomendamos que os usuários definam a variável de ambiente.

Para definir explicitamente a cadeia de conexão:

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

Perguntas frequentes

Esta seção fornece respostas para perguntas comuns.

As novas regiões do Azure exigem o uso de cadeias de conexão?

Novas regiões do Azure exigem o uso de cadeias de conexão em vez de chaves de instrumentação. Uma cadeia de conexão identifica o recurso com o qual você deseja associar os dados telemétricos. Ela também permite modificar os pontos de extremidade que o recurso usa como um destino para a telemetria. Copie a cadeia de conexão e adicione-a ao código do seu aplicativo ou a uma variável de ambiente.

Devo usar cadeias de conexão ou chaves de instrumentação?

Recomendamos usar cadeias de conexão em vez de chaves de instrumentação.

Próximas etapas

Introdução ao runtime com:

• Aplicativos hospedados no IIS na VM do Azure e nos Conjuntos de Dimensionamento de Máquinas Virtuais do Microsoft Azure
• Servidor IIS
• Recurso de Aplicativos Web do Serviço de Aplicativo do Azure

Introdução ao tempo de desenvolvimento com:

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