Tutorial: Envío de datos a Azure Monitor usando la API de ingesta de registros (plantillas de Resource Manager)

La API de ingesta de registros de Azure Monitor le permite enviar datos personalizados a un área de trabajo de Log Analytics. En este tutorial se usan plantillas de Azure Resource Manager (plantillas de ARM) para abordar paso a paso la configuración de los componentes necesarios para admitir la API y, a continuación, se proporciona una aplicación de ejemplo mediante la API de REST y las bibliotecas cliente para .NET, Go, Java, JavaScript y Python.

Nota:

En este tutorial se usan plantillas de ARM para configurar los componentes necesarios para admitir la API de ingesta de registros. Consulte Tutorial: Envío de datos a registros de Azure Monitor con la API de ingesta de registros (Azure Portal) para ver un tutorial similar que usa la interfaz de usuario de Azure Portal para configurar estos componentes.

Los pasos necesarios para configurar la API de ingesta de registros son los siguientes:

1. Crear una aplicación de Microsoft Entra para autenticarse en la API.
2. Crear una tabla personalizada en un área de trabajo de Log Analytics. Esta es la tabla a la que va a enviar datos.
3. Cree una regla de recopilación de datos (DCR) para dirigir los datos a la tabla de destino.
4. Conceder acceso a la aplicación Microsoft Entra al DCR.
5. Consulte Código de ejemplo para enviar datos a Azure Monitor mediante la API de ingesta de registros para obtener código de ejemplo para enviar datos a mediante la API de ingesta de registros.

Nota:

En este artículo se incluyen opciones para usar un punto de conexión de ingesta de DCR o un punto de conexión de recopilación de datos (DCE). Puede optar por usar cualquiera de ellos, pero se requiere un DCE con la API de ingesta de registros si se usa private link. Vea ¿Cuándo es necesario un DCE?.

Requisitos previos

Para completar este tutorial, necesita:

• Un área de trabajo de Log Analytics en la que tenga al menos derechos de colaborador.
• Permisos para crear objetos DCR en el área de trabajo.

Recopilación de los detalles del área de trabajo

Empiece por recopilar la información que necesitará del área de trabajo.

Vaya al área de trabajo desde el menú Áreas de trabajo de Log Analytics en Azure Portal. En la página Propiedades, copie el identificador de recurso y guárdelo para usarlo más adelante.

Crear una aplicación de Microsoft Entra

Para empezar, registre una aplicación de Microsoft Entra para autenticarse en la API. Se admite cualquier esquema de autenticación de ARM, pero en este tutorial se seguirá el esquema del flujo de concesión de credenciales de cliente.

1. En el menú Microsoft Entra ID de Azure Portal, seleccione Registros de aplicaciones>Nuevo registro.

   

2. Asigne un nombre a la aplicación y cambie el ámbito del inquilinato si el valor predeterminado no es adecuado para su entorno. No se requiere un URI de redireccionamiento.

   

3. Tras el registro, puede ver los detalles de la aplicación. Anote el valor de Id. de aplicación (cliente) y el de Id. de directorio (inquilino). Los necesitará más adelante en el proceso.

   

4. Genere un secreto de cliente de la aplicación, que es algo parecido a la creación de una contraseña para usarla con un nombre de usuario. Seleccione Certificados y secretos>Nuevo secreto de cliente. Asigne un nombre al secreto para identificar su propósito y seleccione una duración en Expiración. La opción 12 meses está aquí seleccionada. En una implementación de producción, debería seguir los procedimientos recomendados de rotación de secretos o usar un modo de autenticación más seguro, como un certificado.

   

5. Seleccione Agregar para guardar el secreto y, a continuación, anote el Valor. Asegúrese de registrar este valor, porque que no se puede recuperar después de salir de esta página. Use las mismas medidas de seguridad que usaría para proteger una contraseña, ya que es el equivalente funcional.

   

Creación de un punto de conexión de recopilación de datos

Punto de conexión de DCR

No es necesario un DCE si usa el punto de conexión de ingesta de DCR.

DCE

Se requiere un DCE para aceptar los datos que se envían a Azure Monitor. Tras configurarlo y vincularlo a una DCR, podrá enviar datos a través de HTTP desde la aplicación. El DCE debe estar situado en la misma región que el DCR y el área de trabajo de Log Analytics al que se enviarán los datos.

1. En el cuadro de búsqueda de Azure Portal, escriba plantilla y, a continuación, seleccione Implementar una plantilla personalizada.

   

2. Seleccione Cree su propia plantilla en el editor.

   

3. Pegue la siguiente plantilla de ARM en el editor y seleccione Guardar. No es necesario modificar esta plantilla, ya que proporcionará los valores de sus 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'))]"
           }
       }
   }
   

4. En la pantalla Implementación personalizada, especifique una suscripción y un grupo de recursos para almacenar la DCR y, a continuación, proporcione un nombre para el DCE. La ubicación debe ser la misma que la del área de trabajo. La región ya aparecerá rellenada y se usará como ubicación del DCE.

   

5. Seleccione Revisar y crear y, a continuación, seleccione Crear después de revisar los detalles.

