Compartir a través de

Envío de datos de registro a Azure Monitor mediante HTTP Data Collector API (en desuso)

  • Artículo

En este artículo se muestra cómo usar http Data Collector API para enviar datos de registro a Azure Monitor desde un cliente de API REST. Describe cómo dar formato a los datos recopilados por el script o la aplicación, incluirlos en una solicitud y tener esa solicitud autorizada por Azure Monitor. Se proporcionan ejemplos de Azure PowerShell, C#y Python.

Nota

La API del recopilador de datos HTTP de Azure Monitor está en desuso y ya no funcionará desde el 14/9/2026. Se ha reemplazado por la API de ingesta de registros de .

Conceptos

Puede usar HTTP Data Collector API para enviar datos de registro a un área de trabajo de Log Analytics en Azure Monitor desde cualquier cliente que pueda llamar a una API REST. El cliente podría ser un runbook en Azure Automation que recopila datos de administración de Azure u otra nube, o podría ser un sistema de administración alternativo que usa Azure Monitor para consolidar y analizar los datos de registro.

Todos los datos del área de trabajo de Log Analytics se almacenan como un registro con un tipo de registro determinado. Dé formato a los datos para enviarlos a la API del recopilador de datos HTTP como varios registros en notación de objetos JavaScript (JSON). Al enviar los datos, se crea un registro individual en el repositorio para cada registro de la carga de solicitud.

Captura de pantalla que ilustra la información general del recopilador de datos HTTP.

Creación de una solicitud

Para usar la API del recopilador de datos HTTP, cree una solicitud POST que incluya los datos que se van a enviar en JSON. En las tres tablas siguientes se enumeran los atributos necesarios para cada solicitud. Describiremos cada atributo con más detalle más adelante en el artículo.

URI de solicitud

Atributo Propiedad
Método PUBLICAR
URI https://<CustomerId>.ods.opinsights.azure.com/api/logs?api-version=2016-04-01
Tipo de contenido application/json

Parámetros de URI de solicitud

Parámetro Descripción
ID de Cliente Identificador único del área de trabajo de Log Analytics.
Recurso El nombre del recurso de API: /api/logs.
Versión de API Versión de la API que se va a usar con esta solicitud. Actualmente, la versión es 2016-04-01.

Encabezados de solicitud

Encabezado Descripción
Autorización Firma de autorización. Más adelante en el artículo, puede leer sobre cómo crear un encabezado HMAC-SHA256.
Log-Type Especifique el tipo de registro de los datos que se envían. Solo puede contener letras, números y el carácter de subrayado (_) y no puede superar los 100 caracteres.
x-ms-date La fecha en que se procesó la solicitud, en formato rfC 1123.
x-ms-AzureResourceId Identificador de recurso del recurso de Azure al que se deben asociar los datos. Rellena la propiedad _ResourceId y permite que los datos se incluyan en consultas de contexto de recursos . Si no se especifica este campo, los datos no se incluirán en las consultas de contexto de recursos.
campo generado por el tiempo Nombre de un campo de los datos que contiene la marca de tiempo del elemento de datos. Si especifica un campo, su contenido se usa para TimeGenerated. Si no especifica este campo, el valor predeterminado de TimeGenerated es el momento en que se ingiere el mensaje. El contenido del campo de mensaje debe seguir el formato ISO 8601 AAAA-MM-DDThh:mm:ssZ. El valor de Tiempo Generado no puede ser anterior a 2 días antes de la hora de recepción o más de un día en el futuro. En tal caso, se usará la hora en que se ingiere el mensaje.

Autorización

Cualquier solicitud a la API del recopilador de datos HTTP de Azure Monitor debe incluir un encabezado de autorización. Para autenticar una solicitud, firme la solicitud con la clave principal o secundaria del área de trabajo que realiza la solicitud. A continuación, pase esa firma como parte de la solicitud.

Este es el formato del encabezado de autorización:

Authorization: SharedKey <WorkspaceID>:<Signature>

workspaceID es el identificador único del área de trabajo de Log Analytics. Signature es un Código de Autenticación de Mensajes Basado en Hash (HMAC) que se construye a partir de la solicitud y luego se calcula mediante el algoritmo SHA256 de . A continuación, se codifica utilizando la codificación Base64.

Use este formato para codificar la cadena de firma SharedKey:

StringToSign = VERB + "\n" +
                  Content-Length + "\n" +
                  Content-Type + "\n" +
                  "x-ms-date:" + x-ms-date + "\n" +
                  "/api/logs";

Este es un ejemplo de una cadena de firma:

POST\n1024\napplication/json\nx-ms-date:Mon, 04 Apr 2016 08:00:00 GMT\n/api/logs

Cuando tenga la cadena de firma, codídela mediante el algoritmo HMAC-SHA256 en la cadena con codificación UTF-8 y, a continuación, codifique el resultado como Base64. Use este formato:

