Partager via

API Ingestion des journaux dans Azure Monitor

L’API d’ingestion des journaux d’activité 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 à des tables Azure prises en charge ou à des 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. Elle n’a pas nécessairement besoin de correspondre à la structure de la table cible, car la DCR peut inclure une transformation pour convertir les données en fonction de 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 montrant une vue d’ensemble de l’API de collecte des journaux d’activité.

Paramétrage

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 l’exemple de code permettant d’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’un secret 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 du portail Azure, sélectionnez les règles de collecte de données , puis la DCR que vous avez créée. Sélectionnez Contrôle d’accès (IAM) pour la DCR, puis ajoutez l’attribution de rôle pour ajouter le rôle Éditeur de métriques de surveillance .

Point de terminaison

Le point de terminaison de l'API REST pour l'API d'ingestion des journaux peut être un point de terminaison de collecte de données (DCE) ou un point de terminaison d'ingestion des journaux 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 des journaux d’activité dans une DCR.

Une DCE est obligatoire uniquement si 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 des 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 la 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é. Les points de terminaison ne peuvent pas être ajoutés à une DCR existante, mais vous pouvez continuer à utiliser les DCR existantes avec les 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, un DCR qui peut être utilisé avec l’API d’ingestion des journaux est créé 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 dans Azure Monitor pour créer la DCR.

Paramètre Descriptif
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 Custom-table-name<>. Pour une table intégrée, ajoutez le préfixe Microsoft-table-name<>. 
{
    "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 des journaux d’activité.

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 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 la récupérer à partir de la page Vue d’ensemble de la DCR dans le portail Azure.

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

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 de requête

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

En-tête Requis ? Descriptif
Autorisation Oui Jeton du porteur obtenu via le flux d’informations d’identification du client. Utilisez la valeur d’audience du jeton (étendue) 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
Type de contenu Oui application/json
Encodage du contenu 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 de la requête

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. Voici un exemple de tableau à élément unique.

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 l’exemple de code permettant d’envoyer des données à Azure Monitor à l’aide de l’API d’ingestion de journaux 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 :

Tableaux Descriptif
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 d’activité, consultez Limites du service Azure Monitor.

Étapes suivantes