Migración de HTTP Data Collector API a la API de ingesta de registros

La API de recopilación de datos HTTP está en proceso de desaprobación. El soporte para la API heredada de Data Collector finaliza el 14 de septiembre de 2026. La ingesta existente sigue funcionando, pero la API solo recibe correcciones de seguridad críticas. Migre a la API de ingesta de registros , que proporciona más capacidad de procesamiento y flexibilidad en la ingesta de registros y la administración de tablas.

En este artículo se describen las diferencias entre las dos API y cómo migrar a la API de ingesta de registros.

Dos fechas afectan a la ingesta de la API de Data Collector. El 1 de marzo de 2026, el punto de conexión de API dejó de aceptar versiones heredadas de TLS; Los clientes que no negocian TLS 1.2 o posterior no pueden ingerir datos. El 14 de septiembre de 2026, la API está en desuso, pero la ingesta continúa para los clientes compatibles con TLS. Verifique la configuración TLS de su cliente antes de dar por hecho que la ingesta funciona correctamente, independientemente del cronograma de migración.

Ventajas de la API de ingesta de registros

La API de ingesta de registros proporciona las siguientes ventajas con respecto a la API del Recopilador de datos:

  • Admite transformaciones, que permiten modificar los datos antes de ingerirlos en la tabla de destino, incluido el filtrado y la manipulación de datos.
  • Permite enviar datos a varios destinos.
  • Permite administrar el esquema de la tabla de destino, incluidos los nombres de columna, y si se van a agregar nuevas columnas a la tabla de destino cuando cambia el esquema de datos de origen.
  • Admite el control de acceso basado en rol (RBAC) para restringir la ingesta de datos por regla y identidad de recopilación de datos.

Requisitos previos

Para completar esta migración, necesita:

Permisos necesarios

La API de ingesta de registros usa la autenticación basada en OAuth a través de Microsoft Entra (para registros de aplicaciones o identidades administradas) y la regla de recopilación de datos (DCR) con ámbito RBAC. Asigne los permisos de la aplicación a la DCR y use un punto de conexión de colección de datos (DCE) o el punto de conexión de ingesta de registros de la DCR para las solicitudes de ingesta.

Acción Permisos necesarios
Cree un punto de conexión de recopilación de datos. Permisos de Microsoft.Insights/dataCollectionEndpoints/write, por ejemplo mediante el rol integrado Colaborador de supervisión.
Cree o modifique una regla de recopilación de datos. Permisos de Microsoft.Insights/DataCollectionRules/Write, por ejemplo mediante el rol integrado Colaborador de supervisión.
Convierta una tabla que use Data Collector API en reglas de recopilación de datos y la API de ingesta de registros. Permisos de Microsoft.OperationalInsights/workspaces/tables/migrate/action, por ejemplo mediante el rol integrado Colaborador de Log Analytics.
Cree nuevas tablas o modifique esquemas de tabla. Permisos de microsoft.operationalinsights/workspaces/tables/write, por ejemplo mediante el rol integrado Colaborador de Log Analytics.
Llame a la API de ingesta de registros. Consulte Asignación de permisos a un DCR.

Creación de nuevos recursos necesarios para la API de ingesta de registros

La API de ingesta de registros requiere que cree dos nuevos tipos de recursos, que la API del recopilador de datos HTTP no requiere:

Migración de tablas personalizadas existentes o creación de nuevas tablas

Si tiene una tabla personalizada existente a la que actualmente envía datos mediante Data Collector API, las opciones son:

  • Migre la tabla y cambie a la API de ingesta de registros.
  • Mantenga la tabla y los datos existentes y configure una nueva tabla en la que se ingieren datos mediante la API de ingesta de registros. Elimine la tabla anterior cuando esté listo.
  • (No recomendado) Migre la tabla pero siga usando la API de recopilador de datos heredada. Los cambios en los tipos de datos existentes y varios cambios de esquema en las tablas personalizadas de Data Collector API existentes pueden provocar errores.

Identificación de tablas personalizadas clásicas

