Partager via


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 :

  1. Créez une application Microsoft Entra pour vous authentifier auprès de l’API.
  2. Créez une table personnalisée dans un espace de travail Log Analytics. C’est la table à laquelle vous allez envoyer des données.
  3. Créez une règle de collecte de données (DCR) pour diriger les données vers la table cible.
  4. Accordez à l’application Microsoft Entra un accès au DCR.
  5. 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é.

Remarque

Cet article inclut des options d’utilisation d’un point de terminaison d’ingestion DCR ou d’un point de terminaison de collecte de données (DCE). Vous pouvez choisir d’utiliser l’un ou l’autre utilisateur, mais une DCE est nécessaire avec l’API d’ingestion de journaux si une liaison privée est utilisée. Consultez Quand un DCE est-il nécessaire ?.

Prérequis

Pour suivre ce didacticiel, vous avez besoin des éléments suivants :

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.

Capture d’écran montrant l’ID de ressource de l’espace de travail.

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.

  1. Dans le menu Microsoft Entra ID du Portail Azure, sélectionnez Inscriptions d’applications>Nouvelle inscription.

    Capture d’écran montrant l’écran d’inscription d’application.

  2. 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.

    Capture d’écran montrant les détails de l’application.

  3. 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.

    Capture d’écran montrant l’ID de l’application.

  4. 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.

    Capture d’écran montrant le secret de la nouvelle application.

  5. 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.

    Capture d’écran montrant la valeur du secret de la nouvelle application.

Créer un point de terminaison de collecte de données

Une DCE n’est pas nécessaire si vous utilisez le point de terminaison d’ingestion DCR.

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.

  1. Sélectionnez le bouton Cloud Shell dans le portail Azure et vérifiez que l’environnement est défini sur PowerShell.

    Capture d’écran montrant l’ouverture de Cloud Shell.

  2. 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
  1. Dans la zone de recherche du portail Azure, entrez modèle, puis sélectionnez Déployer un modèle personnalisé.

    Capture d’écran montrant comment déployer un modèle personnalisé.

  2. Sélectionnez Générer votre propre modèle dans l’éditeur.

    Capture d’écran montrant comment générer un modèle dans l’éditeur.

  3. Collez le modèle ARM suivant dans l’éditeur, puis sélectionnez Enregistrer.

    Capture d’écran montrant comment modifier un modèle ARM.

    Notez les détails suivants dans la DCR défini dans ce modèle :

    • 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-08-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."
                }
            }
        },
        "resources": [
            {
                "type": "Microsoft.Insights/dataCollectionRules",
                "name": "[parameters('dataCollectionRuleName')]",
                "location": "[parameters('location')]",
                "apiVersion": "2023-03-11",
                "kind": "Direct",
                "properties": {
                    "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'))]"
            }
        }
    }
    

  1. 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.

    Capture d’écran montrant comment modifier les valeurs de déploiement personnalisées.

  2. Sélectionnez Vérifier + créer, puis Créer après avoir passé en revue les détails.

  3. 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.

    Capture d’écran montrant les détails de la règle DCR.

  4. Copiez l’ID immuable et l’URI d’ingestion des journaux pour la DCR. Vous les utilisez lorsque vous envoyez des données à Azure Monitor à l’aide de l’API.

    Capture d’écran montrant la vue JSON de la règle DCR.

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 à la nouvelle DCR.

  1. À partir de la règle DCR sur le portail Azure, sélectionnez Contrôle d’accès (IAM)>Ajouter une attribution de rôle.

    Capture d’écran montrant l’ajout d’une attribution de rôle personnalisée à la règle DCR.

  2. 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.

    Capture d’écran montrant la sélection d’un rôle pour l’attribution d’un rôle de règle DCR.

  3. 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.

    Capture d’écran montrant la sélection de membres pour l’attribution du rôle de règle DCR.

  4. Sélectionnez Vérifier + attribuer, puis passez en revue les détails avant d’enregistrer votre attribution de rôle.

    Capture d’écran montrant l’enregistrement de l’attribution de rôle de règle DCR.

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.

Étapes suivantes