Fonctions dans les requêtes de journal Azure Monitor

Une fonction est une requête de journal dans Azure Monitor qui peut être utilisée dans d’autres requêtes de journal comme s’il s’agissait d’une commande. Vous pouvez utiliser des fonctions pour fournir des solutions à différents clients et également réutiliser la logique de requête dans votre propre environnement. Cet article décrit comment utiliser les fonctions et comment créer les vôtres.

Autorisations requises

Action	Autorisations requises
Afficher ou utiliser des fonctions	Les autorisations Microsoft.OperationalInsights/workspaces/query/*/read sur l’espace de travail Log Analytics, telles qu’elles sont fournies par le rôle intégré Lecteur Log Analytics, par exemple.
Créer ou modifier des fonctions	Les autorisations microsoft.operationalinsights/workspaces/savedSearches/write pour l’espace de travail Log Analytics, telles qu’elles sont fournies par le rôle intégré Contributeur Log Analytics, par exemple.

Types de fonctions

Il existe deux types de fonctions dans Azure Monitor :

• Fonction de solution : Des fonctions prédéfinies sont incluses dans Azure Monitor. Ces fonctions sont disponibles dans tous les espaces de travail Log Analytics et ne peuvent pas être modifiées.

• Fonctions de l’espace de travail : Ces fonctions sont installées dans un espace de travail Log Analytics particulier. Elles peuvent être modifiées et contrôlées par l’utilisateur.

Fonctions View

Vous pouvez afficher les fonctions de la solution et les fonctions de l’espace de travail dans l’espace de travail actuel à partir de l’onglet Fonctions dans le volet gauche d’un espace de travail Log Analytics. Utilisez Filtre pour filtrer les fonctions incluses dans la liste. Utilisez Grouper par pour modifier leur regroupement. Entrez une chaîne dans le champ Recherche pour rechercher une fonction précise. Placez le curseur sur une fonction pour en afficher les détails, notamment une description et les paramètres.

Utiliser une fonction

Utilisez une fonction dans une requête en tapant son nom avec des valeurs pour les paramètres comme vous le feriez dans une commande. La sortie de la fonction peut être retournée en tant que résultats ou redirigée vers une autre commande.

Ajoutez une fonction à la requête en cours en double-cliquant sur son nom ou en pointant dessus, puis en sélectionnant Utiliser dans l’éditeur. Les fonctions de l’espace de travail sont également incluses dans IntelliSense lorsque vous entrez une requête.

Si une requête requiert des paramètres, fournissez-les en utilisant la syntaxe function_name(param1,param2,...).

Créer une fonction

Portail

Pour créer une fonction à partir de la requête actuelle dans l’éditeur, sélectionnez Enregistrer>Enregistrer en tant que fonction.

Pour créer une fonction avec Log Analytics sur le portail Azure, en sélectionnant Enregistrer, puis en fournissant les informations indiquées dans le tableau suivant :

Paramètre	Description
Nom de la fonction	Nom de la fonction. Le nom ne doit pas inclure d'espace ou de caractères spéciaux. Il ne peut pas non plus commencer par un trait de soulignement (_), car ce caractère est réservé aux fonctions de solution.
Catégorie héritée	Catégorie définie par l’utilisateur pour aider à filtrer et à regrouper des fonctions.
Enregistrer en tant que groupe d’ordinateurs	Enregistrer cette requête comme groupe d'ordinateurs.
Paramètres	Ajoutez un paramètre pour chaque variable de la fonction qui requiert une valeur lorsqu’elle est utilisée. Pour plus d’informations, voir Paramètres de fonction.

modèle Azure Resource Manager

L’exemple suivant utilise le modèle Microsoft.OperationalInsights workspaces/savedSearches pour créer une fonction. Pour plus d’informations sur les modèles Azure Resource Manager, consultez Comprendre la structure et la syntaxe des modèles ARM.

Pour en savoir plus sur la manière de déployer des ressources à partir d’un modèle personnalisé, consultez Déployer des ressources à l’aide de modèles ARM et du Portail Azure.

Remarque

Pour obtenir une liste des exemples disponibles et des conseils sur leur déploiement dans votre abonnement Azure, consultez Exemples Azure Resource Manager pour Azure Monitor.

Fichier de modèle

{
  "$schema": "
https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#"
,
  "contentVersion": "1.0.0.0",
  "resources": [
    {
      "type": "Microsoft.OperationalInsights/workspaces/savedSearches",
      "apiVersion": "2020-08-01",
      "name": "[concat(parameters('workspaceName'), '/', parameters('functionName'))]",
      "location": "[parameters('location')]",
      "properties": {
        "etag": "*",
        "displayName": "[parameters('functionDisplayName')]",
        "category": "[parameters('category')]",
        "query": "[parameters('query')]",
        "functionAlias": "[parameters('functionAlias')]",
        "version": 1
      }
    }
  ],
  "parameters": {
    "workspaceName": {
      "type": "string",
      "metadata": {
        "description": "Name of the Log Analytics workspace"
      }
    },
    "functionName": {
      "type": "string",
      "metadata": {
        "description": "Name of the function"
      }
    },
    "location": {
      "type": "string",
      "metadata": {
        "description": "Location of the Log Analytics workspace"
      }
    },
    "functionDisplayName": {
      "type": "string",
      "metadata": {
        "description": "Display name of the function"
      }
    },
    "category": {
      "type": "string",
      "metadata": {
        "description": "Category of the function"
      }
    },
    "query": {
      "type": "string",
      "metadata": {
        "description": "Kusto query for the function"
      }
    },
    "functionAlias": {
      "type": "string",
      "metadata": {
        "description": "Alias for the function"
      }
    }
  }
}

Paramètres de fonction

Vous pouvez ajouter des paramètres à une fonction pour pouvoir fournir des valeurs pour certaines variables lorsque vous l’appelez. Par conséquent, la même fonction peut être utilisée dans différentes requêtes, chacune fournissant des valeurs différentes pour les paramètres. Les paramètres sont définis par les propriétés suivantes :

Paramètre	Description
Type	Type de données pour la valeur.
Nom	Nom du paramètre. Ce nom doit être utilisé dans la requête pour remplacer la valeur du paramètre.
Valeur par défaut	Valeur à utiliser pour le paramètre si aucune valeur n’est fournie.

Les paramètres sont triés au fur et à mesure de leur création. Les paramètres qui n’ont pas de valeur par défaut sont positionnés devant les paramètres qui ont une valeur par défaut.

Utiliser le code de fonction

Vous pouvez afficher le code d’une fonction pour avoir un aperçu de son fonctionnement ou pour modifier le code d’une fonction de l’espace de travail. Sélectionnez Charger le code de la fonction pour ajouter le code de la fonction à la requête actuelle dans l’éditeur.

Si vous ajoutez le code de la fonction à une requête vide ou à la première ligne d’une requête existante, le nom de la fonction est ajouté à l’onglet. Une fonction de l’espace de travail permet de modifier les détails de la fonction.

Modifier une fonction

Modifiez les propriétés ou le code d’une fonction en créant une nouvelle requête. Placez le curseur sur le nom de la fonction et sélectionnez Charger le code de la fonction. Apportez les modifications souhaitées au code, sélectionnez Enregistrer. Sélectionnez ensuite Modifier les détails de la fonction. Apportez les modifications souhaitées aux propriétés et aux paramètres de la fonction et cliquez sur Enregistrer.

Exemple

L’exemple de fonction suivant renvoie tous les événements du journal d’activité Azure depuis une date précise et qui correspondent à une catégorie précise.

Commencez par la requête suivante en utilisant des valeurs codées en dur pour vérifier que la requête fonctionne comme prévu.

AzureActivity
| where CategoryValue == "Administrative"
| where TimeGenerated > todatetime("2021/04/05 5:40:01.032 PM")

Ensuite, remplacez les valeurs codées en dur par des noms de paramètres. Enregistrez ensuite la fonction en sélectionnant Enregistrer> Enregistrer en tant que fonction.

AzureActivity
| where CategoryValue == CategoryParam
| where TimeGenerated > DateParam

Indiquez les valeurs suivantes pour les propriétés de la fonction :

Propriété	Valeur
Nom de la fonction	AzureActivityByCategory
Catégorie héritée	Fonctions de démonstration

Définissez les paramètres suivants avant d’enregistrer la fonction :

Type	Nom	Valeur par défaut
string	CategoryParam	« Administratif »
DATETIME	DateParam

Créez une nouvelle requête et affichez la nouvelle fonction en pointant dessus. Examinez l’ordre des paramètres. Ils doivent être spécifiés dans cet ordre lorsque vous utilisez la fonction.

Sélectionnez Utiliser dans l’éditeur pour ajouter la nouvelle fonction à une requête. Ajoutez ensuite des valeurs pour les paramètres. Vous n’avez pas besoin de spécifier une valeur pour CategoryParam car la valeur par défaut existe.

Étapes suivantes

Voir Opérations de chaîne pour plus d’informations sur la façon d’écrire des requêtes de journal Azure Monitor.