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 workspace do Log Analytics usando uma chamada à API REST ou bibliotecas de cliente. A API permite que você envie dados para tabelas do Azure com suporte ou para as tabelas personalizadas que você criar. 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 sabe 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 de destino e o espaço de trabalho e as credenciais de um registro de aplicativo com acesso à DCR especificada.

Os dados enviados pelo seu aplicativo à API devem ser formatados em JSON e corresponder à estrutura esperada pela DCR. Eles não precisam necessariamente corresponder à estrutura da tabela de destino, pois a DCR pode incluir uma transformação para converter os dados a fim de fazer uma correspondência à estrutura da tabela. Você pode modificar a tabela de destino e o workspace modificando a DCR sem qualquer alteração na chamada à API ou nos dados de origem.

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

Configuração

A seguinte tabela descreve cada componente no Azure que você deve configurar antes de poder usar a API de Ingestão de Logs.

Observação

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

Componente Função
Registro e segredo do aplicativo O registro do aplicativo é usado para autenticar a chamada à API. Ele deve receber permissão para o DCR descrito abaixo. A chamada à API inclui a ID (cliente) do aplicativo e a ID (locatário) do diretório do aplicativo e o Valor de um segredo de aplicativo.

Consulte Criar um aplicativo do Microsoft Entra e uma entidade de serviço que podem 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 será enviado. Um único DCE pode dar suporte a várias DCRs, portanto, você pode usar um DCE existente se já tiver um na mesma região do seu workspace do Log Analytics.

Consulte Criar um ponto de extremidade de coleta de dados.
Tabela no workspace do Log Analytics A tabela no workspace 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, a DCR será criado para você, incluindo uma transformação, se for necessário. Com qualquer outro método, você precisa criar a DCR manualmente, conforme descrito na próxima seção.

Consulte Criar uma tabela personalizada.
DCR (regra de coleta de dados) O Azure Monitor usa a Regra de coleta de dados (DCR) para reconhecer 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, a DCR poderá incluir uma transformação para converter os dados de origem para que correspondam à tabela de destino. Você também pode usar a transformação para filtrar os dados de origem e executar quaisquer outros cálculos ou conversões.

Se você criar uma tabela personalizada usando o portal do Azure, a DCR e a transformação serão criadas para você com base nos dados de amostra que você fornecer. Se você usar uma tabela existente ou criar uma tabela personalizada usando outro método, então você deverá criar manualmente a DCR usando os detalhes da seguinte seção.

Depois que a DCR for criada, você deverá conceder acesso a ela para o aplicativo que criou na primeira etapa. No menu Monitorar do portal do Azure, selecione Regras de Coleta de Dados e depois a DCR que você criou. Selecione Controle de Acesso (IAM) para a DCR e depois selecione Adicionar atribuição de função para adicionar a função Monitoramento de Publicador de Métricas.

Criar uma DCR manualmente

Se você estiver enviando dados para uma tabela que já existe, então você deve criar a DCR manualmente. Comece com a Amostra de DCR para a 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 a DCR.

Parâmetro Descrição
region Região para criar sua DCR. Isso deve corresponder à região do DCE e ao workspace do Log Analytics.
dataCollectionEndpointId ID do recurso do seu DCE.
streamDeclarations Altere a lista de colunas para as colunas em seus dados de entrada. Você não precisa alterar o nome do fluxo, pois ele só precisa corresponder ao nome streams em dataFlows.
workspaceResourceId ID do recurso do seu workspace do Log Analytics. Você não precisa alterar o nome, pois ele só precisa corresponder ao nome destinations em dataFlows.
transformKql Consulta KQL a ser aplicada aos dados de entrada. 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 que correspondam ao esquema da tabela.
outputStream Nome da tabela para enviar os dados. Para uma tabela personalizada, adicione o prefixo Custom-<table-name>. Para uma tabela integrada, adicione o prefixo Microsoft-<table-name>.

Bibliotecas de clientes

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

Chamada da API REST

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

URI do ponto de extremidade

O URI do ponto de extremidade usa o seguinte formato, em que Data Collection Endpoint e DCR Immutable ID identificam o DCE e a DCR. A ID imutável é gerada para a DCR quando for criada. Você pode recuperá-la a ID a partir de Exibição JSON da DCR no portal do Azure. Stream Name se refere ao Stream Name na DCR que deve lidar com 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 seguinte tabela descreve os cabeçalhos para sua chamada à API.

Cabeçalho Obrigatório? Descrição
Autorização Sim Token de portador obtido por meio 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
Nuvem Microsoft Azure operada pela 21Vianet - https://monitor.azure.cn
Nuvem Azure US Government - https://monitor.azure.us
Tipo de conteúdo Sim application/json
Codificação de conteúdo Não gzip
x-ms-client-request-id Não GUID formatado para cadeia de caracteres. Essa é uma ID da solicitação que pode ser usada pela Microsoft para fins de solução de problemas.

Corpo

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

Por exemplo:

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

Certifique-se que o corpo da solicitação esteja codificado corretamente em UTF-8 para evitar problemas com a transmissão de dados.

Exemplo

Consulte Exemplo de código para enviar dados ao Azure Monitor usando a API de ingestão de Logs para um exemplo de chamada à API usando PowerShell.

Tabelas com suporte

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

Tabelas Descrição
Tabelas personalizadas Qualquer tabela que você criar no seu workspace do Log Analytics. A tabela de destino deve existir para que você possa enviar dados a ela. As tabelas personalizadas devem ter o sufixo _CL.
Tabelas do Azure As seguintes tabelas do Azure têm suporte atualmente. Outras tabelas podem ser adicionadas a essa lista, à medida que o suporte a elas é implementado.

Observação

Os nomes de coluna devem começar com uma letra e podem consistir de até 45 caracteres alfanuméricos e sublinhados (_). _ResourceId, id, _ResourceId, _SubscriptionId, TenantId, Type, UniqueId e Title são nomes de coluna reservados. As colunas personalizadas que você adiciona a uma tabela do Azure devem ter o sufixo _CF.

Limitações e restrições

Para obter os limites relacionados à API de Ingestão de Logs, confira Limites de serviço do Azure Monitor.

Próximas etapas