Partager via

API Ingestion des journaux dans Azure Monitor

  • Article

L’API d’ingestion des journaux dans Azure Monitor vous permet d’envoyer des données à un espace de travail Log Analytics à l’aide d’un appel d’API REST ou de bibliothèques clientes. L’API vous permet d’envoyer des données à tables Azure prises en charge ou à tables personnalisées que vous créez. Vous pouvez également étendre le schéma des tables Azure avec des colonnes personnalisées pour accepter des données supplémentaires.

Fonctionnement de base

Les données peuvent être envoyées à l’API d’ingestion des journaux à partir de n’importe quelle application pouvant effectuer un appel d’API REST. Il peut s’agir d’une application personnalisée que vous créez, ou il peut s’agir d’une application ou d’un agent qui comprend comment envoyer des données à l’API. Il spécifie une règle de collecte de données (DCR) qui inclut la table cible et l’espace de travail et les informations d’identification d’une inscription d’application avec accès au DCR spécifié. Il envoie les données à un point de terminaison spécifié par le DCR ou à un point de terminaison de collecte de données (DCE) si vous utilisez une liaison privée.

Les données envoyées par votre application à l’API doivent être mises en forme au format JSON et correspondre à la structure attendue par la DCR. Il n’est en revanche pas nécessaire qu’elles soient calquées sur la structure de la table cible. En effet, la règle de collecte de données peut inclure une transformation permettant de convertir les données suivant la structure de la table. Vous pouvez changer la table et l’espace de travail cibles en modifiant la règle de collecte de données sans avoir à toucher à l’appel d’API ni aux données sources.

Diagramme de vue d’ensemble de l’API d’ingestion des journaux.

Configuration

Le tableau suivant décrit chaque composant dans Azure que vous devez configurer avant de pouvoir utiliser l’API d’ingestion des journaux.

Remarque

Pour obtenir un script PowerShell qui automatise la configuration de ces composants, consultez exemple de code pour envoyer des données à Azure Monitor à l’aide de l’API d’ingestion de journaux.

Composant Fonction
Inscription et secret de l’application L’inscription de l’application est utilisée pour authentifier l’appel d’API. Elle doit être accordée à la DCR décrite ci-dessous. L’appel d’API inclut l’ID d’application (client) et l’ID d’annuaire (locataire) de l’application et la valeur d’une clé secrète d’application.

Consultez Créer une application Microsoft Entra et un principal de service qui peuvent accéder aux ressources et Créer un secret d’application.
Tableau dans l’espace de travail Log Analytics La table de l’espace de travail Log Analytics doit exister avant de pouvoir y envoyer des données. Vous pouvez utiliser l’une des tables Azure prises en charge ou créer une table personnalisée à l’aide de l’une des méthodes disponibles. Si vous utilisez le portail Azure pour créer la table, le DCR est créé pour vous, y compris une transformation si nécessaire. Avec toute autre méthode, vous devez créer la DCR manuellement, comme décrit dans la section suivante.

Consultez Créer une table personnalisée.
Règle de collecte de données (DCR) Azure Monitor utilise la règle de collecte de données (DCR) pour comprendre la structure des données entrantes et ce qu’il faut faire avec elle. Si la structure de la table et les données entrantes ne correspondent pas, la DCR peut inclure une transformation de pour convertir les données sources en fonction de la table cible. Vous pouvez également utiliser la transformation pour filtrer les données sources et effectuer d’autres calculs et conversions.

Si vous créez une table personnalisée à l’aide du portail Azure, la DCR et la transformation sont créées pour vous en fonction d’exemples de données que vous fournissez. Si vous utilisez une table existante ou créez une table personnalisée à l’aide d’une autre méthode, vous devez créer manuellement la DCR à l’aide de détails dans la section suivante.

Une fois votre DCR créé, vous devez lui accorder l’accès pour l’application que vous avez créée à la première étape. Dans le menu Monitor dans le portail Azure, sélectionnez règles de collecte de données , puis le DCR que vous avez créé. Sélectionnez contrôle d’accès (IAM) pour la DCR, puis sélectionnez Ajouter une attribution de rôle pour ajouter le rôle éditeur de métriques de surveillance .

