Compartir a través de

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

  • Artículo

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.

Diagrama que muestra información general de la API de ingesta de registros.

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.

Nota:

Para ver un script de PowerShell que automatiza la configuración de estos componentes, consulte Código de ejemplo para enviar datos a Azure Monitor mediante la API de ingesta de registros.

Componente Función
Registro y secreto de la aplicación El registro de la aplicación se usa para autenticar la llamada API. Se debe conceder permiso a la DCR que se describe a continuación. La llamada API incluye el id. de la aplicación (cliente) y el id. del directorio (inquilino) de la aplicación, y el valor de un secreto de aplicación.

Consulte Creación de una aplicación de Microsoft Entra y una entidad de servicio con acceso a los recursos y Creación de un nuevo secreto de aplicación.
Ver del área de trabajo de Log Analytics Para poder enviar datos a la tabla del área de trabajo de Log Analytics, es necesario que esta exista. Puede usar una de las tablas de Azure admitidas o crear una tabla personalizada mediante cualquiera de los métodos disponibles. Si usa Azure Portal para crear la tabla, la DCR se crea automáticamente, incluida una transformación si es necesario. Con cualquier otro método, debe crear la DCR manualmente como se describe en la sección siguiente.

Consulte Creación de una tabla personalizada.
Regla de recopilación de datos (DCR) Azure Monitor usa la regla de recopilación de datos (DCR) para conocer la estructura de los datos entrantes y saber qué hacer con ellos. Si la estructura de la tabla y los datos entrantes no coinciden, la DCR puede incluir una transformación para convertir los datos de origen de manera que coincidan con la tabla de destino. También puede usar la transformación para filtrar los datos de origen y realizar cualquier otro cálculo o conversión.

Si crea una tabla personalizada mediante Azure Portal, la DCR y la transformación se crearán automáticamente en función de los datos de ejemplo que proporcione. Si usa una tabla existente o crea una tabla personalizada mediante otro método, debe crear manualmente la DCR con los detalles de la sección siguiente.

Una vez creada la DCR, debe conceder acceso a esta para la aplicación que creó en el primer paso. En el menú Supervisión de Azure Portal, seleccione Reglas de recopilación de datos y seleccione la DCR que ha creado. Seleccione Control de acceso (IAM) para la DCR y, después, seleccione Agregar asignación de roles para añadir el rol de Publicador de métricas de supervisión.

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.

Recorte de pantalla que muestra el punto de conexión de ingesta de registros en un DCR.

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.

Nota:

La propiedad logsIngestion se agregó el 31 de marzo de 2024. Antes de esta fecha, se requería una DCE para la API de ingesta de registros. Los puntos de conexión no se pueden agregar a un DCR existente, pero puede seguir usando las DCR existentes con DCE existentes. Si desea pasar a un punto de conexión de DCR, debe crear un nuevo DCR para reemplazar el existente. Un DCR con puntos de conexión también puede usar un DCE. En este caso, puede elegir si usar los puntos de conexión DCE o DCR para cada uno de los clientes que usan DCR.

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.

Parámetro Descripción
region Región para crear la DCR. Esto debe coincidir con la región del área de trabajo de Log Analytics y el DCE si usa uno.
dataCollectionEndpointId Id. de recurso del DCE. Quite este parámetro si usa el Punto de ingesta de DCR.
streamDeclarations Cambie la lista de columnas por las columnas de los datos entrantes. No es necesario cambiar el nombre de la secuencia, ya que esto solo tiene que coincidir con el nombre de streams en dataFlows.
workspaceResourceId Id. de recurso del área de trabajo de Log Analytics. No es necesario cambiar el nombre, ya que esto solo tiene que coincidir con el nombre de destinations en dataFlows.
transformKql Consulta de KQL que se va a aplicar a los datos entrantes. Si el esquema de los datos entrantes coincide con el esquema de la tabla, puede usar source para la transformación, que pasará los datos entrantes sin cambios. De lo contrario, use una consulta que transformará los datos para que coincidan con el esquema de la tabla de destino.
outputStream Nombre de la tabla a la que se van a enviar los datos. Para una tabla personalizada, agregue el prefijo Custom-<nombre de tabla>. Para una tabla integrada, agregue el prefijo Microsoft-<nombre de tabla>. 
{
    "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.

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.

Recorte de pantalla de una regla de recopilación de datos que muestra el identificador inmutable.

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.

Encabezado ¿Necesario? Descripción
Authorization Sí Token de portador obtenido a través del flujo de credenciales de cliente. Use el valor de audiencia del token para la nube:

Nube pública de Azure: https://monitor.azure.com
Microsoft Azure operado por la nube 21Vianet: https://monitor.azure.cn
Nube de Azure del gobierno de EE. UU.: https://monitor.azure.us
Content-Type Sí application/json
Content-Encoding No gzip
x-ms-client-request-id No GUID con formato de cadena. Id. de solicitud que Microsoft puede usar para solucionar problemas.

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:

Tablas Descripción
Tablas personalizadas Cualquier tabla personalizada que se cree en el área de trabajo de Log Analytics. La tabla de destino debe existir antes de poder enviarle datos. Las tablas personalizadas deben tener el sufijo _CL.
Tablas de Azure Actualmente se admiten las tablas de Azure siguientes. Se pueden agregar otras tablas a esta lista, ya que se implementa la compatibilidad con ellas.

Nota:

Los nombres de columna deben comenzar con una letra y pueden constar de hasta 45 caracteres alfanuméricos y guiones bajos (_). _ResourceId, id, _ResourceId, _SubscriptionId, TenantId, Type, UniqueId y Title son nombres de columna reservados. Las columnas personalizadas que agregue a una tabla de Azure deben tener el sufijo _CF.

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