Configurer une base de données avec un script de langage de requête Kusto

Article
02/19/2024

Vous pouvez exécuter un script Kusto Query Language pour configurer votre base de données durant le déploiement d’un modèle ARM (Azure Resource Manager). Un script est une liste d’une ou plusieurs commandes de gestion, chacune séparée par un saut de ligne, et est créée en tant que ressource accessible avec le modèle ARM.

Le script peut uniquement exécuter des commandes de gestion au niveau de la base de données qui commencent par les verbes suivants :

.create
.create-or-alter
.create-merge
.alter
.alter-merge
.add

Notes

Les commandes prises en charge doivent être exécutées au niveau de la base de données. Par exemple, vous pouvez modifier une table à l’aide de la commande .create-or-alter table. Les commandes au niveau du cluster, telles que .alter cluster les stratégies, ne sont pas prises en charge.

En général, nous recommandons d’utiliser la version idempotente des commandes. De cette façon, si elles sont appelées plus d’une fois avec les mêmes paramètres d’entrée, elles n’ont aucun effet supplémentaire. En d’autres termes, exécuter une commande plusieurs fois revient à l’exécuter une seule fois. Par exemple, dans la mesure du possible, nous vous recommandons d’utiliser la commande idempotente .create-or-alter plutôt que la commande .create habituelle.

Il existe différentes méthodes pour configurer une base de données avec des scripts. Dans cet article, nous nous concentrons sur les méthodes suivantes à l’aide de déploiements de modèles ARM :

Script inline : le script est fourni inline en tant que paramètre à un modèle ARM JSON.
Script Bicep : le script est fourni en tant que fichier distinct utilisé par un modèle ARM Bicep.
Compte de stockage : le script est créé en tant qu’objet blob dans un compte de stockage Azure et ses détails (URL et signatures d’accès partagé (SAS) fournis en tant que paramètres du modèle ARM.

Notes

Chaque cluster peut avoir un maximum de 50 scripts (d’autres scripts déclenchent une Code:TooManyScripts erreur.) Il est recommandé de fusionner plusieurs petits scripts en moins grands, après avoir supprimé les scripts existants pour libérer de l’espace pour les nouveaux scripts. La suppression d’un script ne restaure pas les commandes qui ont été exécutées à partir de ce script.

Exemple de script avec des commandes de gestion

L’exemple suivant est un script avec des commandes qui créent deux tables : MyTable et MyTable2.

.create-merge table MyTable (Level:string, Timestamp:datetime, UserId:string, TraceId:string, Message:string, ProcessId:int32)

.create-merge table MyTable2 (Level:string, Timestamp:datetime, UserId:string, TraceId:string, Message:string, ProcessId:int32)

Notez que les deux commandes sont idempotentes. Lorsqu’elles sont exécutées pour la première fois, les tables sont créées ; mais lors des exécutions suivantes, rien ne se passe.

Prérequis

Un abonnement Azure. Créez un compte Azure gratuit.
Un cluster et une base de données Azure Data Explorer. Créez un cluster et une base de données.

Sécurité

Le principal, tel qu’un utilisateur ou un principal de service, utilisé pour déployer un script doit avoir les rôles de sécurité suivants :

Rôle Contributeur sur le cluster
Rôle Administrateur sur la base de données

Important

Le principal qui provisionne le cluster obtient automatiquement le rôle All Databases Admin sur le cluster.

Script en ligne

Utilisez cette méthode pour créer un modèle ARM avec le script défini en tant que paramètre inline. Si votre script comporte une ou plusieurs commandes de gestion, séparez les commandes par au moins un saut de ligne.

Exécuter un script inline avec un modèle ARM

Le modèle suivant montre comment exécuter le script avec un modèle Azure Resource Manager JSON.

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "kqlScript": {
            "defaultValue": ".create-merge table MyTable (Level:string, Timestamp:datetime, UserId:string, TraceId:string, Message:string, ProcessId:int32)\n\n.create-merge table MyTable2 (Level:string, Timestamp:datetime, UserId:string, TraceId:string, Message:string, ProcessId:int32)",
            "type": "String"
        },
        "forceUpdateTag": {
            "defaultValue": "[utcNow()]",
            "type": "String"
        },
        "continueOnErrors": {
            "defaultValue": false,
            "type": "bool"
        },
        "clusterName": {
            "type": "String"
        },
        "databaseName": {
            "type": "String"
        },
        "scriptName": {
            "type": "String"
        }
    },
    "variables": {
    },
    "resources": [
        {
            "type": "Microsoft.Kusto/Clusters/Databases/Scripts",
            "apiVersion": "2022-02-01",
            "name": "[concat(parameters('clusterName'), '/', parameters('databaseName'), '/', parameters('scriptName'))]",
            "properties": {
                "scriptContent": "[parameters('kqlScript')]",
                "continueOnErrors": "[parameters('continueOnErrors')]",
                "forceUpdateTag": "[parameters('forceUpdateTag')]"
            }
        }
    ],
    "outputs": {
    }
}

