API de ingesta de registros en Azure Monitor (versión preliminar)

La API de ingesta de registros en Azure Monitor le permite enviar datos a un área de trabajo de Log Analytics mediante una llamada a la API de REST o a las bibliotecas de cliente. La API permite enviar datos a tablas de Azure admitidas o a las tablas personalizadas que cree. También se puede extender el esquema de las tablas de Azure con columnas personalizadas para aceptar datos adicionales.

Funcionamiento básico

Los datos se pueden enviar a la API de ingesta de registros desde cualquier aplicación que pueda realizar una llamada a la API REST. Puede tratarse de una aplicación personalizada creada por usted o de una aplicación o agente que sepa cómo enviar datos a la API. Especifica un regla de recopilación de datos (DCR) que incluye la tabla y el área de trabajo de destino, así como las credenciales de un registro de aplicación con acceso a la DCR especificada. Envía los datos a un punto de conexión especificado por el DCR o a un punto de conexión de recopilación de datos (DCE) si usa un vínculo privado.

Los datos enviados por la aplicación a la API deben tener el formato JSON y coincidir con la estructura esperada por la DCR. No es necesario que coincida necesariamente con la estructura de la tabla de destino, ya que la DCR puede incluir una transformación para convertir los datos para que coincidan con la estructura de la tabla. Puede modificar el área de trabajo y la tabla de destino modificando la regla de recopilación de datos sin realizar ningún cambio en la llamada API ni en los datos de origen.

Configuración

En la tabla siguiente se describe cada componente de Azure que se debe configurar para poder usar la API de ingesta de registros.

Punto de conexión

El punto de conexión de la API de REST para la API de ingesta de registros puede ser un Punto de conexión de recopilación de datos (DCE) o el punto de conexión de ingesta de registros de DCR.

El punto de conexión de ingesta de registros de DCR se genera al crear un DCR para la ingesta directa. Para recuperar este punto de conexión, abra DCR en la vista JSON en Azure Portal. Es posible que tenga que cambiar la Versión de API a la versión más reciente para que se muestren los puntos de conexión.

Una DCE solo es necesaria cuando se conecta a un área de trabajo de Log Analytics mediante un vínculo privado o si el DCR no incluye el punto de conexión de ingesta de registros. Este puede ser el caso si usa un DCR anterior o si creó el DCR sin el parámetro "kind": "Direct". Consulte Regla de recopilación de datos (DCR) a continuación para obtener más detalles.

Regla de recopilación de datos (DCR)

Al crear una tabla personalizada en un área de trabajo de Log Analytics mediante Azure Portal, se crea un DCR que se puede usar con la API de ingesta de registros. Si va a enviar datos a una tabla ya existente, debe crear la DCR manualmente. Comience con el DCR de ejemplo siguiente, reemplazando los valores de los parámetros siguientes en la plantilla. Use cualquiera de los métodos descritos en Crear y editar reglas de recopilación de datos (DCR) en Azure Monitor para crear el DCR.

{
    "location": "eastus",
    "dataCollectionEndpointId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/my-resource-group/providers/Microsoft.Insights/dataCollectionEndpoints/dce-eastus",
    "kind": "Direct",
    "properties": {
        "streamDeclarations": {
            "Custom-MyTable": {
                "columns": [
                    {
                        "name": "Time",
                        "type": "datetime"
                    },
                    {
                        "name": "Computer",
                        "type": "string"
                    },
                    {
                        "name": "AdditionalContext",
                        "type": "string"
                    }
                ]
            }
        },
        "destinations": {
            "logAnalytics": [
                {
                    "workspaceResourceId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/cefingestion/providers/microsoft.operationalinsights/workspaces/my-workspace",
                    "name": "LogAnalyticsDest"
                }
            ]
        },
        "dataFlows": [
            {
                "streams": [
                    "Custom-MyTable"
                ],
                "destinations": [
                    "LogAnalyticsDest"
                ],
                "transformKql": "source",
                "outputStream": "Custom-MyTable_CL"
            }
        ]
    }
}

Bibliotecas de clientes

Además de realizar una llamada a la API REST, puede usar las siguientes bibliotecas cliente para enviar datos a la API de ingesta de registros. Las bibliotecas requieren los mismos componentes descritos en Configuración. Para ver ejemplos con cada una de estas bibliotecas, consulte Código de ejemplo para enviar datos a Azure Monitor mediante la API de ingesta de registros.

• .NET
• Go
• Java
• JavaScript
• Python

Llamada a API REST

