Partager via

Envoyer des données de journal à Azure Monitor à l’aide de l’API collecteur de données HTTP (déconseillée)

  • Article

Cet article explique comment utiliser l’API collecteur de données HTTP pour envoyer des données de journal à Azure Monitor à partir d’un client d’API REST. Il décrit comment mettre en forme les données collectées par votre script ou votre application, les inclure dans une demande et demander cette demande autorisée par Azure Monitor. Nous fournissons des exemples pour Azure PowerShell, C# et Python.

Note

L’API collecteur de données HTTP Azure Monitor a été déconseillée et ne sera plus fonctionnelle à compter du 14/9/2026. Elle a été remplacée par l’API d’ingestion Logs.

Concepts

Vous pouvez utiliser l’API collecteur de données HTTP pour envoyer des données de journal à un espace de travail Log Analytics dans Azure Monitor à partir de n’importe quel client qui peut appeler une API REST. Le client peut être un runbook dans Azure Automation qui collecte des données de gestion à partir d’Azure ou d’un autre cloud, ou il peut s’agir d’un autre système de gestion qui utilise Azure Monitor pour consolider et analyser les données de journal.

Toutes les données de l’espace de travail Log Analytics sont stockées sous forme d’enregistrement avec un type d’enregistrement particulier. Vous mettez en forme vos données à envoyer à l’API collecteur de données HTTP en tant qu’enregistrements multiples dans JavaScript Object Notation (JSON). Lorsque vous envoyez les données, un enregistrement individuel est créé dans le référentiel pour chaque enregistrement de la charge utile de la demande.

Capture d’écran illustrant la vue d’ensemble du collecteur de données HTTP.

Créer une demande

Pour utiliser l’API collecteur de données HTTP, vous créez une requête POST qui inclut les données à envoyer au format JSON. Les trois tables suivantes répertorient les attributs requis pour chaque requête. Nous décrivons chaque attribut plus en détail plus loin dans l’article.

URI de requête

Attribut Propriété
Méthode PUBLIER
URI https://<CustomerId>.ods.opinsights.azure.com/api/logs?api-version=2016-04-01
Type de contenu application/json

Paramètres de l’URI de requête

Paramètre Description
CustomerID Identificateur unique de l’espace de travail Log Analytics.
Ressource Nom de la ressource d’API : /api/logs.
Version de l’API Version de l’API à utiliser avec cette requête. Actuellement, la version est 2016-04-01.

En-têtes de requête

En-tête Description
Autorisation Signature d’autorisation. Plus loin dans l’article, vous pouvez découvrir comment créer un en-tête HMAC-SHA256.
Log-Type Spécifiez le type d’enregistrement des données envoyées. Il ne peut contenir que des lettres, des chiffres et le caractère de soulignement (_), et il ne peut pas dépasser 100 caractères.
x-ms-date Date à laquelle la demande a été traitée, au format RFC 1123.
x-ms-AzureResourceId ID de ressource de la ressource Azure à laquelle les données doivent être associées. Il remplit la propriété _ResourceId et permet aux données d’être incluses dans requêtes de contexte de ressources. Si ce champ n’est pas spécifié, les données ne seront pas incluses dans les requêtes de contexte de ressource.
champ généré dans le temps Nom d’un champ dans les données qui contient l’horodatage de l’élément de données. Si vous spécifiez un champ, son contenu est utilisé pour TimeGenerated. Si vous ne spécifiez pas ce champ, la valeur par défaut de TimeGenerated est l’heure à laquelle le message est ingéré. Les contenus du champ de message doivent suivre le format ISO 8601 AAAA-MM-DDThh:mm:ssZ. La valeur de temps générée ne peut pas être antérieure à 2 jours avant l'heure de réception ou plus d'un jour dans le futur. Dans ce cas, l’heure à laquelle le message est ingéré sera utilisé.

Autorisation

Toute demande adressée à l’API collecteur de données HTTP Azure Monitor doit inclure un en-tête d’autorisation. Pour authentifier une demande, signez la demande avec la clé primaire ou secondaire de l’espace de travail qui effectue la requête. Ensuite, transmettez cette signature dans le cadre de la demande.