Point de terminaison

Le point de terminaison d’API REST pour l’API d’ingestion de journaux d’activité peut être un point de terminaison de collecte de données (DCE) ou le point de terminaison d’ingestion de journaux d’activité DCR.

Le point de terminaison d’ingestion de journaux d’activité DCR est généré lorsque vous créez une DCR pour l’ingestion directe. Pour récupérer ce point de terminaison, ouvrez la DCR dans la vue JSON du Portail Azure. Vous devrez peut-être remplacer la version de l’API par la dernière version pour que les points de terminaison s’affichent.

Capture d’écran montrant le point de terminaison d’ingestion de journaux d’activité dans une DCR.

Une DCE est requise uniquement lorsque vous vous connectez à un espace de travail Log Analytics à l’aide d’une liaison privée ou si votre DCR n’inclut pas le point de terminaison d’ingestion de journaux d’activité. Cela peut être le cas si vous utilisez une DCR plus ancienne ou si vous avez créé la DCR sans le paramètre "kind": "Direct". Pour plus d’informations, consultez Règle de collecte de données (DCR) ci-dessous.

Remarque

La propriété logsIngestion a été ajoutée le 31 mars 2024. Avant cette date, une DCE était requise pour l’API d’ingestion de journaux d’activité. Vous ne pouvez pas ajouter de points de terminaison à une DCR existante, mais vous pouvez continuer à utiliser toute DCR existante avec des DCE existants. Si vous souhaitez passer à un point de terminaison DCR, vous devez créer une DCR pour remplacer la DCR existante. Une DCR avec des points de terminaison peut également utiliser un DCE. Dans ce cas, vous pouvez choisir d’utiliser soit le DCE, soit les points de terminaison DCR pour chacun des clients qui utilisent la DCR.

Règle de collecte de données (DCR)

Lorsque vous créez une table personnalisée dans un espace de travail Log Analytics à l’aide du Portail Azure, une DCR pouvant être utilisée avec l’API d’ingestion de journaux d’activité est créée pour vous. Si vous envoyez des données à une table qui existe déjà, vous devez créer la DCR manuellement. Commencez par l’exemple de DCR ci-dessous, en remplaçant les valeurs des paramètres suivants dans le modèle. Utilisez l’une des méthodes décrites dans Créer et modifier des règles de collecte de données (DCR) dans Azure Monitor pour créer la DCR.

Paramètre Description
region Région pour créer votre DCR. Elle doit correspondre à la région de l’espace de travail Log Analytics et de la DCE si vous en utilisez une.
dataCollectionEndpointId ID de ressource de votre DCE. Supprimez ce paramètre si vous utilisez le point d’ingestion DCR.
streamDeclarations Remplacez la liste des colonnes par les colonnes de vos données entrantes. Vous n’avez pas besoin de modifier le nom du flux, car cela doit simplement correspondre au nom streams dans dataFlows.
workspaceResourceId ID de ressource de votre espace de travail Log Analytics. Vous n’avez pas besoin de modifier le nom, car cela doit simplement correspondre au nom destinations dans dataFlows.
transformKql Requête KQL à appliquer aux données entrantes. Si le schéma des données entrantes correspond au schéma de la table, vous pouvez utiliser source pour la transformation qui transmettra les données entrantes inchangées. Sinon, utilisez une requête qui transforme les données pour qu’elles correspondent au schéma de table de destination.
outputStream Nom de la table à envoyer les données. Pour une table personnalisée, ajoutez le préfixe nom de table<personnalisé>. Pour une table intégrée, ajoutez le préfixe Microsoft-<nom de table>. 
{
    "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"
            }
        ]
    }
}

Bibliothèques clientes

