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.

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.

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.

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

   

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.

   

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.

   

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.

   

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.

   

Criar ponto de extremidade da coleta de dados

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.

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

   

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.

   

2. Selecione Criar seu próprio modelo no editor.

   

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

   

   • Ponto de extremidade DCR
   • DCE

   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'))]"
           }
       }
   }
   

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

   

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

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

   

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

   

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.

   

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.

   

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.

   

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

Próximas etapas

• Conclua um tutorial semelhante usando o portal do Azure
• Saiba mais sobre logs personalizados
• Saiba mais sobre a gravação de consultas de transformação