Signature=Base64(HMAC-SHA256(UTF8(StringToSign)))

Los ejemplos de las secciones siguientes tienen código de ejemplo para ayudarle a crear un encabezado de autorización.

Cuerpo de la solicitud

El cuerpo del mensaje debe estar en JSON. Debe incluir uno o varios registros con los pares de nombre de propiedad y valor en el formato siguiente. El nombre de propiedad solo puede contener letras, números y el carácter de subrayado (_).

[
    {
        "property 1": "value1",
        "property 2": "value2",
        "property 3": "value3",
        "property 4": "value4"
    }
]

Puede procesar por lotes varios registros juntos en una sola solicitud mediante el siguiente formato. Todos los registros deben ser el mismo tipo de registro.

[
    {
        "property 1": "value1",
        "property 2": "value2",
        "property 3": "value3",
        "property 4": "value4"
    },
    {
        "property 1": "value1",
        "property 2": "value2",
        "property 3": "value3",
        "property 4": "value4"
    }
]

Tipo de registro y propiedades

Se define un tipo de registro personalizado al enviar datos a través de la API del recopilador de datos HTTP de Azure Monitor. Actualmente, no se pueden escribir datos en tipos de registro existentes creados por otros tipos de datos y soluciones. Azure Monitor lee los datos entrantes y, a continuación, crea propiedades que coinciden con los tipos de datos de los valores especificados.

Cada solicitud a la API de recopilación de datos debe incluir un encabezado Log-Type con el nombre del tipo de registro. El sufijo _CL se anexa automáticamente al nombre que escribe para distinguirlo de otros tipos de registro como registro personalizado. Por ejemplo, si escribe el nombre MyNewRecordType, Azure Monitor crea un registro con el tipo MyNewRecordType_CL. Esto ayuda a garantizar que no haya conflictos entre los nombres de tipo creados por el usuario y los enviados en soluciones actuales o futuras de Microsoft.

Para identificar el tipo de datos de una propiedad, Azure Monitor agrega un sufijo al nombre de la propiedad. Si una propiedad contiene un valor NULL, la propiedad no se incluye en ese registro. En esta tabla se muestra el tipo de datos de propiedad y el sufijo correspondiente:

Tipo de datos de propiedad Sufijo
Cuerda _s
Booleano _b
Doble _d
Fecha y hora _t
GUID (almacenado como una cadena) _g

Nota

A los valores de cadena que parecen ser GUID se les asigna el sufijo _g y se les da formato como GUID, incluso si el valor entrante no incluye guiones. Por ejemplo, "8145d822-13a7-44ad-859c-36f31a84f6dd" y "8145d82213a744ad859c36f31a84f6dd" se almacenan como "8145d822-13a7-44ad-859c-36f31a84f6dd". Las únicas diferencias entre esta cadena y otra son el _g en el nombre y la inserción de guiones si no se proporcionan en la entrada.

El tipo de datos que usa Azure Monitor para cada propiedad depende de si el tipo de registro del nuevo registro ya existe.

  • Si el tipo de registro no existe, Azure Monitor crea uno nuevo mediante la inferencia de tipos JSON para determinar el tipo de datos para cada propiedad del nuevo registro.
  • Si el tipo de registro existe, Azure Monitor intenta crear un registro basado en las propiedades existentes. Si el tipo de datos de una propiedad del nuevo registro no coincide y no se puede convertir al tipo existente, o si el registro incluye una propiedad que no existe, Azure Monitor crea una nueva propiedad que tiene el sufijo correspondiente.

Por ejemplo, la siguiente entrada de envío crearía un registro con tres propiedades, number_d, boolean_by string_s:

Captura de pantalla del registro de ejemplo 1.

Si fuera a enviar esta siguiente entrada, con todos los valores con formato de cadenas, las propiedades no cambiarían. Puede convertir los valores en tipos de datos existentes.

Captura de pantalla del registro de ejemplo 2.

Sin embargo, si realiza este siguiente envío, Azure Monitor crearía las nuevas propiedades boolean_d y string_d. No se pueden convertir estos valores.

Captura de pantalla del registro de ejemplo 3.

Si envía la entrada siguiente, antes de crear el tipo de registro, Azure Monitor crearía un registro con tres propiedades, number_s, boolean_sy string_s. En esta entrada, cada uno de los valores iniciales tiene el formato de cadena:

Captura de pantalla del registro de ejemplo 4.

Propiedades reservadas

Las siguientes propiedades están reservadas y no deben usarse en un tipo de registro personalizado. Recibirá un error si la carga incluye cualquiera de estos nombres de propiedad:

  • arrendatario
  • TimeGenerated
  • RawData

Límites de datos