Voici le format de l’en-tête d’autorisation :

Authorization: SharedKey <WorkspaceID>:<Signature>

WorkspaceID est l’identificateur unique de l’espace de travail Log Analytics. Signature est un code d’authentification de message basé sur le hachage (HMAC) construit à partir de la requête, puis calculé à l’aide de l’algorithme SHA256. Ensuite, vous l’encodez à l’aide de l’encodage Base64.

Utilisez ce format pour encoder la chaîne de signature SharedKey :

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

Voici un exemple de chaîne de signature :

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

Lorsque vous disposez de la chaîne de signature, encodez-la à l’aide de l’algorithme HMAC-SHA256 sur la chaîne encodée UTF-8, puis encodez le résultat en base64. Utilisez ce format :

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

Les exemples des sections suivantes ont un exemple de code pour vous aider à créer un en-tête d’autorisation.

Corps de la demande

Le corps du message doit être au format JSON. Il doit inclure un ou plusieurs enregistrements avec le nom de propriété et les paires valeur au format suivant. Le nom de la propriété ne peut contenir que des lettres, des chiffres et le caractère de soulignement (_).

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

Vous pouvez regrouper plusieurs enregistrements dans une seule requête à l’aide du format suivant. Tous les enregistrements doivent être du même type d’enregistrement.

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

Type d’enregistrement et propriétés

Vous définissez un type d’enregistrement personnalisé lorsque vous envoyez des données via l’API Collecteur de données HTTP Azure Monitor. Actuellement, vous ne pouvez pas écrire de données dans des types d’enregistrements existants qui ont été créés par d’autres types de données et solutions. Azure Monitor lit les données entrantes, puis crée des propriétés qui correspondent aux types de données des valeurs que vous entrez.

Chaque requête adressée à l’API collecteur de données doit inclure un en-tête de type journal avec le nom du type d’enregistrement. Le suffixe _CL est automatiquement ajouté au nom que vous entrez afin de le distinguer d'autres types de journaux comme un journal personnalisé. Par exemple, si vous entrez le nom MyNewRecordType, Azure Monitor crée un enregistrement avec le type MyNewRecordType_CL. Cela permet de s’assurer qu’il n’existe aucun conflit entre les noms de types créés par l’utilisateur et ceux fournis dans les solutions Microsoft actuelles ou futures.

Pour identifier le type de données d’une propriété, Azure Monitor ajoute un suffixe au nom de la propriété. Si une propriété contient une valeur Null, la propriété n’est pas incluse dans cet enregistrement. Ce tableau répertorie le type de données de propriété et le suffixe correspondant :

Type de données de propriété Suffixe
Corde _s
Booléen _b
Double _d
Date/heure _t
GUID (stocké sous forme de chaîne) _g

Note

Les valeurs de chaîne qui semblent être des GUID reçoivent le suffixe _g et elles sont mises en forme en tant que GUID, même si la valeur entrante n’inclut pas de tirets. Par exemple, « 8145d822-13a7-44ad-859c-36f31a84f6dd » et « 8145d82213a744ad8859c36f31a84f6ddd » sont stockés en tant que « 8145d822-13a7-44ad-859c-36f31a84f6dd ». Les seules différences entre cette chaîne et une autre chaîne sont le _g dans le nom et l'ajout de tirets s'ils ne sont pas fournis dans l'entrée.

Le type de données utilisé par Azure Monitor pour chaque propriété varie selon que le type d’enregistrement du nouvel enregistrement existe déjà.

  • Si le type d’enregistrement n’existe pas, Azure Monitor en crée un en utilisant l’inférence de type JSON pour déterminer le type de données de chaque propriété pour le nouvel enregistrement.
  • Si le type d’enregistrement existe, Azure Monitor tente de créer un enregistrement en fonction des propriétés existantes. Si le type de données d’une propriété dans le nouvel enregistrement ne correspond pas et ne peut pas être converti en type existant ou si l’enregistrement inclut une propriété qui n’existe pas, Azure Monitor crée une propriété qui a le suffixe approprié.