En plus d’effectuer un appel d’API REST, vous pouvez utiliser les bibliothèques clientes suivantes pour envoyer des données à l’API d’ingestion Logs. Les bibliothèques nécessitent les mêmes composants décrits dans Configuration. Pour obtenir des exemples utilisant chacune de ces bibliothèques, consultez exemple de code pour envoyer des données à Azure Monitor à l’aide de l’API d’ingestion de journaux.

Appel d’API REST

Pour envoyer des données à Azure Monitor avec un appel d’API REST, effectuez un appel POST sur HTTP. Les détails requis pour cet appel sont décrits dans cette section.

URI

L’URI inclut la région, le point de terminaison d’ingestion DCE ou DCR, l’ID de la DCR et le nom du flux. Il spécifie également la version de l’API.

L’URI utilise le format suivant.

{Endpoint}/dataCollectionRules/{DCR Immutable ID}/streams/{Stream Name}?api-version=2023-01-01

Par exemple :

https://my-dce-5kyl.eastus-1.ingest.monitor.azure.com/dataCollectionRules/dcr-000a00a000a00000a000000aa000a0aa/streams/Custom-MyTable?api-version=2023-01-01

L’élément DCR Immutable ID est généré pour la DCR lors de sa création. Vous pouvez l’obtenir à partir de la page de présentation du DCR dans le portail Azure.

Capture d’écran d’une règle de collecte de données montrant l’ID non modifiable.

Stream Name fait référence au Stream Name de la règle de collecte de données qui doit gérer les données personnalisées.

En-têtes

Le tableau suivant décrit les en-têtes de votre appel d’API.

En-tête Requis ? Description
Autorisation Oui Jeton du porteur obtenu via le flux d’informations d’identification du client. Utilisez la valeur d’audience du jeton pour votre cloud :

Cloud public Azure - https://monitor.azure.com
Microsoft Azure géré par le cloud 21Vianet - https://monitor.azure.cn
Cloud Azure US Government - https://monitor.azure.us
Content-Type Oui application/json
Content-Encoding Non gzip
x-ms-client-request-id Non GUID au format chaîne Il s’agit d’un ID de demande qui peut être utilisé par Microsoft à des fins de résolution des problèmes.

Corps

Le corps de l’appel comprend les données personnalisées à envoyer à Azure Monitor. La forme des données doit être un tableau JSON dont la structure des éléments correspond au format attendu par le flux dans la règle de collecte de données. S’il est nécessaire d’envoyer un seul élément dans l’appel d’API, les données doivent être envoyées sous la forme d’un tableau avec un seul élément.

Par exemple :

[
{
    "TimeGenerated": "2023-11-14 15:10:02",
    "Column01": "Value01",
    "Column02": "Value02"
}
]

Vérifiez que le corps de la requête est correctement encodé dans UTF-8 pour éviter tout problème de transmission de données.

Exemple

Consultez exemple de code pour envoyer des données à Azure Monitor à l’aide de l’API d’ingestion logs pour obtenir un exemple d’appel d’API à l’aide de PowerShell.

Tables prises en charge

Les données envoyées à l’API d’ingestion peuvent être envoyées aux tableaux suivants :

Tables Description
Tables personnalisées Toute table personnalisée que vous créez dans votre espace de travail Log Analytics. La table cible doit déjà exister pour que vous puissiez lui envoyer des données. Les tables personnalisées doivent comporter le suffixe _CL.
Tables Azure Les tableaux Azure suivants sont actuellement pris en charge. D’autres tables peuvent être ajoutées à cette liste, car la prise en charge de ces tables est implémentée.

Remarque

Les noms de colonnes doivent commencer par une lettre et peuvent comporter jusqu’à 45 caractères alphanumériques et traits de soulignement (_). _ResourceId, id, _ResourceId, _SubscriptionId, TenantId, Type, UniqueId et Title sont des noms de colonnes réservés. Les colonnes personnalisées que vous ajoutez à une table Azure doivent avoir le suffixe _CF.

Limites et restrictions

Pour connaître les limites liées à l’API d’ingestion des journaux, consultez Limites du service Azure Monitor.

Étapes suivantes