Utilisez les paramètres suivants :

Paramètre	Description
kqlScript	Script Kusto Query Language inline. Utilisez `\n` pour ajouter des caractères de nouvelle ligne.
forceUpdateTag	Chaîne unique. En cas de modification, le script est appliqué à nouveau.
continueOnErrors	Indicateur signalant s’il faut continuer en cas d’échec de l’une des commandes. Valeur par défaut : false.
clusterName	Nom du cluster dans lequel le script s’exécute.
databaseName	Nom de la base de données sous laquelle le script s’exécute.
scriptName	Nom du script lors de l’utilisation d’un fichier externe pour fournir le script. Il s’agit du nom du modèle de ressource ARM réelle du type script.

Omettre l’étiquette de mise à jour

L’exécution d’un script KQL à chaque déploiement de modèle ARM n’est pas recommandée en raison des ressources de cluster consommées. Vous pouvez empêcher l’exécution du script dans des déploiements consécutifs à l’aide des méthodes suivantes :

Spécifiez la forceUpdateTag propriété et conservez la même valeur entre les déploiements.
Omettre la propriété forceUpdateTag, ou la laisser vide, et utiliser le même script entre les déploiements.

La meilleure pratique consiste à omettre la forceUpdateTag propriété afin que toutes les modifications de script soient exécutées lors du prochain déploiement du modèle. Utilisez uniquement la propriété forceUpdateTag si vous devez forcer l’exécution du script.

Script Bicep

La transmission d’un script en tant que paramètre à un modèle peut être fastidieuse. Le modèle Azure Resource Manager Bicep vous permet de conserver et de gérer le script dans un fichier séparé et de le charger dans le modèle avec la fonction Bicep loadTextContent.

En supposant que le script est stocké dans un fichier script.kql situé dans le même dossier que le fichier Bicep, le modèle suivant produit le même résultat que l’exemple précédent :

param forceUpdateTag string = utcNow()
param continueOnErrors bool = false
param clusterName string
param databaseName string
param scriptName string

resource cluster 'Microsoft.Kusto/clusters@2022-02-01' existing = {
    name: clusterName
}

resource db 'Microsoft.Kusto/clusters/databases@2022-02-01' existing = {
    name: databaseName
    parent: cluster
}

resource perfTestDbs 'Microsoft.Kusto/clusters/databases/scripts@2022-02-01' = {
    name: scriptName
    parent: db
    properties: {
        scriptContent: loadTextContent('script.kql')
        continueOnErrors: continueOnErrors
        forceUpdateTag: forceUpdateTag
    }
}

Utilisez les paramètres suivants :

Paramètre	Description
forceUpdateTag	Chaîne unique. En cas de modification, le script est appliqué à nouveau.
continueOnErrors	Indicateur signalant de continuer en cas d’échec de l’une des commandes. Valeur par défaut : false.
clusterName	Nom du cluster dans lequel le script s’exécute.
databaseName	Nom de la base de données sous laquelle le script s’exécute.
scriptName	Nom du script lors de l’utilisation d’un fichier externe pour fournir le script.

Le modèle Bicep peut être déployé à l’aide d’outils similaires en tant que modèle ARM JSON. Par exemple, vous pouvez utiliser les commandes Azure CLI suivantes pour déployer le modèle :

az deployment group create -n "deploy-$(uuidgen)" -g "MyResourceGroup" --template-file "json-sample.json" --parameters clusterName=MyCluster databaseName=MyDb

Les modèles Bicep sont transpilés en modèle ARM JSON avant le déploiement. Dans l’exemple, le fichier de script est incorporé dans le modèle ARM JSON. Pour plus d’informations, consultez Vue d’ensemble de Bicep.

Script du compte de stockage

Cette méthode suppose que vous disposez déjà d’un objet blob dans un compte Stockage Azure et que vous fournissez ses détails (URL et signatures d’accès partagé ou SaS) directement dans le modèle ARM.

Notes

Les scripts ne peuvent pas être chargés à partir de comptes de stockage configurés avec des règles de pare-feu ou de réseau virtuel Stockage Azure.