Los datos publicados en la API de recopilación de datos de Azure Monitor están sujetos a ciertas restricciones:

  • Máximo de 30 MB por publicación en Azure Monitor Data Collector API. Se trata de un límite de tamaño para una sola publicación. Si los datos de una sola publicación superan los 30 MB, debe dividir los datos en fragmentos de tamaño más pequeño y enviarlos simultáneamente.
  • Máximo de 32 KB para los valores de campo. Si el valor del campo es mayor que 32 KB, los datos se truncarán.
  • Se recomienda un máximo de 50 campos para un tipo determinado. Se trata de un límite práctico desde una perspectiva de facilidad de uso y experiencia de búsqueda.
  • Las tablas de las áreas de trabajo de Log Analytics solo admiten hasta 500 columnas (denominadas campos de este artículo).
  • Máximo de 45 caracteres para los nombres de columna.

Códigos de retorno

El código de estado HTTP 200 significa que la solicitud se ha recibido para su procesamiento. Esto indica que la operación finalizó correctamente.

El conjunto completo de códigos de estado que el servicio puede devolver aparece en la tabla siguiente:

Código Estado Código de error Descripción
200 De acuerdo La solicitud se aceptó correctamente.
400 Solicitud incorrecta ClienteInactivo Se ha cerrado el área de trabajo.
400 Solicitud incorrecta VersiónApiInválida El servicio no reconoció la versión de LA API que especificó.
400 Solicitud incorrecta IdDeClienteInválido El identificador de área de trabajo especificado no es válido.
400 Solicitud incorrecta FormatoDeDatosNoVálido Se envió un JSON no válido. El cuerpo de la respuesta puede contener más información sobre cómo resolver el error.
400 Solicitud incorrecta TipoDeRegistroInválido El tipo de registro especificado contenía caracteres especiales o numéricos.
400 Solicitud incorrecta FaltaVersiónAPI No se especificó la versión de la API.
400 Solicitud incorrecta TipoDeContenidoFaltante No se especificó el tipo de contenido.
400 Solicitud incorrecta TipoDeRegistroFaltante No se especificó el tipo de registro de valores requerido.
400 Solicitud incorrecta TipoDeContenidoNoCompatible No se configuró el tipo de contenido como application/json.
403 Prohibido Autorización no válida El servicio no pudo autenticar la solicitud. Compruebe que el identificador del área de trabajo y la clave de conexión son válidos.
404 No encontrado La dirección URL proporcionada es incorrecta o la solicitud es demasiado grande.
429 Demasiadas solicitudes El servicio está experimentando un alto volumen de datos de su cuenta. Vuelva a intentar la solicitud más adelante.
500 Error interno del servidor UnspecifiedError El servicio encontró un error interno. Vuelva a intentar la solicitud.
503 Servicio no disponible Servicio No Disponible El servicio no está disponible actualmente para recibir solicitudes. Vuelva a intentar la solicitud.

Consulta de datos

Para consultar los datos enviados por la API del recopilador de datos HTTP de Azure Monitor, busque registros cuyo tipo de sea igual al LogType valor que especificó y anexó con _CL. Por ejemplo, si usó MyCustomLog, devolverá todos los registros con MyCustomLog_CL.

Solicitudes de ejemplo

En esta sección se muestran ejemplos que muestran cómo enviar datos a la API del recopilador de datos HTTP de Azure Monitor mediante varios lenguajes de programación.

Para cada ejemplo, establezca las variables para el encabezado de autorización haciendo lo siguiente:

  1. En Azure Portal, busque el área de trabajo de Log Analytics.
  2. Seleccione Agentes.
  3. A la derecha del ID del área de trabajo , seleccione el icono Copiar y, a continuación, pegue el ID como valor de la variable ID de cliente.
  4. A la derecha de la Clave principal, seleccione el icono Copiar y, a continuación, pegue la ID como valor de la variable Clave compartida.

Como alternativa, puede cambiar las variables para el tipo de registro y los datos JSON.

# Replace with your Workspace ID
$CustomerId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"  

# Replace with your Primary Key
$SharedKey = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Specify the name of the record type that you'll be creating
$LogType = "MyRecordType"

# Optional name of a field that includes the timestamp for the data. If the time field is not specified, Azure Monitor assumes the time is the message ingestion time
$TimeStampField = ""

# Create two records with the same set of properties to create
$json = @"
[{  "StringValue": "MyString1",
    "NumberValue": 42,
    "BooleanValue": true,
    "DateValue": "2019-09-12T20:00:00.625Z",
    "GUIDValue": "9909ED01-A74C-4874-8ABF-D2678E3AE23D"
},
{   "StringValue": "MyString2",
    "NumberValue": 43,
    "BooleanValue": false,
    "DateValue": "2019-09-12T20:00:00.625Z",
    "GUIDValue": "8809ED01-A74C-4874-8ABF-D2678E3AE23D"
}]
"@