Par exemple, l’entrée de soumission suivante crée un enregistrement avec trois propriétés, number_d, boolean_bet string_s:

Capture d’écran de l’exemple d’enregistrement 1.

Si vous deviez soumettre cette entrée suivante, avec toutes les valeurs mises en forme sous forme de chaînes, les propriétés ne changent pas. Vous pouvez convertir les valeurs en types de données existants.

Capture d’écran de l’exemple d’enregistrement 2.

Toutefois, si vous effectuez ensuite cette soumission suivante, Azure Monitor crée les nouvelles propriétés boolean_d et string_d. Vous ne pouvez pas convertir ces valeurs.

Capture d’écran de l’exemple d’enregistrement 3.

Si vous envoyez ensuite l’entrée suivante, avant la création du type d’enregistrement, Azure Monitor crée un enregistrement avec trois propriétés, number_s, boolean_set string_s. Dans cette entrée, chacune des valeurs initiales est mise en forme sous forme de chaîne :

Capture d’écran de l’exemple d’enregistrement 4.

Propriétés réservées

Les propriétés suivantes sont réservées et ne doivent pas être utilisées dans un type d’enregistrement personnalisé. Vous recevrez une erreur si votre charge utile inclut l’un de ces noms de propriétés :

  • locataire
  • TimeGenerated
  • RawData

Limites des données

Les données publiées dans l’API de collecte de données Azure Monitor sont soumises à certaines contraintes :

  • Maximum de 30 Mo par publication sur l’API collecteur de données Azure Monitor. Il s’agit d’une limite de taille pour une publication unique. Si les données d'un message unique dépassent 30 Mo, vous devez diviser les données en blocs de taille plus petite et les envoyer simultanément.
  • Maximum de 32 Ko pour les valeurs de champ. Si la valeur du champ est supérieure à 32 Ko, les données sont tronquées.
  • Maximum recommandé de 50 champs pour un type donné. Il s’agit d’une limite pratique du point de vue de l’utilisation et de l’expérience de recherche.
  • Les tables des espaces de travail Log Analytics ne prennent en charge que jusqu’à 500 colonnes (appelées champs dans cet article).
  • Maximum de 45 caractères pour les noms de colonnes.

Codes de retour

Le code d’état HTTP 200 signifie que la requête a été reçue pour traitement. Cela indique que l’opération s’est terminée correctement.

L’ensemble complet de codes d’état que le service peut retourner est répertorié dans le tableau suivant :

Code Statut Code d’erreur Description
200 D’ACCORD La demande a été acceptée avec succès.
400 Demande incorrecte ClientInactif L’espace de travail a été fermé.
400 Demande incorrecte InvalidApiVersion La version de l’API que vous avez spécifiée n’a pas été reconnue par le service.
400 Demande incorrecte InvalidCustomerId L’ID d’espace de travail spécifié n’est pas valide.
400 Demande incorrecte FormatDeDonnéesInvalide Un JSON non valide a été envoyé. Le corps de la réponse peut contenir plus d’informations sur la résolution de l’erreur.
400 Demande incorrecte InvalidLogType Le type de journal spécifié contenait des caractères spéciaux ou des chiffres.
400 Demande incorrecte MissingApiVersion La version de l’API n’a pas été spécifiée.
400 Demande incorrecte Type de contenu manquant Le type de contenu n’a pas été spécifié.
400 Demande incorrecte TypeDeJournalManquant Le type de journal des valeurs requises n’a pas été spécifié.
400 Demande incorrecte Non pris en charge TypeDeContenu Le type de contenu n’a pas été défini sur application/json.
403 Interdit Autorisation Invalide Le service n’a pas pu authentifier la requête. Vérifiez que l’ID et la clé de connexion de l’espace de travail sont valides.
404 Introuvable L’URL fournie est incorrecte ou la requête est trop volumineuse.
429 Trop de demandes Le service rencontre un volume élevé de données à partir de votre compte. Réessayez la demande ultérieurement.
500 Erreur interne du serveur Erreur non spécifiée Le service a rencontré une erreur interne. Réessayez la demande.
503 Service indisponible Service Indisponible Actuellement, le service n’est pas disponible pour recevoir des demandes. Réessayez votre demande.