Tiene varias maneras de encontrar tablas que usan Data Collector API:

  • Propiedades de tabla (portal):Ver las propiedades de la tabla. Las tablas que usan la API de recopilador de datos o incorporan datos a través del agente heredado de Log Analytics (MMA) muestran Tabla personalizada (clásica) como la propiedad Tipo.

  • Propiedades de la tabla (API):tableSubType es Classic al ver las propiedades de la tabla con la operación Table de la API de administración de registros. Este es un ejemplo CLI de Azure comando que busca rápidamente todas las tablas con estos criterios:

az monitor log-analytics workspace table list \
  --resource-group myResourceGroupName --workspace-name myWorkspaceName \
  --query "[?schema.tableSubType=='Classic'].{Name:name, SubType:schema.tableSubType}" -o table
  • Heurística de consulta: Las pistas de los registros individuales pueden ayudar a investigar aún más el uso de la API heredada. Los registros con el SourceSystem valor de RestAPI indican que la API del recopilador de datos HTTP creó el registro, por lo que la tabla se ha heredado cuando se creó el registro. Además, algunos sufijos de nombre de columna indican que la API heredada creó la columna.

Para enumerar tablas de un área de trabajo que contenga filas ingeridas a través de Data Collector API, ejecute esta consulta:

Convenciones de sufijo para las columnas creadas por la API heredada:

Sufijo Tipo de dato
_s string
_d double
_t datetime

Advertencia

Migre desde el agente de Log Analytics al agente de Azure Monitor antes de convertir las tablas de MMA. De lo contrario, los datos dejan de introducirse en los campos personalizados de estas tablas tras la conversión de la tabla.

Consideraciones sobre la migración

Los conectores de Microsoft Sentinel están pasando a conectores de Codeless Connector Framework (CCF) disponibles en el Centro de contenido. Estos conectores CCF usan las DCR con la API de ingesta de registros. Este enfoque proporciona control de esquema regulado por DCR, aplica transformaciones para la normalización y mejora la confiabilidad y la escalabilidad en comparación con la API heredada del recopilador de datos. La migración podría introducir esquemas y nombres de tabla nuevos o actualizados. Los conectores antiguos basados en Azure Functions que usan la API heredada del recopilador de datos HTTP y los nuevos conectores CCF pueden coexistir temporalmente durante el período de transición.

Al migrar conectores de Sentinel, debe actualizar los artefactos dependientes (reglas de análisis, consultas de búsqueda, workbooks, cuadernos de estrategias, analizadores) para hacer referencia a las nuevas tablas basadas en CCF o a esquemas modificados. Verifique y actualice las consultas, alertas y paquetes de contenido de KQL para evitar brechas de ingesta o detección después de la migración.

En esta tabla se resumen las consideraciones de cada opción:

Migración de la tabla Implementación en paralelo
Nomenclatura de tabla y columna Vuelva a usar el nombre de la tabla existente.
Opciones de nomenclatura de columnas:
- Use nuevos nombres de columnas y defina una transformación para dirigir los datos entrantes a la columna recién nombrada.
- Continúe usando nombres antiguos.		 Establezca libremente el nuevo nombre de la tabla.
Ajuste las integraciones, los paneles y las alertas antes de cambiar a la nueva tabla.
Procedimiento de migración Migración única de tabla. No es posible revertir una tabla migrada. Puede migrar de forma gradual, por tabla.
Después de la migración: Si sigue ingeriendo datos mediante HTTP Data Collector API con columnas existentes, no cambie el esquema.
Cree nuevas columnas solo si ingiere datos mediante la API de ingesta de registros.		 Los datos de la tabla anterior están disponibles hasta el final del período de retención.
Cuando configura por primera vez una nueva tabla o realiza cambios de esquema, los cambios de datos pueden tardar entre 10 y 15 minutos en aparecer en la tabla de destino.

Advertencia

Si sigue importando datos a través de la API heredada de Data Collector después de migrar una tabla, no use la API de Tables ni la opción Editar esquema en la interfaz de usuario de Tables para realizar cambios en el esquema (por ejemplo, añadir una nueva columna). Hacerlo interrumpe la ingestión heredada. Si debe continuar con la ingesta mediante Data Collector API, no realice cambios de esquema hasta que migre completamente a la API de ingesta de registros.