Créer la ressource de script

La première étape consiste à créer un script et à le charger sur un compte de stockage.

Créez un script contenant les commandes de gestion que vous souhaitez utiliser pour créer la table dans votre base de données.
Chargez votre script sur votre compte Stockage Azure. Vous pouvez créer votre compte de stockage en utilisant le portail Azure, PowerShell ou Azure CLI.
Permettez l’accès à ce fichier à l’aide de signatures d’accès partagé (SAS). Vous pouvez fournir l’accès à l’aide de PowerShell, d’Azure CLI ou de .NET.

Exécuter le script avec un modèle ARM

Dans cette section, vous allez apprendre à exécuter un script stocké dans stockage Azure avec un modèle de Resource Manager Azure.

{
  "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
  "contentVersion": "1.0.0.0",
  "parameters": {
    "scriptUrl": {
      "type": "String"
    },
    "scriptUrlSastoken": {
      "type": "SecureString"
    },
    "forceUpdateTag": {
      "defaultValue": "[utcNow()]",
      "type": "String"
    },
    "continueOnErrors": {
      "defaultValue": false,
      "type": "bool"
    },
    "clusterName": {
      "type": "String"
    },
    "databaseName": {
      "type": "String"
    },
    "scriptName": {
      "type": "String"
    }
  },
  "variables": {
  },
  "resources": [
    {
      "type": "Microsoft.Kusto/Clusters/Databases/Scripts",
      "apiVersion": "2021-01-01",
      "name": "[concat(concat(parameters('clusterName'), '/'), concat(parameters('databaseName'), '/'), parameters('scriptName'))]",
      "properties": {
        "scriptUrl": "[parameters('scriptUrl')]",
        "scriptUrlSasToken": "[parameters('scriptUrlSasToken')]",
        "continueOnErrors": "[parameters('continueOnErrors')]",
        "forceUpdateTag": "[parameters('forceUpdateTag')]"
      }
    }
  ],
  "outputs": {
  }
}

Utilisez les paramètres suivants :

Paramètre	Description
scriptUrl	URL de l’objet blob. Par exemple, « https://myaccount.blob.core.windows.net/mycontainer/myblob ».
scriptUrlSastoken	Chaîne avec les signatures d’accès partagé (SAS).
forceUpdateTag	Chaîne unique. En cas de modification, le script est appliqué à nouveau.
continueOnErrors	Indicateur signalant s’il faut continuer en cas d’échec de l’une des commandes. Valeur par défaut : false.
clusterName	Nom du cluster dans lequel le script s’exécute.
databaseName	Nom de la base de données sous laquelle le script s’exécute.
scriptName	Nom du script lors de l’utilisation d’un fichier externe pour fournir le script.

Limites

Les scripts sont pris en charge uniquement dans Azure Data Explorer ; Les scripts ne sont pas pris en charge dans les pools Data Explorer Synapse.
Deux scripts ne peuvent pas être ajoutés/modifiés/supprimés en parallèle sur le même cluster. Si cela se produit, l’erreur suivante : Code="ServiceIsInMaintenance" est générée. Vous pouvez contourner le problème en plaçant une dépendance entre les deux scripts afin qu’ils soient créés/mis à jour séquentiellement.
Pour créer des fonctions avec des requêtes inter-clusters à l’aide de scripts, vous devez définir la skipvalidation propriété true sur dans la commande .create function.

Dépannage

Les commandes exécutées par une ressource de script n’apparaissent pas dans les résultats de la commande .show commands-and-queries. Vous pouvez suivre l’exécution du script avec la commande .show journal.

Vue d'ensemble des commandes de gestion

Partager via

Configurer une base de données avec un script de langage de requête Kusto

Exemple de script avec des commandes de gestion

Prérequis

Sécurité

Script en ligne

Exécuter un script inline avec un modèle ARM

Omettre l’étiquette de mise à jour

Script Bicep

Script du compte de stockage

Créer la ressource de script

Exécuter le script avec un modèle ARM

Limites

Dépannage

Commentaires

Ressources supplémentaires

Partager via

Configurer une base de données avec un script de langage de requête Kusto

Exemple de script avec des commandes de gestion

Prérequis

Sécurité

Script en ligne

Exécuter un script inline avec un modèle ARM

Omettre l’étiquette de mise à jour

Script Bicep

Script du compte de stockage

Créer la ressource de script

Exécuter le script avec un modèle ARM

Limites

Dépannage

Contenu connexe

Commentaires

Ressources supplémentaires