Interroger des données

Pour interroger les données soumises par l’API collecteur de données HTTP Azure Monitor, recherchez les enregistrements dont Type est égal à la valeur LogType que vous avez spécifiée et ajoutée avec _CL. Par exemple, si vous avez utilisé MyCustomLog, vous retourneriez tous les enregistrements avec MyCustomLog_CL.

Exemples de requêtes

Dans cette section, vous trouverez des exemples qui montrent comment envoyer des données à l’API collecteur de données HTTP Azure Monitor à l’aide de différents langages de programmation.

Pour chaque exemple, définissez les variables pour l’en-tête d’autorisation en procédant comme suit :

  1. Dans le portail Azure, recherchez votre espace de travail Log Analytics.
  2. Sélectionnez Agents.
  3. À droite de ID de l’espace de travail, sélectionnez l’icône Copier, puis collez l’ID comme valeur de la variable ID client.
  4. À droite de clé primaire, sélectionnez l’icône copier, puis collez l’ID comme valeur de la variable clé partagée.

Vous pouvez également modifier les variables pour le type de journal et les données 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

Alternatives et considérations

Bien que l’API collecteur de données couvre la plupart de vos besoins lorsque vous collectez des données de forme libre dans les journaux Azure, vous devrez peut-être adopter une autre approche pour surmonter certaines des limitations de l’API. Vos options, notamment les principales considérations, sont répertoriées dans le tableau suivant :

Alternatif Description Idéal pour
événements personnalisés: ingestion native basée sur le SDK dans Application Insights Application Insights, généralement instrumenté par le biais d’un KIT de développement logiciel (SDK) au sein de votre application, vous permet d’envoyer des données personnalisées via des événements personnalisés.
  • Données générées au sein de votre application, mais non récupérées par le Kit de développement logiciel (SDK) via l’un des types de données par défaut (demandes, dépendances, exceptions, etc.).
  • Les données qui sont les plus souvent corrélées avec d’autres données d’application dans Application Insights.
API Collecteur de données dans les journaux d'Azure Monitor Dans Azure Monitor, l'API Collecteur de données dans les logs est un moyen totalement libre d'ingérer des données. Toutes les données mises en forme dans un objet JSON peuvent être envoyées ici. Une fois qu'il a été envoyé, il est traité et mis à disposition dans les Monitor Logs pour être mis en corrélation avec d'autres données dans les Monitor Logs ou par rapport à d'autres données d'Application Insights.

Il est assez facile de charger les données en tant que fichiers dans un blob de stockage Azure, où les fichiers seront traités, puis envoyés vers Log Analytics. Pour obtenir un exemple d’implémentation, consultez Créer un pipeline de données avec l’API collecteur de données.
  • Données qui ne sont pas nécessairement générées dans une application instrumentée dans Application Insights.
    Les exemples incluent la recherche et les tables de faits, les données de référence, les statistiques prédéfinies, et ainsi de suite.
  • Données qui seront croisées avec d'autres données d'Azure Monitor (Application Insights, autres types de données de Journaux Monitor, Defender pour le Cloud, Container Insights et machines virtuelles, etc.).
Explorateur de données Azure Azure Data Explorer, désormais en disponibilité générale pour le public, est la plateforme de données qui alimente Application Insights Analytics et les journaux Azure Monitor. En utilisant la plateforme de données sous sa forme brute, vous disposez d'une flexibilité totale (mais cela implique la charge de gestion) sur le cluster (contrôle d'accès basé sur les rôles Kubernetes (RBAC), la période de rétention, le schéma, etc.). Azure Data Explorer fournit de nombreuses options d’ingestion , notamment fichiers CSV, TSV et JSON.
  • Données qui ne seront pas corrélées avec d’autres données sous Application Insights ou Monitor Logs.
  • Les données nécessitant des capacités avancées d'ingestion ou de traitement qui ne sont pas actuellement disponibles dans les journaux d'Azure Monitor.

Étapes suivantes