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. La aplicación envía datos a un punto de conexión de recopilación de datos (DCE) que es un punto de conexión único para la suscripción de Azure. 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.

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.
Un punto de conexión de recopilación de datos (DCE) El DCE proporciona un punto de conexión para que la aplicación se envíe. Un único DCE puede admitir varias DCR, por lo que se puede usar un DCE existente si ya se tiene uno en la misma región que el área de trabajo de Log Analytics.

Consulte Creación de un punto de conexión de recopilación de datos.
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.

Creación manual de la DCR

Si va a enviar datos a una tabla ya existente, debe crear la DCR manualmente. Comience con la DCR de ejemplo para la API de ingesta de registros y modifique los parámetros siguientes en la plantilla. A continuación, use cualquiera de los métodos descritos en Creación y edición de reglas de recopilación de datos (DCR) en Azure Monitor para crear la DCR.

Parámetro Descripción
region Región para crear la DCR. Debe coincidir con la región del DCE y el área de trabajo de Log Analytics.
dataCollectionEndpointId Id. de recurso del DCE.
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 transforme los datos para que coincidan con el esquema de la tabla.
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>.

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 de punto de conexión

El URI del punto de conexión usa el formato siguiente, donde Data Collection Endpoint y DCR Immutable ID identifican el DCE y la DCR. El id. inmutable se genera para la DCR cuando esta se crea. Puede recuperarlo desde la vista JSON de la DCR en Azure Portal. Stream Name hace referencia al Stream Name en la DCR que debe controlar los datos personalizados.

{Data Collection Endpoint URI}/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

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