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

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

Ponto final

O ponto de extremidade da API REST para a API de ingestão de logs pode ser um ponto de extremidade de coleta de dados (DCE) ou o ponto de extremidade de ingestão de logs 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 no modo de 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ó é necessário quando você está se conectando a um espaço de trabalho do Log Analytics usando um link privado ou se o DCR não incluir o ponto de extremidade de ingestão de logs. Este pode ser o caso se você estiver usando um DCR mais antigo ou se você criou o DCR sem o "kind": "Direct" parâmetro. Consulte Regra de coleta de dados (DCR) abaixo para obter mais detalhes.

Nota

A logsIngestion propriedade 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 qualquer DCR existente com DCEs existentes. Se você quiser mover para um ponto de extremidade DCR, então você deve criar um novo 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 recolha de dados (DCR)

Quando você cria uma tabela personalizada em um espaço de trabalho 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, deverá criar o DCR manualmente. Comece com o exemplo de DCR abaixo, substituindo valores para os seguintes parâmetros no modelo. 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 espaço de trabalho do Log Analytics e ao DCE, se você estiver usando um.
dataCollectionEndpointId ID do recurso do seu DCE. Remova esse parâmetro se estiver usando o ponto de ingestão DCR.
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 de destino.
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><. 
{
    "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 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

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

O URI usa o seguinte formato.

{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

O DCR Immutable ID é gerado para o DCR quando ele é criado. Você pode recuperá-lo na página Visão geral do DCR no portal do Azure.

Captura de ecrã de uma regra de recolha de dados que mostra o ID imutável.

Stream Name refere-se ao fluxo no DCR que deve manipular os dados personalizados.

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