# Create the function to create the authorization signature
Function Build-Signature ($customerId, $sharedKey, $date, $contentLength, $method, $contentType, $resource)
{
    $xHeaders = "x-ms-date:" + $date
    $stringToHash = $method + "`n" + $contentLength + "`n" + $contentType + "`n" + $xHeaders + "`n" + $resource

    $bytesToHash = [Text.Encoding]::UTF8.GetBytes($stringToHash)
    $keyBytes = [Convert]::FromBase64String($sharedKey)

    $sha256 = New-Object System.Security.Cryptography.HMACSHA256
    $sha256.Key = $keyBytes
    $calculatedHash = $sha256.ComputeHash($bytesToHash)
    $encodedHash = [Convert]::ToBase64String($calculatedHash)
    $authorization = 'SharedKey {0}:{1}' -f $customerId,$encodedHash
    return $authorization
}

# Create the function to create and post the request
Function Post-LogAnalyticsData($customerId, $sharedKey, $body, $logType)
{
    $method = "POST"
    $contentType = "application/json"
    $resource = "/api/logs"
    $rfc1123date = [DateTime]::UtcNow.ToString("r")
    $contentLength = $body.Length
    $signature = Build-Signature `
        -customerId $customerId `
        -sharedKey $sharedKey `
        -date $rfc1123date `
        -contentLength $contentLength `
        -method $method `
        -contentType $contentType `
        -resource $resource
    $uri = "https://" + $customerId + ".ods.opinsights.azure.com" + $resource + "?api-version=2016-04-01"

    $headers = @{
        "Authorization" = $signature;
        "Log-Type" = $logType;
        "x-ms-date" = $rfc1123date;
        "time-generated-field" = $TimeStampField;
    }

    $response = Invoke-WebRequest -Uri $uri -Method $method -ContentType $contentType -Headers $headers -Body $body -UseBasicParsing
    return $response.StatusCode

}

# Submit the data to the API endpoint
Post-LogAnalyticsData -customerId $customerId -sharedKey $sharedKey -body ([System.Text.Encoding]::UTF8.GetBytes($json)) -logType $logType

Alternativas y consideraciones

Aunque Data Collector API debe cubrir la mayoría de sus necesidades a medida que recopila datos de forma libre en los registros de Azure, es posible que necesite un enfoque alternativo para superar algunas de las limitaciones de la API. Las opciones, incluidas las consideraciones principales, se enumeran en la tabla siguiente:

Alternativo Descripción Más adecuado para
Eventos personalizados: recopilación basada en SDK nativo en Application Insights Application Insights, normalmente instrumentado a través de un SDK dentro de la aplicación, ofrece la posibilidad de enviar datos personalizados a través de eventos personalizados.
  • Datos generados dentro de la aplicación, pero que no los recoge el SDK a través de uno de los tipos de datos predeterminados (solicitudes, dependencias, excepciones, etc.).
  • Datos que se correlacionan con más frecuencia con otros datos de la aplicación en Application Insights.
Data Collector API en los registros de Azure Monitor Data Collector API en los registros de Azure Monitor es una manera completamente abierta de ingerir datos. Los datos con formato en un objeto JSON se pueden enviar aquí. Una vez enviado, se procesa y se pone a disposición de los registros de supervisión para correlacionarse con otros datos de Los registros de supervisión o con otros datos de Application Insights.

Es bastante fácil cargar los datos como archivos en un blob de Azure Blob Storage, donde se procesarán los archivos y, a continuación, se cargarán en Log Analytics. Para obtener una implementación de ejemplo, consulte Creación de una canalización de datos con data Collector API.
  • Datos que no se generan necesariamente dentro de una aplicación que se instrumenta en Application Insights.
    Algunos ejemplos son las tablas de búsqueda y hechos, los datos de referencia, las estadísticas preagregadas, etc.
  • Datos a los que se hará referencia cruzada con otros datos de Azure Monitor (Application Insights, otros tipos de datos de registros de supervisión, Defender for Cloud, Container Insights y máquinas virtuales, etc.).
Azure Data Explorer Azure Data Explorer, ahora disponible con carácter general para el público, es la plataforma de datos que impulsa Application Insights Analytics y los registros de Azure Monitor. Mediante el uso de la plataforma de datos en su forma sin procesar, tiene una flexibilidad completa (pero requiere la sobrecarga de administración) en el clúster (control de acceso basado en rol (RBAC) de Kubernetes, tasa de retención, esquema, etc. Azure Data Explorer proporciona muchas opciones de ingesta , incluidos archivos CSV, TSV y JSON.
  • Datos que no se correlacionarán con ningún otro dato en Application Insights o en los registros de monitorización.
  • Datos que requieren funcionalidades avanzadas de ingesta o procesamiento que no están disponibles actualmente en los registros de Azure Monitor.

Pasos siguientes