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. L’application envoie des données à un point de terminaison de collecte de données (DCE), qui est un point de connexion unique pour votre abonnement Azure. 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é.

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.
Point de terminaison de collecte de données (DCE) Le DCE fournit un point de terminaison à l’application vers lequel envoyer. Une seule DCE peut prendre en charge plusieurs contrôleurs de domaine. Vous pouvez donc utiliser une DCE existante si vous en avez déjà une dans la même région que votre espace de travail Log Analytics.

Consultez Créer un point de terminaison de collecte de données.
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 .

créer manuellement desDCR

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 pour l’API d’ingestion de journaux d’activité et modifiez les paramètres suivants dans le modèle. Utilisez ensuite 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. Cela doit correspondre à la région de la DCE et à l’espace de travail Log Analytics.
dataCollectionEndpointId ID de ressource de votre DCE.
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 transformera les données pour qu’elles correspondent au schéma de table.
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>.

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 de point de terminaison

L’URI de point de terminaison respecte le format suivant, où Data Collection Endpoint et DCR Immutable ID identifient le point de terminaison de collecte de données et la règle de collecte de données. L’ID immuable est généré pour le DCR lors de sa création. Vous pouvez le récupérer à partir de la vue JSON du DCR dans le portail Azure. 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.

{Data Collection Endpoint URI}/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

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