Para enviar datos a Azure Monitor con una llamada API de REST, realice una llamada POST a través de HTTP. Los detalles necesarios para esta llamada se describen en esta sección.

URI

El URI incluye la región, el Punto de conexión de ingesta de DCE o DCR, el identificador de DCR y el nombre de la secuencia. También especifica la versión de la API.

El URI usa el siguiente formato.

{Endpoint}/dataCollectionRules/{DCR Immutable ID}/streams/{Stream Name}?api-version=2023-01-01

Por ejemplo:

https://my-dce-5kyl.eastus-1.ingest.monitor.azure.com/dataCollectionRules/dcr-000a00a000a00000a000000aa000a0aa/streams/Custom-MyTable?api-version=2023-01-01

El DCR Immutable ID se genera para el DCR cuando se crea. Puede recuperarlo desde la página Información general de la DCR en Azure Portal.

Stream Name hace referencia al Stream Name en la DCR que debe controlar los datos personalizados.

encabezados

En la tabla siguiente se describen los encabezados de la llamada API.

Body

El cuerpo de la llamada incluye los datos personalizados que se enviarán a Azure Monitor. La forma de los datos debe ser una matriz JSON con una estructura de elementos que coincide con el formato esperado por el flujo en la DCR. Si es necesario enviar un solo elemento dentro de la llamada API, los datos se deben enviar como una matriz de un solo elemento.

Por ejemplo:

[
{
    "TimeGenerated": "2023-11-14 15:10:02",
    "Column01": "Value01",
    "Column02": "Value02"
}
]

Asegúrese de que el cuerpo de la solicitud está codificado correctamente en UTF-8 para evitar problemas con la transmisión de datos.

Ejemplo

Para ver un ejemplo de la llamada API mediante PowerShell, consulte Código de ejemplo para enviar datos a Azure Monitor mediante la API de ingesta de registros.

Tablas admitidas

Los datos enviados a la API de ingesta se pueden enviar a las tablas siguientes:

• ADAssessmentRecommendation
  
• ADSecurityAssessmentRecommendation
  
• Anomalías
  
• ASimAuditEventLogs
  
• ASimAuthenticationEventLogs
  
• ASimDhcpEventLogs
  
• ASimDnsActivityLogs
  
• ASimDnsAuditLogs
  
• ASimFileEventLogs
  
• ASimNetworkSessionLogs
  
• ASimProcessEventLogs
  
• ASimRegistryEventLogs
  
• ASimUserManagementActivityLogs
  
• ASimWebSessionLogs
  
• AWSCloudTrail
  
• AWSCloudWatch
  
• AWSGuardDuty
  
• AWSVPCFlow
  
• AzureAssessmentRecommendation
  
• CommonSecurityLog
  
• DeviceTvmSecureConfigurationAssessmentKB
  
• DeviceTvmSoftwareVulnerabilitiesKB
  
• ExchangeAssessmentRecommendation
  
• ExchangeOnlineAssessmentRecommendation
  
• GCPAuditLogs
  
• GoogleCloudSCC
  
• SCCMAssessmentRecommendation
  
• SCOMAssessmentRecommendation
  
• SecurityEvent
  
• SfBAssessmentRecommendation
  
• SfBOnlineAssessmentRecommendation
  
• SharePointOnlineAssessmentRecommendation
  
• SPAssessmentRecommendation
  
• SQLAssessmentRecommendation
  
• StorageInsightsAccountPropertiesDaily
  
• StorageInsightsDailyMetrics
  
• StorageInsightsHourlyMetrics
  
• StorageInsightsMonthlyMetrics
  
• StorageInsightsWeeklyMetrics
  
• Syslog
  
• UCClient
  
• UCClientReadinessStatus
  
• UCClientUpdateStatus
  
• UCDeviceAlert
  
• UCDOAggregatedStatus
  
• UCDOStatus
  
• UCServiceUpdateStatus
  
• UCUpdateAlert
  
• WindowsClientAssessmentRecommendation
  
• WindowsEvent
  
• WindowsServerAssessmentRecommendation
  

Límites y restricciones

Para los límites relacionados con la API de ingesta de registros, consulte Límites de servicio de Azure Monitor.

Pasos siguientes

• Consulte un tutorial sobre el envío de datos a registros de Azure Monitor con la API de ingesta de registros en Azure Portal
• Consulte un tutorial sobre el envío de registros personalizados con plantillas de Resource Manager y la API de REST.
• Obtenga instrucciones sobre el uso de las bibliotecas cliente para la API de ingesta de registros para .NET, Java, JavaScript o Python.