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. Consultez 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 à l’aide de l’API d’ingestion des journaux.

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). Choisissez d’utiliser l’un ou l’autre, mais une DCE est requise 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 identifiant d’application (client) et identifiant de répertoire (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.

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 l’avoir lié à une DCR, vous pouvez envoyer des données via HTTP depuis 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.

  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. Vous n’avez pas besoin de modifier ce modèle, car vous devrez fournir des valeurs pour ses paramètres.

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

    {
    "$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'))]"
        }
    }
}

  4. Sur l’écran Déploiement personnalisé, spécifiez un Abonnement et un Groupe de ressources pour stocker la DCR, puis renseignez des valeurs telles qu’un Nom pour le point de terminaison de collecte de données (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.

    Capture d’écran de la modification des valeurs de déploiement personnalisé.

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

  6. Sélectionnez Affichage JSON pour afficher d’autres détails concernant le point de terminaison DCE. Copiez l’ID de ressource et le point de terminaison logsIngestion dont vous aurez besoin à une étape ultérieure.

    Capture d’écran montrant l’ID de la ressource DCE.

Créer une table dans l’espace de travail Log Analytics

Une table personnalisée doit être créée avant de pouvoir y envoyer des données. Tenez compte de ces contraintes lorsque vous créez la table :

  • 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, , intlongreal, boolean, dateTime, et .dynamic L’API et l’interface utilisateur du portail acceptent guid comme type de colonne, mais les GUID sont stockés et interrogés en tant que type string. Lorsque vous définissez le flux dans votre règle de collecte de données, déclarez les colonnes GUID en tant que string. Pour plus d’informations, consultez les colonnes GUID et les différences de type de données.
  • Les tables personnalisées doivent utiliser un suffixe de _CL.

Remarque

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.

  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 : Associe le flux à l’espace de travail de destination et spécifie la requête de transformation ainsi que 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."
            }
        }
    },
    "resources": [
        {
            "type": "Microsoft.Insights/dataCollectionRules",
            "name": "[parameters('dataCollectionRuleName')]",
            "location": "[parameters('location')]",
            "apiVersion": "2023-03-11",
            "kind": "Direct",
            "properties": {
                "streamDeclarations": {
                    "Custom-MyTable": {
                        "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-MyTable"
                        ],
                        "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. Sur l’écran Déploiement personnalisé, indiquez un abonnement et un groupe de ressources pour stocker le DCR. Fournissez ensuite les valeurs définies dans le modèle. Les valeurs comprennent un Nom pour la DCR et l’ID de ressource de l’espace de travail que vous avez relevé lors 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 du point de terminaison 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 terminé, développez la section Détails du déploiement et sélectionnez votre DCR pour en afficher les détails. Sélectionnez Vue JSON.

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

  4. Copiez l’identifiant 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 DCR.

Attribuer des autorisations à une DCR

Une fois le DCR créé, l’application doit être autorisée à y accéder. 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 de rôle 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’affectation du rôle 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 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

  • Dernière mise à jour :