Cadeias de ligação

Este artigo mostra como usar cadeias de conexão.

Descrição geral

Nota

A documentação a seguir depende da API clássica do Application Insights. O plano de longo prazo para o Application Insights é coletar dados usando OpenTelemetry. Para obter mais informações, consulte Habilitar o Azure Monitor OpenTelemetry 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 de prefixo para cada serviço ou produto do Application Insights.

Nota

A 31 de março de 2025, o suporte da ingestão de chaves de instrumentação terminará. A ingestão de chaves de instrumentação continuará a funcionar, mas não forneceremos mais atualizações ou suporte para o recurso. Transição para cadeias de conexão para aproveitar os novos recursos.

Descrição geral do cenário

Cenários mais afetados por esta 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 pedia que você adicionasse pontos de extremidade de serviço individuais à sua configuração. Para obter mais informações, consulte Posso monitorar um servidor Web de intranet?. As cadeias de conexão oferecem uma alternativa melhor, reduzindo esse esforço a uma única configuração. Um prefixo simples, alteração de sufixo, permite o preenchimento automático e o redirecionamento de todos os pontos finais para os serviços certos.

• Ambientes de nuvem soberana ou híbrida:

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

Começar agora

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

Encontrar a sua cadeia de ligaçã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 máximo suportado de 4.096 caracteres.

Pares chave-valor

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

Sintaxe

• InstrumentationKey (por exemplo, 00000000-0000-0000-0000-00000000000000). InstrumentationKey é um campo obrigatório .
• Authorization (por exemplo, ikey). Essa configuração é opcional porque hoje só suportamos a autorização do ikey.
• EndpointSuffix (por exemplo, applicationinsights.azure.cn). A configuração do sufixo de ponto de extremidade informa ao SDK a qual nuvem do Azure 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 de 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 Regiões que exigem modificação de ponto de extremidade.

Prefixos válidos

• Ingestão de telemetria: dc
• Métricas ao vivo: live
• Criador de perfil: profiler
• Instantâneo: 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 telemetria a um recurso específico do Application Insights. Esses identificadores exclusivos do ikey não são tokens de segurança ou chaves de segurança. Se você quiser 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 na ID do Microsoft Entra.

Nota

O SDK JavaScript do Application Insights requer que a cadeia de conexão seja passada durante a inicialização e a configuração. É visível em texto simples em navegadores de clientes. Não há uma maneira fácil de usar a autenticação baseada em ID do Microsoft Entra para telemetria do navegador. Recomendamos que você considere a criação de 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 de ponto de extremidade e o SDK constrói pontos de extremidade de serviço:

• O padrão do esquema de autorização é "ikey"
• Chave de instrumentação: 00000000-0000-0000-0000-0000000000000
• Os URIs de serviço regional são baseados no sufixo de ponto de extremidade fornecido:
  • Ingestão: https://dc.ai.contoso.com
  • Métricas ao vivo: https://live.ai.contoso.com
  • Criador de perfil: https://profiler.ai.contoso.com
  • Depurador: https://snapshot.ai.contoso.com

Cadeia de conexão com substituições explícitas de ponto de extremidade

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 usa os pontos de extremidade exatos fornecidos sem modificação:

• O padrão do esquema de autorização é "ikey"
• Chave de instrumentação: 00000000-0000-0000-0000-0000000000000
• Os URIs de serviço regional são baseados nos valores de substituição explícitos:
  • Ingestão: https://custom.com:111/
  • Métricas ao vivo: https://custom.com:222/
  • Criador de perfil: 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 padrão do esquema de autorização é "ikey"
• Chave de instrumentação: 00000000-0000-0000-0000-0000000000000
• Os URIs de serviço regional são baseados nos valores de substituição explícitos:
  • Ingestão: https://southcentralus.in.applicationinsights.azure.com/

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

az account list-locations -o table

Definir uma cadeia de conexão

As cadeias de conexão são suportadas 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

Você pode definir 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

Amostras de código

.NET 5.0+

1. Defina a cadeia de conexão no appsettings.json arquivo:

   {
     "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 ao Program.cs registrar o ApplicationInsightsTelemetry serviço:

   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

Você pode definir a cadeia de conexão no applicationinsights.json arquivo de configuração:

{
  "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

JavaScript não suporta o uso de variáveis de ambiente. Tem duas opções:

• Para usar o JavaScript (Web) SDK Loader Script, consulte JavaScript (Web) SDK Loader Script.
• Configuraçã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 mais frequentes

Esta secção fornece respostas a perguntas comuns.

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

As novas regiões do Azure exigem o uso de cadeias de conexão em vez de chaves de instrumentação. A cadeia de conexão identifica o recurso que você deseja associar aos seus dados de telemetria. Ele também permite que você modifique os pontos de extremidade que seu recurso usa como destino para sua 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 teclas de instrumentação?

Recomendamos que você use cadeias de conexão em vez de teclas de instrumentação.

Próximos passos

Introdução ao tempo de execução com:

• A VM do Azure e a Escala da Máquina Virtual do Azure Definem aplicativos hospedados no IIS
• Servidor do IIS
• Recurso Aplicativos Web do Serviço de Aplicativo do Azure

Introdução no momento de programação com:

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