6. Seleccione Vista JSON para ver otros detalles del DCE. Copie el identificador de recurso y el punto de conexión de ingesta de registros que necesitará en un paso posterior.

   

Creación de una tabla en el área de trabajo de Log Analytics

Se debe crear la tabla personalizada antes para poder enviarle datos. La tabla para este tutorial incluirá cinco columnas que se muestran en el siguiente esquema. Las propiedades name, type y description son obligatorias para cada columna. Las propiedades isHidden y isDefaultDisplay ambas tienen como valor predeterminado false salvo que se especifiquen explícitamente. Los tipos de datos posibles son string, int, long, real, boolean, dateTime, guid, y dynamic.

Nota:

En este tutorial se usa PowerShell de Azure Cloud Shell para realizar llamadas API REST usando la API Tables de Azure Monitor. Puede utilizar cualquier otro método válido para realizar estas llamadas.

Importante

Las tablas personalizadas deben usar un sufijo _CL.

1. Seleccione el botón de Cloud Shell en Azure Portal y asegúrese de que el entorno esté establecido en PowerShell.

   

2. Copie el siguiente código de PowerShell y reemplace las variables en el parámetro Path por los valores adecuados del área de trabajo en el comando Invoke-AzRestMethod. Péguelo en el símbolo del sistema de Cloud Shell para ejecutarlo.

   $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
   

Crear una regla de recopilación de datos.

El DCR define cómo se manipularán los datos una vez recibidos. Esto incluye:

• Esquema de datos que se envían al punto de conexión
• Transformación que se aplicará a los datos antes de enviarlos al área de trabajo
• Área de trabajo de destino y tabla a la que se enviarán los datos transformados

1. En el cuadro de búsqueda de Azure Portal, escriba plantilla y, a continuación, seleccione Implementar una plantilla personalizada.

   

2. Seleccione Cree su propia plantilla en el editor.

   

3. Pegue la siguiente plantilla de ARM en el editor y seleccione Guardar.

   

   Punto de conexión de DCR

   Observe los detalles siguientes en la regla de recopilación de datos que se define en esta plantilla:

   • streamDeclarations: definiciones de columna de los datos entrantes.
   • destinations: área de trabajo de destino.
   • dataFlows: hace que el flujo coincida con el área de trabajo de destino y especifica la consulta de transformación y la tabla de destino. La salida de la consulta de destino es lo que se enviará a la tabla 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'))]"
           }
       }
   }
   

   DCE

   Observe los detalles siguientes en la regla de recopilación de datos que se define en esta plantilla:

   • dataCollectionEndpointId: identificador de recurso del punto de conexión de recopilación de datos.
   • streamDeclarations: definiciones de columna de los datos entrantes.
   • destinations: área de trabajo de destino.
   • dataFlows: hace que el flujo coincida con el área de trabajo de destino y especifica la consulta de transformación y la tabla de destino. La salida de la consulta de destino es lo que se enviará a la tabla 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."
               }
           },
           "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": "2023-03-11",
               "kind": "Direct",
               "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. En la pantalla Implementación personalizada, especifique una suscripción y un grupo de recursos para almacenar la DCR. A continuación, introduzca los valores definidos en la plantilla. Los valores incluyen un nombre para la DCR y el identificador de recurso del área de trabajo que obtuvo en un paso anterior. La ubicación debe ser la misma que la del área de trabajo. La región ya aparecerá rellenada y se usará como ubicación de la DCR.

   

5. Seleccione Revisar y crear y, a continuación, seleccione Crear después de revisar los detalles.

6. Una vez completada la implementación, expanda el cuadro Detalles de la implementación y seleccione su DCR para ver sus detalles. Seleccione Vista JSON.

   

7. Copie el Identificador inmutable y el URI de ingesta de registros para el DCR. Los usará al enviar datos a Azure Monitor mediante la API.

   

Asignación de permisos a una DCR

Tras crear la DCR, se debe conceder permiso a la aplicación para acceder a ella. Este permiso hará que cualquier aplicación que use el identificador y la clave de aplicación correctos pueda enviar datos al nuevo DCR.

1. En la DCR de Azure Portal, seleccione Control de acceso (IAM)>Agregar asignación de roles.

   

2. Seleccione Publicador de métricas de supervisión y seleccione Siguiente. En su lugar, podría crear una acción personalizada con la acción de datos Microsoft.Insights/Telemetry/Write.

   

3. Seleccione Usuario, grupo o entidad de servicio en Asignar acceso a y seleccione Seleccionar miembros. Seleccione la aplicación que creó y seleccione Seleccionar.

   

4. Seleccione Revisar y asignar, y compruebe los detalles antes de guardar la asignación de roles.

   

Código de ejemplo

Consulte Código de ejemplo para enviar datos a Azure Monitor mediante la API de ingesta de registros para obtener código de ejemplo mediante los componentes creados en este tutorial.

Pasos siguientes

• Seguir un tutorial similar con Azure Portal
• Obtener más información sobre los registros personalizados
• Obtenga más información sobre cómo escribir consultas de transformación.