Tutorial: Enviar dados para o Azure Monitor usando a API de ingestão de logs (modelos do Gerenciador de Recursos)

  • Artigo

A API de Ingestão de Logs no Azure Monitor permite enviar dados personalizados para um espaço de trabalho do Log Analytics. Este tutorial usa modelos do Azure Resource Manager (modelos ARM) para percorrer a configuração dos componentes necessários para dar suporte à API e, em seguida, fornece um aplicativo de exemplo usando a API REST e bibliotecas de cliente para .NET, Go, Java, JavaScript e Python.

Nota

Este tutorial usa modelos ARM para configurar os componentes necessários para dar suporte à API de ingestão de Logs. Consulte Tutorial: Enviar dados para a API de ingestão de logs do Azure Monitor com logs (portal do Azure) para obter um tutorial semelhante que usa a interface do usuário do portal do Azure para configurar esses componentes.

As etapas necessárias para configurar a API de ingestão de logs são as seguintes:

  1. Crie um aplicativo Microsoft Entra para autenticar na API.
  2. Crie um ponto de extremidade de coleta de dados (DCE) para receber dados.
  3. Crie uma tabela personalizada em um espaço de trabalho do Log Analytics. Esta é a tabela para a qual você enviará dados.
  4. Crie uma regra de coleta de dados (DCR) para direcionar os dados para a tabela de destino.
  5. Dê ao aplicativo Microsoft Entra acesso ao DCR.
  6. Consulte Código de exemplo para enviar dados para o Azure Monitor usando a API de ingestão de logs para obter o código de exemplo para enviar dados usando a API de ingestão de logs.

Pré-requisitos

Para concluir este tutorial, precisa de:

Coletar detalhes do espaço de trabalho

Comece por recolher as informações de que necessitará a partir da sua área de trabalho.

Vá para seu espaço de trabalho no menu de espaços de trabalho do Log Analytics no portal do Azure. Na página Propriedades, copie a ID do Recurso e salve-a para uso posterior.

Captura de tela que mostra a ID do recurso do espaço de trabalho.

Criar aplicativo Microsoft Entra

Comece registrando um aplicativo Microsoft Entra para autenticar na API. Qualquer esquema de autenticação do Resource Manager é suportado, mas este tutorial segue o esquema de Fluxo de Concessão de Credenciais do Cliente.

  1. No menu ID do Microsoft Entra no portal do Azure, selecione Registos de>aplicações Novo registo.

    Captura de ecrã que mostra o ecrã de registo da aplicação.

  2. Dê um nome ao aplicativo e altere o escopo da locação se o padrão não for apropriado para seu ambiente. Um URI de redirecionamento não é necessário.

    Captura de ecrã que mostra os detalhes da aplicação.

  3. Após o registo, poderá visualizar os detalhes da candidatura. Observe a ID do aplicativo (cliente) e a ID do diretório (locatário). Você precisará desses valores mais tarde no processo.

    Captura de ecrã que mostra o ID da aplicação.

  4. Gere um segredo de cliente de aplicativo, que é semelhante à criação de uma senha para usar com um nome de usuário. Selecione Certificados & segredos Novo segredo do>cliente. Dê ao segredo um nome para identificar sua finalidade e selecione uma duração Expira . A opção 12 meses é selecionada aqui. Para uma implementação de produção, você deve seguir as práticas recomendadas para um procedimento de rotação secreta ou usar um modo de autenticação mais seguro, como um certificado.

    Captura de tela que mostra o segredo do novo aplicativo.

  5. Selecione Adicionar para salvar o segredo e, em seguida, anote o Valor. Certifique-se de registrar esse valor porque não é possível recuperá-lo depois de sair desta página. Use as mesmas medidas de segurança que você usaria para proteger uma senha, pois ela é o equivalente funcional.

    Captura de tela que mostra o valor secreto para o novo aplicativo.

Criar ponto de extremidade de coleta de dados

