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

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ées par un saut de ligne et créée en tant que ressource accessible avec le modèle ARM.

Le script ne peut exécuter que 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

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 :

1. Script inline : le script est fourni inline en tant que paramètre à un modèle ARM JSON.
2. Script Bicep : le script est fourni en tant que fichier distinct utilisé par un modèle ARM Bicep.
3. 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) fournies en tant que paramètres pour le modèle ARM.

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

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 a 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 :

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 les modifications de script soient exécutées la prochaine fois que le modèle est déployé. Utilisez uniquement la propriété forceUpdateTag si vous devez forcer l’exécution du script.

Script Bicep

Le passage d’un script en tant que paramètre à un modèle peut être fastidieux. 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 :

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.

Créer la ressource de script

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

1. Créez un script contenant les commandes de gestion que vous souhaitez utiliser pour créer la table dans votre base de données.

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

3. Permettez l’accès à ce fichier à l’aide de signatures d’accès partagé (SAS). Vous pouvez fournir un 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 Azure Resource Manager.

{
  "$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 :

Limites

• Les scripts sont uniquement pris en charge dans Azure Data Explorer ; Les scripts ne sont pas pris en charge dans les pools Synapse Data Explorer.
• 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 est Code="ServiceIsInMaintenance" 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 de fonction .create.

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.

Contenu connexe

• Vue d’ensemble des commandes de gestion