Conversión de una tabla de V1 a V2

Para convertir una tabla que usa Data Collector API (V1) en reglas de recopilación de datos y la API de ingesta de registros (V2), ejecute la operación de migración en la tabla. Si la tabla ya está convertida, esta operación no tiene ningún efecto.

En el siguiente ejemplo de CLI de Azure se usa el comando az monitor log-analytics workspace table migrate.

# Set variables
resourceGroupName="<ResourceGroupName>"
workspaceName="<WorkspaceName>"
tableName="<TableName_CL>"

# Migrate the table from V1 to V2
az monitor log-analytics workspace table migrate \
  --resource-group "$resourceGroupName" \
  --workspace-name "$workspaceName" \
  --table-name "$tableName"

Nota:

CLI de Azure comandos usan el punto de conexión de Azure Resource Manager desde el contexto actual de la CLI, por lo que no es necesario especificar management.azure.com en la sintaxis del comando.

La operación migrate habilita todas las funcionalidades de los registros personalizados basados en DCR en la tabla. Si data Collector API sigue ingeriendo datos en columnas existentes, no crea ninguna columna nueva. Los campos personalizados definidos anteriormente dejan de obtener nuevos datos. No cambie el esquema para crear columnas nuevas o la Data Collector API dejará de recopilar datos en toda la tabla. Aplique una transformación del espacio de trabajo para migrar una tabla a los DCR y posponer el cambio a la API de ingesta de registros.

Importante

  • Los nombres de columna deben comenzar con una letra y pueden constar de hasta 45 caracteres alfanuméricos y guiones bajos (_).
  • _ResourceId, id, _SubscriptionId, TenantId, Type, UniqueIdy Title son nombres de columna reservados.
  • Las columnas personalizadas que agregue a una tabla de Azure deben tener el sufijo _CF.
  • Si actualiza el esquema de tabla en el área de trabajo de Log Analytics, también debe actualizar la definición del flujo de entrada en la regla de recopilación de datos para ingerir datos en columnas nuevas o modificadas.

Reducción del tamaño de los datos por llamada

La API de ingesta de registros le permite enviar hasta 1 MB de datos comprimidos o sin comprimir por llamada. Si necesita enviar más de 1 MB de datos, puede enviar varias llamadas en paralelo. Este límite difiere de la API del recopilador de datos, lo que le permite enviar hasta 32 MB de datos por llamada.

Para llamar a la API de ingesta de registros, consulte Llamada a la API REST de ingesta de registros.

Controlar las diferencias en el tipo de datos GUID

Los GUIDs se almacenan como cadenas en Azure Monitor Logs. Tables API acepta guid como un tipo de columna, pero ese tipo de datos se ve y escribe como string tipo por las API de ingesta de registros y de consulta de registros, respectivamente. Declare los GUID de origen de datos como string en su DCRstreamDeclarations. Este comportamiento es el mismo para ambas API de ingesta, por lo que la migración desde la API del recopilador de datos no cambia cómo se almacenan o consultan los valores GUID existentes. Para obtener más información, consulte Tipos de datos de columna de tabla.

Control de los cambios en el esquema de datos de origen

Data Collector API ajusta automáticamente el esquema de una tabla heredada de destino cuando cambia el esquema del objeto de datos de origen, pero la API de ingesta de registros no. La API de ingesta de registros garantiza que no recopile nuevos datos en columnas que no quiera crear.

Opciones cuando cambia el esquema de datos de origen:

Nota:

No se puede reutilizar un nombre de columna con un tipo de datos que difiere del tipo de datos original de la columna.

Contenido relacionado

Microsoft MVP Morten Waltorp Knudsen contribuyó a este artículo. Para obtener un ejemplo de automatización de la instalación y el uso continuo de la API de ingesta de registros, consulte su módulo de PowerShell AzLogDcrIngestPS.

  • Last updated on