Um DCE é necessário para aceitar os dados que estão sendo enviados para o Azure Monitor. Depois de configurar o DCE e vinculá-lo a um DCR, você pode enviar dados por HTTP do seu aplicativo. O DCE deve estar localizado na mesma região que o DCR e o espaço de trabalho do Log Analytics para onde os dados serão enviados.

  1. Na caixa de pesquisa do portal do Azure, insira modelo e selecione Implantar um modelo personalizado.

    Captura de tela que mostra como implantar um modelo personalizado.

  2. Selecione Crie o seu próprio modelo no editor.

    Captura de tela que mostra como criar um modelo no editor.

  3. Cole o seguinte modelo ARM no editor e selecione Salvar. Não é necessário modificar esse modelo porque você fornecerá valores para seus parâmetros.

    Captura de tela que mostra como editar um modelo ARM. 

    {
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "dataCollectionEndpointName": {
            "type": "string",
            "metadata": {
                "description": "Specifies the name of the Data Collection Endpoint to create."
            }
        },
        "location": {
            "type": "string",
            "defaultValue": "westus2",
            "metadata": {
                "description": "Specifies the location for the Data Collection Endpoint."
            }
        }
    },
    "resources": [
        {
            "type": "Microsoft.Insights/dataCollectionEndpoints",
            "name": "[parameters('dataCollectionEndpointName')]",
            "location": "[parameters('location')]",
            "apiVersion": "2021-04-01",
            "properties": {
                "networkAcls": {
                "publicNetworkAccess": "Enabled"
                }
            }
        }
    ],
    "outputs": {
        "dataCollectionEndpointId": {
            "type": "string",
            "value": "[resourceId('Microsoft.Insights/dataCollectionEndpoints', parameters('dataCollectionEndpointName'))]"
        }
    }
}

  4. Na tela Implantação personalizada, especifique um grupo Assinatura e Recursos para armazenar o DCR e forneça valores como um Nome para o DCE. O local deve ser o mesmo local do espaço de trabalho. A Região já estará povoada e será utilizada para a localização do DCE.

    Captura de tela para editar valores de implantação personalizados.

  5. Selecione Rever + criar e, em seguida, selecione Criar depois de rever os detalhes.

  6. Selecione Visualização JSON para exibir outros detalhes do DCE. Copie o ID do recurso e o ponto de extremidade logsIngestion, que você precisará em uma etapa posterior.

    Captura de tela que mostra o ID do recurso DCE.

Criar nova tabela no espaço de trabalho do Log Analytics

A tabela personalizada deve ser criada antes que você possa enviar dados para ela. A tabela para este tutorial incluirá cinco colunas mostradas no esquema abaixo. As namepropriedades , type, e são description obrigatórias para cada coluna. As propriedades isHidden e isDefaultDisplay ambos o padrão para false se não explicitamente especificado. Os tipos de dados possíveis são string, int, long, real, boolean, dateTime, guide dynamic.

Nota

Este tutorial usa o PowerShell do Azure Cloud Shell para fazer chamadas de API REST usando a API de Tabelas do Azure Monitor. Você pode usar qualquer outro método válido para fazer essas chamadas.

Importante

As tabelas personalizadas devem usar um sufixo de _CL.

  1. Selecione o botão Cloud Shell no portal do Azure e verifique se o ambiente está definido como PowerShell.

    Captura de tela que mostra a abertura do Cloud Shell.

  2. Copie o seguinte código do PowerShell e substitua as variáveis no parâmetro Path pelos valores apropriados para seu espaço de trabalho no Invoke-AzRestMethod comando. Cole no prompt do Cloud Shell para executá-lo.

    $tableParams = @'
{
    "properties": {
        "schema": {
            "name": "MyTable_CL",
            "columns": [
                {
                    "name": "TimeGenerated",
                    "type": "datetime",
                    "description": "The time at which the data was generated"
                },
               {
                    "name": "Computer",
                    "type": "string",
                    "description": "The computer that generated the data"
                },
                {
                    "name": "AdditionalContext",
                    "type": "dynamic",
                    "description": "Additional message properties"
                },
                {
                    "name": "CounterName",
                    "type": "string",
                    "description": "Name of the counter"
                },
                {
                    "name": "CounterValue",
                    "type": "real",
                    "description": "Value collected for the counter"
                }
            ]
        }
    }
}
'@

Invoke-AzRestMethod -Path "/subscriptions/{subscription}/resourcegroups/{resourcegroup}/providers/microsoft.operationalinsights/workspaces/{workspace}/tables/MyTable_CL?api-version=2022-10-01" -Method PUT -payload $tableParams

Criar regra de coleta de dados

