API de ingestão de logs no Azure Monitor

  • Artigo

A API de Ingestão de Logs no Azure Monitor permite enviar dados para um espaço de trabalho do Log Analytics usando uma chamada de API REST ou bibliotecas de cliente. A API permite que você envie dados para tabelas do Azure com suporte ou para tabelas personalizadas que você cria. Você também pode estender o esquema de tabelas do Azure com colunas personalizadas para aceitar dados adicionais.

Operação básica

Os dados podem ser enviados para a API de ingestão de logs de qualquer aplicativo que possa fazer uma chamada à API REST. Isso pode ser um aplicativo personalizado que você cria ou pode ser um aplicativo ou agente que entende como enviar dados para a API. O aplicativo envia dados para um ponto de extremidade de coleta de dados (DCE), que é um ponto de conexão exclusivo para sua assinatura do Azure. Ele especifica uma regra de coleta de dados (DCR) que inclui a tabela e o espaço de trabalho de destino e as credenciais de um registro de aplicativo com acesso ao DCR especificado.

Os dados enviados pelo seu aplicativo para a API devem ser formatados em JSON e corresponder à estrutura esperada pelo DCR. Ele não precisa necessariamente corresponder à estrutura da tabela de destino porque o DCR pode incluir uma transformação para converter os dados para corresponder à estrutura da tabela. Você pode modificar a tabela de destino e o espaço de trabalho modificando o DCR sem qualquer alteração na chamada da API ou nos dados de origem.

Diagrama que mostra uma visão geral da API de ingestão de logs.

Configuração

A tabela a seguir descreve cada componente no Azure que você deve configurar antes de usar a API de ingestão de logs.

Nota

Para obter um script do PowerShell que automatiza a configuração desses componentes, consulte Código de exemplo para enviar dados ao Azure Monitor usando a API de ingestão de logs.

Componente Function
Registo e segredo da aplicação O registro do aplicativo é usado para autenticar a chamada de API. Deve ser concedida permissão ao DCR descrito abaixo. A chamada de API inclui o ID do aplicativo (cliente) e o ID do diretório (locatário) do aplicativo e o valor de um segredo do aplicativo.

Consulte Criar uma entidade de serviço e aplicativo Microsoft Entra que possa acessar recursos e Criar um novo segredo de aplicativo.
Ponto de extremidade de coleta de dados (DCE) O DCE fornece um ponto de extremidade para o qual o aplicativo deve ser enviado. Um único DCE pode suportar vários DCRs, portanto, você pode usar um DCE existente se já tiver um na mesma região do espaço de trabalho do Log Analytics.

Consulte Criar um ponto de extremidade de coleta de dados.
Tabela no espaço de trabalho do Log Analytics A tabela no espaço de trabalho do Log Analytics deve existir antes que você possa enviar dados para ela. Você pode usar uma das tabelas do Azure com suporte ou criar uma tabela personalizada usando qualquer um dos métodos disponíveis. Se você usar o portal do Azure para criar a tabela, o DCR será criado para você, incluindo uma transformação, se necessário. Com qualquer outro método, você precisa criar o DCR manualmente, conforme descrito na próxima seção.

Consulte Criar uma tabela personalizada.
Regra de recolha de dados (DCR) O Azure Monitor usa a regra de coleta de dados (DCR) para entender a estrutura dos dados de entrada e o que fazer com eles. Se a estrutura da tabela e os dados de entrada não corresponderem, o DCR poderá incluir uma transformação para converter os dados de origem para corresponder à tabela de destino. Você também pode usar a transformação para filtrar dados de origem e executar quaisquer outros cálculos ou conversões.

Se você criar uma tabela personalizada usando o portal do Azure, o DCR e a transformação serão criados para você com base nos dados de exemplo fornecidos. Se você usar uma tabela existente ou criar uma tabela personalizada usando outro método, deverá criar manualmente o DCR usando detalhes na seção a seguir.

Depois que o DCR for criado, você deverá conceder acesso a ele para o aplicativo criado na primeira etapa. No menu Monitor no portal do Azure, selecione Regras de coleta de dados e, em seguida, o DCR que você criou. Selecione Controle de Acesso (IAM) para o DCR e, em seguida, selecione Adicionar atribuição de função para adicionar a função Editor de Métricas de Monitoramento .

Criar DCR manualmente

Se você estiver enviando dados para uma tabela que já existe, deverá criar o DCR manualmente. Comece com o DCR de exemplo para API de ingestão de logs e modifique os seguintes parâmetros no modelo. Em seguida, use qualquer um dos métodos descritos em Criar e editar regras de coleta de dados (DCRs) no Azure Monitor para criar o DCR.

