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:
- Criar um aplicativo do Microsoft Entra para autenticar na API.
- Crie um ponto de extremidade de coleta de dados (DCE) para receber dados.
- Crie uma tabela personalizada em um workspace do Log Analytics. Esta é a tabela para a qual você estará enviando dados.
- Crie uma regra de coleta de dados (DCR) para direcionar os dados para a tabela de destino.
- Atribuir ao aplicativo do Microsoft Entra um acesso ao DCR.
- 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.
Pré-requisitos
Para concluir este tutorial, você precisará:
- Um workspace do Log Analytics em que você tenha, no mínimo, direitos de colaborador.
- Permissões para criar objetos de DCR no workspace.
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.
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.
No menu do Microsoft Entra ID no portal do Azure, selecione Registros de aplicativo>Novo registro.
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.
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.
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.
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.
Criar ponto de extremidade da coleta de dados
Um DCE é necessário para aceitar os dados enviados para o Azure Monitor. Depois de configurar o DCE e vinculá-lo a uma DCR, você poderá enviar dados por HTTP de seu aplicativo. O DCE deve estar localizado na mesma região que o DCR e o workspace do Log Analytics onde os dados serão enviados.
Na caixa de pesquisa do portal do Azure, insira modelo e selecione Implantar um modelo personalizado.
Selecione Criar seu próprio modelo no editor.
Copie o modelo do ARM a seguir no editor e selecione Salvar. Você não precisa modificar esse modelo, pois fornecerá os valores para seus parâmetros.
{ "$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'))]" } } }Na tela Implantação personalizada, especifique uma Assinatura e um Grupo de recursos para armazenar a DCR e, em seguida, forneça valores como um Nome para o DCE. O Local deve ser o mesmo local do workspace. A Região já estará preenchida e será usada para o local de DCE.
Selecione Examinar + criar e, em seguida, selecione Criar depois de examinar os detalhes.
Selecione Exibição JSON para exibir outros detalhes do DCE. Copie a ID do Recurso e o ponto de extremidade logsIngestion que você precisará em uma etapa posterior.
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.
Selecione o botão Cloud Shell no portal do Azure e verifique se o ambiente está definido como PowerShell.
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
Na caixa de pesquisa do portal do Azure, insira modelo e selecione Implantar um modelo personalizado.
Selecione Criar seu próprio modelo no editor.
Copie o modelo do ARM a seguir no editor e selecione Salvar.
Observe os seguintes detalhes na DCR definida neste modelo:
dataCollectionEndpointId: ID de recurso do ponto de extremidade da coleta de dados.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-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'))]" } } }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.
Selecione Examinar + criar e, em seguida, selecione Criar depois de examinar os detalhes.
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.
Copie a ID imutável para a DCR. Você a usará em uma etapa posterior ao enviar dados de exemplo usando a API.
Observação
Todas as propriedades da DCR, como a transformação, podem não ser exibidas no portal do Azure mesmo que a DCR tenha sido criada com êxito com essas propriedades.
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 qualquer aplicativo que esteja usando a ID e a chave do aplicativo corretas envie dados para o novo DCE e a DCR.
Na DCR no portal do Azure, selecione Controle de Acesso (IAM)>Adicionar atribuição de função.
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.
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.
Selecione Revisar + atribuir e verifique os detalhes antes de salvar sua atribuição de função.
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.