O DCR define como os dados serão tratados uma vez recebidos. O que está incluído:

  • Esquema de dados que estão sendo enviados para o ponto de extremidade
  • Transformação que será aplicada aos dados antes de serem enviados para o espaço de trabalho
  • Espaço de trabalho de destino e tabela para a qual os dados transformados serão enviados

  1. Na caixa de pesquisa do portal do Azure, insira modelo e selecione Implantar um modelo personalizado.

    Captura de tela que mostra como implantar um modelo personalizado.

  2. Selecione Crie o seu próprio modelo no editor.

    Captura de tela que mostra como criar um modelo no editor.

  3. Cole o seguinte modelo ARM no editor e selecione Salvar.

    Captura de tela que mostra como editar um modelo ARM.

    Observe os seguintes detalhes no DCR definido neste modelo:

    • dataCollectionEndpointId: ID do recurso do ponto de extremidade de coleta de dados.
    • streamDeclarations: Definições de coluna dos dados recebidos.
    • destinations: Espaço de trabalho de destino.
    • dataFlows: Faz a correspondência entre o fluxo e o espaço de trabalho de destino e especifica a consulta de transformação e a tabela de destino. A saída da consulta de destino é o que será enviado para a tabela de destino.
    {
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "dataCollectionRuleName": {
            "type": "string",
            "metadata": {
                "description": "Specifies the name of the Data Collection Rule to create."
            }
        },
        "location": {
            "type": "string",
            "metadata": {
                "description": "Specifies the location in which to create the Data Collection Rule."
            }
        },
        "workspaceResourceId": {
            "type": "string",
            "metadata": {
                "description": "Specifies the Azure resource ID of the Log Analytics workspace to use."
            }
        },
        "endpointResourceId": {
            "type": "string",
            "metadata": {
                "description": "Specifies the Azure resource ID of the Data Collection Endpoint to use."
            }
        }
    },
    "resources": [
        {
            "type": "Microsoft.Insights/dataCollectionRules",
            "name": "[parameters('dataCollectionRuleName')]",
            "location": "[parameters('location')]",
            "apiVersion": "2021-09-01-preview",
            "properties": {
                "dataCollectionEndpointId": "[parameters('endpointResourceId')]",
                "streamDeclarations": {
                    "Custom-MyTableRawData": {
                        "columns": [
                            {
                                "name": "Time",
                                "type": "datetime"
                            },
                            {
                                "name": "Computer",
                                "type": "string"
                            },
                            {
                                "name": "AdditionalContext",
                                "type": "string"
                            },
                            {
                                "name": "CounterName",
                                "type": "string"
                            },
                            {
                                "name": "CounterValue",
                                "type": "real"
                            }
                        ]
                    }
                },
                "destinations": {
                    "logAnalytics": [
                        {
                            "workspaceResourceId": "[parameters('workspaceResourceId')]",
                            "name": "myworkspace"
                        }
                    ]
                },
                "dataFlows": [
                    {
                        "streams": [
                            "Custom-MyTableRawData"
                        ],
                        "destinations": [
                            "myworkspace"
                        ],
                        "transformKql": "source | extend jsonContext = parse_json(AdditionalContext) | project TimeGenerated = Time, Computer, AdditionalContext = jsonContext, CounterName=tostring(jsonContext.CounterName), CounterValue=toreal(jsonContext.CounterValue)",
                        "outputStream": "Custom-MyTable_CL"
                    }
                ]
            }
        }
    ],
    "outputs": {
        "dataCollectionRuleId": {
            "type": "string",
            "value": "[resourceId('Microsoft.Insights/dataCollectionRules', parameters('dataCollectionRuleName'))]"
        }
    }
}

  4. Na tela Implantação personalizada, especifique um grupo Assinatura e Recursos para armazenar o DCR. Em seguida, forneça os valores definidos no modelo. Os valores incluem um Nome para o DCR e a ID do Recurso de Espaço de Trabalho que você coletou em uma etapa anterior. O local deve ser o mesmo local do espaço de trabalho. A Região já estará povoada e será utilizada para a localização do DCR.

    Captura de tela que mostra como editar valores de implantação personalizados.

  5. Selecione Rever + criar e, em seguida, selecione Criar depois de rever os detalhes.

  6. Quando a implantação estiver concluída, expanda a caixa Detalhes da implantação e selecione seu DCR para exibir seus detalhes. Selecione Visualização JSON.

    Captura de tela que mostra detalhes do DCR.

  7. Copie a ID imutável para o DCR. Você o usará em uma etapa posterior quando enviar dados de exemplo usando a API.

    Captura de tela que mostra o modo de exibição JSON DCR.

    Nota

    Todas as propriedades do DCR, como a transformação, podem não ser exibidas no portal do Azure, mesmo que o DCR tenha sido criado com êxito com essas propriedades.

Atribuir permissões a um DCR

Depois que o DCR for criado, o aplicativo precisa receber permissão para ele. A permissão permitirá que qualquer aplicativo usando o ID do aplicativo correto e a chave do aplicativo envie dados para o novo DCE e DCR.

  1. No DCR no portal do Azure, selecione Controle de Acesso (IAM)>Adicionar atribuição de função.

    Captura de tela que mostra a adição de uma atribuição de função personalizada ao DCR.

  2. Selecione Monitoring Metrics Publisher e selecione Next. Em vez disso, você pode criar uma ação personalizada com a Microsoft.Insights/Telemetry/Write ação de dados.

    Captura de tela que mostra a seleção de uma função para atribuição de função DCR.

  3. Selecione Usuário, grupo ou entidade de serviço para Atribuir acesso e escolha Selecionar membros. Selecione o aplicativo que você criou e escolha Selecionar.

    Captura de tela que mostra a seleção de membros para a atribuição de função DCR.

  4. Selecione Rever + atribuir e verifique os detalhes antes de guardar a atribuição de função.

    Captura de tela que mostra como salvar a atribuição de função DCR.

Código de exemplo

Consulte Código de exemplo para enviar dados para o Azure Monitor usando a API de ingestão de logs para obter código de exemplo usando os componentes criados neste tutorial.

Próximos passos