Compartilhar via

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. 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. Ele envia os dados para um ponto de extremidade especificado pelo DCR ou para um DCE (ponto de extremidade de coleta de dados) se você estiver usando um link privado.

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

Ponto de extremidade

O ponto de extremidade da API REST para a API de Ingestão de Logs pode ser um DCE (ponto de extremidade de coleta de dados) ou ponto de extremidade de ingestão de logs do DCR.

O ponto de extremidade de ingestão de logs de DCR é gerado quando você cria um DCR para ingestão direta. Para recuperar esse ponto de extremidade, abra o DCR na exibição JSON no portal do Azure. Talvez seja necessário alterar a versão da API para a versão mais recente para que os pontos de extremidade sejam exibidos.

Captura de tela que mostra o ponto de extremidade de ingestão de log em um DCR.

Um DCE só será necessário quando você estiver se conectando a um workspace do Log Analytics usando um link privado ou se o DCR não incluir o ponto de extremidade de ingestão de logs. Esse pode ser o caso se você estiver usando um DCR mais antigo ou se tiver criado o DCR sem o parâmetro "kind": "Direct". Consulte a DCR (regra de coleta de dados) abaixo para obter mais detalhes.

Observação

A propriedade logsIngestion foi adicionada em 31 de março de 2024. Antes dessa data, um DCE era necessário para a API de ingestão de Logs. Os pontos de extremidade não podem ser adicionados a um DCR existente, mas você pode continuar usando DCRs existentes com DCEs existentes. Se você quiser migrar para um ponto de extremidade DCR, precisará criar um DCR para substituir o existente. Um DCR com pontos de extremidade também pode usar um DCE. Nesse caso, você pode escolher se deseja usar os pontos de extremidade DCE ou DCR para cada um dos clientes que usam o DCR.

Regra de coleta de dados (DCR)

Quando você cria uma tabela personalizada em um workspace do Log Analytics usando o portal do Azure, um DCR que pode ser usado com a API de ingestão de Logs é criado para você. Se você estiver enviando dados para uma tabela que já existe, então você deve criar a DCR manualmente. Comece com o DCR de exemplo abaixo, substituindo valores para os parâmetros a seguir no modelo. 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 precisará corresponder à região do workspace do Log Analytics e ao DCE, se você estiver usando um.
dataCollectionEndpointId ID do recurso do seu DCE. Remova esse parâmetro se você estiver usando o ponto de ingestão de DCR.
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 de destino.
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>. 
{
    "location": "eastus",
    "dataCollectionEndpointId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/my-resource-group/providers/Microsoft.Insights/dataCollectionEndpoints/dce-eastus",
    "kind": "Direct",
    "properties": {
        "streamDeclarations": {
            "Custom-MyTable": {
                "columns": [
                    {
                        "name": "Time",
                        "type": "datetime"
                    },
                    {
                        "name": "Computer",
                        "type": "string"
                    },
                    {
                        "name": "AdditionalContext",
                        "type": "string"
                    }
                ]
            }
        },
        "destinations": {
            "logAnalytics": [
                {
                    "workspaceResourceId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/cefingestion/providers/microsoft.operationalinsights/workspaces/my-workspace",
                    "name": "LogAnalyticsDest"
                }
            ]
        },
        "dataFlows": [
            {
                "streams": [
                    "Custom-MyTable"
                ],
                "destinations": [
                    "LogAnalyticsDest"
                ],
                "transformKql": "source",
                "outputStream": "Custom-MyTable_CL"
            }
        ]
    }
}

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

O URI inclui a região, o ponto de extremidade de ingestão de DCE ou DCR, a ID do DCR e o nome do fluxo. Ele também especifica a versão da API.

O URI usa o formato a seguir.

{Endpoint}/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

A DCR Immutable ID é gerada para a DCR quando ele é criado. Você pode recuperá-la na página Visão geral para DCR no portal do Azure.

Captura de tela de uma regra de coleta de dados mostrando a ID imutável.

Stream Name se refere ao Stream Name na DCR que deve lidar com os dados personalizados.

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