Parâmetro Description
region Região para criar seu DCR. Isso deve corresponder à região do DCE e ao espaço de trabalho do Log Analytics.
dataCollectionEndpointId ID do recurso do seu DCE.
streamDeclarations Altere a lista de colunas para as colunas nos dados de entrada. Você não precisa alterar o nome do fluxo, pois isso só precisa corresponder ao streams nome em dataFlows.
workspaceResourceId ID do recurso do seu espaço de trabalho do Log Analytics. Você não precisa alterar o nome, pois isso só precisa corresponder ao destinations nome em dataFlows.
transformKql Consulta KQL a ser aplicada aos dados recebidos. Se o esquema dos dados de entrada corresponder ao esquema da tabela, então você pode usar source para a transformação que passará os dados de entrada inalterados. Caso contrário, use uma consulta que transformará os dados para corresponder ao esquema da tabela.
outputStream Nome da tabela a ser enviada pelos dados. Para uma tabela personalizada, adicione o prefixo Custom-table-name><. Para uma tabela interna, adicione o prefixo Microsoft-table-name><.

Bibliotecas de cliente

Além de fazer uma chamada à API REST, você pode usar as seguintes bibliotecas de cliente para enviar dados para a API de ingestão de logs. As bibliotecas requerem os mesmos componentes descritos em Configuração. Para obter exemplos usando cada uma dessas bibliotecas, consulte Código de exemplo para enviar dados para o Azure Monitor usando a API de ingestão de logs.

Chamada à API REST

Para enviar dados para o Azure Monitor com uma chamada de API REST, faça uma chamada POST por HTTP. Os detalhes necessários para esta chamada são descritos nesta seção.

URI do ponto de extremidade

O URI do ponto de extremidade usa o seguinte formato, onde o Data Collection Endpoint e DCR Immutable ID identificar o DCE e DCR. O ID imutável é gerado para o DCR quando ele é criado. Você pode recuperá-lo do modo de exibição JSON do DCR no portal do Azure. Stream Name refere-se ao fluxo no DCR que deve manipular os dados personalizados.

{Data Collection Endpoint URI}/dataCollectionRules/{DCR Immutable ID}/streams/{Stream Name}?api-version=2023-01-01

Por exemplo:

https://my-dce-5kyl.eastus-1.ingest.monitor.azure.com/dataCollectionRules/dcr-000a00a000a00000a000000aa000a0aa/streams/Custom-MyTable?api-version=2023-01-01

Cabeçalhos

A tabela a seguir descreve os cabeçalhos para sua chamada de API.

Cabeçalho Necessário? Description
Autorização Sim Token ao portador obtido através do fluxo de credenciais do cliente. Use o valor de audiência do token para sua nuvem:

Nuvem pública do Azure - https://monitor.azure.com
Microsoft Azure operado pela nuvem 21Vianet - https://monitor.azure.cn
Azure US Government cloud - https://monitor.azure.us
Tipo de Conteúdo Sim application/json
Codificação de conteúdo Não gzip
ID DO X-MS-CLIENT-REQUEST- Não GUID formatado em cadeia de caracteres. Esta é uma ID de solicitação que pode ser usada pela Microsoft para qualquer finalidade de solução de problemas.

Corpo

O corpo da chamada inclui os dados personalizados a serem enviados para o Azure Monitor. A forma dos dados deve ser uma matriz JSON com estrutura de item que corresponda ao formato esperado pelo fluxo no DCR. Se for necessário enviar um único item dentro da chamada de API, os dados devem ser enviados como uma matriz de item único.

Por exemplo:

[
{
    "TimeGenerated": "2023-11-14 15:10:02",
    "Column01": "Value01",
    "Column02": "Value02"
}
]

Certifique-se de que o corpo da solicitação está devidamente codificado em UTF-8 para evitar quaisquer problemas com a transmissão de dados.

Exemplo

Consulte Código de exemplo para enviar dados para o Azure Monitor usando a API de ingestão de logs para obter um exemplo da chamada de API usando o PowerShell.

Tabelas suportadas

Os dados enviados para a API de ingestão podem ser enviados para as seguintes tabelas:

Tabelas Description
Tabelas personalizadas Qualquer tabela personalizada que você crie em seu espaço de trabalho do Log Analytics. A tabela de destino deve existir antes que você possa enviar dados para ela. As tabelas personalizadas devem ter o sufixo _CL .
Tabelas do Azure As seguintes tabelas do Azure são suportadas atualmente. Outras tabelas podem ser adicionadas a esta lista à medida que o suporte para elas é implementado.

Nota

Os nomes das colunas devem começar com uma letra e podem consistir em até 45 caracteres alfanuméricos e sublinhados (_). _ResourceId, id, , _ResourceId, _SubscriptionId, TypeTenantId, , UniqueIde Title são nomes de colunas reservados. As colunas personalizadas adicionadas a uma tabela do Azure devem ter o sufixo _CF.

Limites e restrições

Para limites relacionados à API de ingestão de logs, consulte Limites de serviço do Azure Monitor.

Próximos passos