Tutoriel : envoyer des données à Azure Monitor avec l’API d’ingestion des journaux (modèles Resource Manager)
L’API d’ingestion des journaux dans Azure Monitor vous permet d’envoyer des données externes à un espace de travail Log Analytics avec une API REST. Ce tutoriel utilise des modèles Azure Resource Manager (modèles ARM) pour parcourir la configuration des composants nécessaires à la prise en charge de l’API, puis fournit un exemple d’application utilisant à la fois l’API REST et les bibliothèques clientes pour .NET, Go, Java, JavaScript et Python.
Remarque
Ce tutoriel utilise des modèles ARM pour configurer les composants nécessaires à la prise en charge de l’API d’ingestion des journaux. Veuillez consulter le Tutoriel : envoyer des données aux journaux Azure Monitor avec l’API d’ingestion des journaux (Portail Azure) pour un tutoriel similaire qui utilise l’IU du Portail Microsoft Azure pour configurer ces composants.
Les étapes requises pour configurer l’API d’ingestion des journaux sont les suivantes :
- Créez une application Microsoft Entra pour vous authentifier auprès de l’API.
- Créez un point de terminaison de collecte de données (DCE) pour recevoir des données.
- Créez une table personnalisée dans un espace de travail Log Analytics. C’est la table à laquelle vous allez envoyer des données.
- Créez une règle de collecte de données (DCR) pour diriger les données vers la table cible.
- Accordez à l’application Microsoft Entra un accès au DCR.
- Veuillez consulter la rubrique Exemple de code pour envoyer des données à Azure Monitor à l’aide de l’API d’ingestion des journaux pour obtenir un exemple de code permettant d’envoyer des données avec l’API d’ingestion de journaux d’activité.
Prérequis
Pour suivre ce didacticiel, vous avez besoin des éléments suivants :
- Un espace de travail Log Analytics dans lequel vous avez au moins des droits de contributeur.
- Autorisations pour créer des objets de règle de collecte de données (DCR) dans l’espace de travail.
Collecter les détails de l’espace de travail
Commencez par rassembler les informations dont vous aurez besoin à partir de votre espace de travail.
Accédez à votre espace de travail dans le menu Espaces de travail Log Analytics du portail Azure. Dans la pagePropriétés, copiez l’ID de ressource et enregistrez-le pour une utilisation ultérieure.
Créer une application Microsoft Entra
Commencez par inscrire une application Microsoft Entra pour vous authentifier auprès de l’API. Tous les schémas d’authentification Resource Manager sont pris en charge, mais ce tutoriel suit le schéma de flux d’octroi d’informations d’identification du client.
Dans le menu Microsoft Entra ID du Portail Azure, sélectionnez Inscriptions d’applications>Nouvelle inscription.
Donnez un nom à l’application et modifiez l’étendue de location si la valeur par défaut n’est pas adaptée à votre environnement. Un URI de redirection n’est pas obligatoire.
Après l’inscription, vous pouvez consulter les détails de l’application. Notez les valeurs ID d’application (client) et ID de l’annuaire (locataire). Vous en aurez besoin ultérieurement dans le processus.
Générez un secret client d’application. La procédure est similaire à la création d’un mot de passe à utiliser avec un nom d’utilisateur. Sélectionnez Certificats et secrets>Nouveau secret client. Donnez un nom au secret pour identifier sa finalité et sélectionnez une durée d’expiration. L’option 12 mois est sélectionnée ici. Pour une implémentation en production, vous devez suivre les bonnes pratiques concernant une procédure de permutation des secrets ou utiliser un mode d’authentification plus sécurisé, comme un certificat.
Sélectionnez Ajouter pour enregistrer le secret, puis notez la Valeur. Veillez à enregistrer cette valeur, car vous ne pouvez pas la récupérer une fois que vous avez quitté cette page. Prenez les mêmes mesures de sécurité que pour la conservation sécurisée d’un mot de passe, car il s’agit de l’équivalent fonctionnel.
Créer un point de terminaison de collecte de données
Un DCE (point de terminaison de collecte de données) est obligatoire pour accepter les données envoyées à Azure Monitor. Après avoir configuré le point de terminaison DCE et que vous l’avez lié à une règle DCR, vous pouvez envoyer des données sur HTTP à partir de votre application. Le point de terminaison de collecte de données doit se trouver dans la même région que le point de terminaison de collecte de données et l’espace de travail Log Analytics où les données vont être envoyées.
Dans la zone de recherche du portail Azure, entrez modèle, puis sélectionnez Déployer un modèle personnalisé.
Sélectionnez Générer votre propre modèle dans l’éditeur.
Collez le modèle ARM suivant dans l’éditeur, puis sélectionnez Enregistrer. Vous n’avez pas besoin de modifier ce modèle, car vous devrez fournir des valeurs pour ses paramètres.
{ "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", "contentVersion": "1.0.0.0", "parameters": { "dataCollectionEndpointName": { "type": "string", "metadata": { "description": "Specifies the name of the Data Collection Endpoint to create." } }, "location": { "type": "string", "defaultValue": "westus2", "metadata": { "description": "Specifies the location for the Data Collection Endpoint." } } }, "resources": [ { "type": "Microsoft.Insights/dataCollectionEndpoints", "name": "[parameters('dataCollectionEndpointName')]", "location": "[parameters('location')]", "apiVersion": "2021-04-01", "properties": { "networkAcls": { "publicNetworkAccess": "Enabled" } } } ], "outputs": { "dataCollectionEndpointId": { "type": "string", "value": "[resourceId('Microsoft.Insights/dataCollectionEndpoints', parameters('dataCollectionEndpointName'))]" } } }Dans l’écran Déploiement personnalisé, spécifiez un Abonnement et un Groupe de ressources pour stocker la règle DCR, puis attribuez des valeurs comme un Nom pour le point de terminaison DCE. L'Emplacement doit être le même que celui de l’espace de travail. La Région est déjà renseignée et est utilisée pour l’emplacement du point de terminaison DCE.
Sélectionnez Vérifier + créer, puis Créer après avoir passé en revue les détails.
Sélectionnez Vue JSON pour afficher d’autres détails sur le point de terminaison DCE. Copiez l’ID de ressource et le point de terminaison logsIngestion dont vous aurez besoin à une étape ultérieure.
Créer une table dans l’espace de travail Log Analytics
La table personnalisée doit être créée avant que vous puissiez lui envoyer des données. Le tableau de ce tutoriel inclut cinq colonnes, comme indiqué dans le schéma ci-dessous. Les propriétés name, type et description sont obligatoires pour chaque colonne. Les propriétés isHidden et isDefaultDisplay sont toutes deux false par défaut si elles ne sont pas explicitement spécifiées. Les types de données possibles sont string, int, long, real, boolean, dateTime, guid et dynamic.
Notes
Ce tutoriel utilise PowerShell depuis Azure Cloud Shell pour passer des appels d’API REST à l’aide de l’API Tables d’Azure Monitor. Vous pouvez utiliser n’importe quelle autre méthode valide pour effectuer ces appels.
Important
Les tables personnalisées doivent utiliser un suffixe de _CL.
Sélectionnez le bouton Cloud Shell dans le portail Azure et vérifiez que l’environnement est défini sur PowerShell.
Copiez le code PowerShell suivant, puis remplacez les variables du paramètre Chemin d’accès par les valeurs appropriées pour votre espace de travail dans la commande
Invoke-AzRestMethod. Collez-le dans l’invite Cloud Shell pour l’exécuter.$tableParams = @' { "properties": { "schema": { "name": "MyTable_CL", "columns": [ { "name": "TimeGenerated", "type": "datetime", "description": "The time at which the data was generated" }, { "name": "Computer", "type": "string", "description": "The computer that generated the data" }, { "name": "AdditionalContext", "type": "dynamic", "description": "Additional message properties" }, { "name": "CounterName", "type": "string", "description": "Name of the counter" }, { "name": "CounterValue", "type": "real", "description": "Value collected for the counter" } ] } } } '@ Invoke-AzRestMethod -Path "/subscriptions/{subscription}/resourcegroups/{resourcegroup}/providers/microsoft.operationalinsights/workspaces/{workspace}/tables/MyTable_CL?api-version=2022-10-01" -Method PUT -payload $tableParams
Créer une règle de collecte de données
La règle de collecte de données définit la façon dont les données seront gérées une fois qu’elles seront reçues. notamment :
- Schéma des données en cours d’envoi au point de terminaison
- Transformation qui sera appliquée aux données avant leur envoi à l’espace de travail
- Espace de travail et table de destination vers lesquels les données transformées seront envoyées
Dans la zone de recherche du portail Azure, entrez modèle, puis sélectionnez Déployer un modèle personnalisé.
Sélectionnez Générer votre propre modèle dans l’éditeur.
Collez le modèle ARM suivant dans l’éditeur, puis sélectionnez Enregistrer.
Notez les détails suivants dans la DCR défini dans ce modèle :
dataCollectionEndpointId: ID de ressource du point de terminaison de collecte de données.streamDeclarations: définitions de colonne des données entrantes.destinations: espace de travail de destination.dataFlows: correspond au flux de travail avec l’espace de travail de destination et spécifie la requête de transformation et la table de destination. Le résultat (ou « sortie ») de la requête de destination correspond à ce qui sera envoyé à la table de destination.
{ "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#", "contentVersion": "1.0.0.0", "parameters": { "dataCollectionRuleName": { "type": "string", "metadata": { "description": "Specifies the name of the Data Collection Rule to create." } }, "location": { "type": "string", "metadata": { "description": "Specifies the location in which to create the Data Collection Rule." } }, "workspaceResourceId": { "type": "string", "metadata": { "description": "Specifies the Azure resource ID of the Log Analytics workspace to use." } }, "endpointResourceId": { "type": "string", "metadata": { "description": "Specifies the Azure resource ID of the Data Collection Endpoint to use." } } }, "resources": [ { "type": "Microsoft.Insights/dataCollectionRules", "name": "[parameters('dataCollectionRuleName')]", "location": "[parameters('location')]", "apiVersion": "2021-09-01-preview", "properties": { "dataCollectionEndpointId": "[parameters('endpointResourceId')]", "streamDeclarations": { "Custom-MyTableRawData": { "columns": [ { "name": "Time", "type": "datetime" }, { "name": "Computer", "type": "string" }, { "name": "AdditionalContext", "type": "string" }, { "name": "CounterName", "type": "string" }, { "name": "CounterValue", "type": "real" } ] } }, "destinations": { "logAnalytics": [ { "workspaceResourceId": "[parameters('workspaceResourceId')]", "name": "myworkspace" } ] }, "dataFlows": [ { "streams": [ "Custom-MyTableRawData" ], "destinations": [ "myworkspace" ], "transformKql": "source | extend jsonContext = parse_json(AdditionalContext) | project TimeGenerated = Time, Computer, AdditionalContext = jsonContext, CounterName=tostring(jsonContext.CounterName), CounterValue=toreal(jsonContext.CounterValue)", "outputStream": "Custom-MyTable_CL" } ] } } ], "outputs": { "dataCollectionRuleId": { "type": "string", "value": "[resourceId('Microsoft.Insights/dataCollectionRules', parameters('dataCollectionRuleName'))]" } } }Dans l’écran Déploiement personnalisé, spécifiez un abonnement et un groupe de ressources pour stocker la règle DCR. Fournissez ensuite les valeurs définies dans le modèle. Les valeurs incluent un Nom pour la règle DCR et l’ID de ressource d’espace de travail que vous avez collecté au cours d’une étape précédente. L' Emplacement doit être le même que celui de l’espace de travail. La Région est déjà renseignée et est utilisée pour l’emplacement de la règle DCR.
Sélectionnez Vérifier + créer, puis Créer après avoir passé en revue les détails.
Une fois le déploiement effectué, développez la zone Détails du déploiement et sélectionnez votre règle DCR pour afficher les détails. Sélectionnez Vue JSON.
Copiez l’ID immuable de la règle DCR. Vous l’utiliserez ultérieurement lorsque vous utiliserez l’API pour envoyer des exemples de données.
Notes
Toutes les propriétés de la règle DCR, telles que la transformation, peuvent ne pas être affichées dans le portail Azure, même si la règle DCR a été correctement créée avec ces propriétés.
Attribuer des autorisations à une règle DCR
Une fois la règle DCR créée, une autorisation doit être octroyée à l’application sur cette règle. Cette autorisation permet à toute application utilisant l’ID d’application et la clé d’application corrects d’envoyer des données au nouveau point de terminaison DCE et à la nouvelle règle DCR.
À partir de la règle DCR sur le portail Azure, sélectionnez Contrôle d’accès (IAM)>Ajouter une attribution de rôle.
Sélectionnez Éditeur des métriques de monitoring, puis sélectionnez Suivant. Au lieu de cela, vous pouvez créer une action personnalisée avec l’action de données
Microsoft.Insights/Telemetry/Write.
Sélectionnez Utilisateur, groupe ou principal du service pour Attribuer l’accès à, puis choisissez Sélectionner des membres. Sélectionnez l’application que vous avez créée, puis choisissez Sélectionner.
Sélectionnez Vérifier + attribuer, puis passez en revue les détails avant d’enregistrer votre attribution de rôle.
Exemple de code
Veuillez consulter la rubrique Exemple de code pour envoyer des données à Azure Monitor à l’aide de l’API d’ingestion des journaux pour obtenir un exemple de code à l’aide des composants créés dans ce tutoriel.