Compartilhar via


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

A API de Ingestão de Logs no Azure Monitor permite que você envie dados personalizados para um workspace do Log Analytics. Este tutorial usa modelos do ARM (modelos do Azure Resource Manager) para guiar 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 clientes para .NET, Go, Java e JavaScript e Python.

Observação

Este tutorial usa modelos do ARM para configurar os componentes necessários para dar suporte à API de ingestão de logs. Confira o Tutorial: Enviar dados para os Logs do Azure Monitor com a API de ingestão de 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. Criar um aplicativo do Microsoft Entra para autenticar na API.
  2. Crie uma tabela personalizada em um workspace do Log Analytics. Esta é a tabela para a qual você estará enviando dados.
  3. Crie uma regra de coleta de dados (DCR) para direcionar os dados para a tabela de destino.
  4. Atribuir ao aplicativo do Microsoft Entra um acesso ao DCR.
  5. Confira Código de exemplo para enviar dados ao Azure Monitor usando a API de ingestão de logs para obter um código de exemplo para enviar dados para usar a API de ingestão de logs.

Observação

Este artigo inclui opções para usar um ponto de extremidade de ingestão DCR ou um ponto de extremidade de coleta de dados (DCE). Você pode optar por usar qualquer um dos usuários, mas um DCE será necessário com a API de ingestão de Logs se o link privado for usado. Consulte Quando um DCE é necessário?.

Pré-requisitos

Para concluir este tutorial, você precisará:

Coletar detalhes do workspace

Comece coletando informações que você precisará no seu workspace.

Vá até seu workspace no menu Workspaces 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 workspace.

Criar aplicativo do Microsoft Entra

Comece registrando um aplicativo do Microsoft Entra para autenticar na API. Há suporte para qualquer esquema de autenticação do Resource Manager, mas este tutorial seguirá o Esquema de fluxo de concessão de credenciais do cliente.

  1. No menu do Microsoft Entra ID no portal do Azure, selecione Registros de aplicativo>Novo registro.

    Captura de tela que mostra a tela de registro do aplicativo.

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

    Captura de tela mostrando os detalhes do aplicativo.

  3. Após o registro, você pode exibir os detalhes do aplicativo. Anote a ID do Aplicativo (cliente) e a ID do Diretório (locatário). Você precisará desses valores mais adiante no processo.

    Captura de tela que mostra a ID do aplicativo.

  4. Gere um segredo do cliente do aplicativo, que é semelhante à criação de uma senha para uso com um nome de usuário. Selecione Certificados e segredos>Novo segredo do cliente. Dê um nome ao segredo para identificar sua finalidade e selecionar uma duração Expira. A opção 12 meses está selecionada aqui. Para uma implementação de produção, você seguiria as melhores práticas para um procedimento de rotação de segredo ou usaria 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 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 do segredo do novo aplicativo.

Criar ponto de extremidade da coleta de dados

Um DCE não é necessário se você usar o ponto de extremidade de ingestão de DCR.

Criar nova tabela no workspace do Log Analytics

A tabela personalizada deve ser criada para que você possa enviar dados a ela. A tabela deste tutorial incluirá cinco colunas, conforme descrito no esquema a seguir. As propriedades name, type e description são obrigatórias para cada coluna. As propriedades isHidden e isDefaultDisplay terão o padrão false se não forem especificadas explicitamente. Os tipos de dados possíveis são string, int, long, real, boolean, dateTime, guid e dynamic.

Observação

Este tutorial usa o PowerShell do Azure Cloud Shell para fazer chamadas à 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 o workspace no comando Invoke-AzRestMethod. Cole o código 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 uma regra de coleta de dados

O DCR define como os dados serão tratados depois de recebidos. Isso inclui:

  • Esquema de dados que estão sendo enviados para o ponto de extremidade
  • Transformação que será aplicada aos dados antes de serem enviados ao workspace
  • O workspace de destino e a tabela onde 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 Criar seu próprio modelo no editor.

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

  3. Copie o modelo do ARM a seguir no editor e selecione Salvar.

    Captura de tela que mostra como editar um modelo do ARM.

    Observe os seguintes detalhes na DCR definida neste modelo:

    • streamDeclarations: Definições de coluna dos dados de entrada.
    • destinations: Workspace de destino.
    • dataFlows: corresponde ao fluxo com o workspace 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-08-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."
                }
            }
        },
        "resources": [
            {
                "type": "Microsoft.Insights/dataCollectionRules",
                "name": "[parameters('dataCollectionRuleName')]",
                "location": "[parameters('location')]",
                "apiVersion": "2023-03-11",
                "kind": "Direct",
                "properties": {
                    "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'))]"
            }
        }
    }
    

  1. Na tela Implantação personalizada, especifique uma Assinatura e um Grupo de recursos para armazenar a DCR. Em seguida, forneça os valores definidos no modelo. Os valores incluem um Nome para a DCR e a ID de Recurso do Workspace que você coletou em uma etapa anterior. O Local deve ser o mesmo local do workspace. A Região já estará preenchida e será usada para o local da DCR.

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

  2. Selecione Examinar + criar e, em seguida, selecione Criar depois de examinar os detalhes.

  3. Quando a implantação for concluída, expanda a caixa Detalhes da implantação e selecione a DCR para exibir os detalhes. Selecione Exibição JSON.

    Captura de tela que mostra os detalhes da DCR.

  4. Copie a ID imutável e o URI de ingestão de logs para o DCR. Você os usará quando enviar dados para o Azure Monitor usando a API.

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

Atribuir permissões a uma DCR

Após a DCR ter sido criada, o aplicativo precisará receber permissão para ela. A permissão permitirá que um aplicativo que esteja usando a ID e a chave do aplicativo corretas envie dados para o novo DCR.

  1. Na 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 à DCR.

  2. Selecione Publicador de Métricas de Monitoramento e selecione Avançar. Em vez disso, você pode criar uma ação personalizada com a ação de dados Microsoft.Insights/Telemetry/Write.

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

  3. Selecione Usuário, grupo ou entidade de serviço para Atribuir acesso a 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 da DCR.

  4. Selecione Revisar + atribuir e verifique os detalhes antes de salvar sua atribuição de função.

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

Código de exemplo

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

Próximas etapas