Konfigurieren einer Datenbank mithilfe eines Skripts für die Kusto-Abfragesprache

Sie können ein Skript für die Kusto-Abfragesprache ausführen, um Ihre Datenbank im Rahmen der ARM-Vorlagenbereitstellung (Azure Resource Management) zu konfigurieren. Ein Skript ist eine Liste mit einem oder mehreren Verwaltungsbefehlen, die jeweils durch einen Zeilenumbruch getrennt sind, und wird als Ressource erstellt, auf die mit der ARM-Vorlage zugegriffen wird.

Das Skript kann nur Verwaltungsbefehle auf Datenbankebene ausführen, die mit den folgenden Verben beginnen:

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

Im Allgemeinen wird empfohlen, die idempotente Version von Befehlen zu verwenden, damit beim mehrfachen Aufrufen mit den gleichen Eingabeparametern keine zusätzlichen Auswirkungen auftreten. Anders ausgedrückt: Das mehrmalige Ausführen des Befehls hat die gleiche Auswirkung wie die einmalige Ausführung. Es wird beispielsweise empfohlen, nach Möglichkeit den idempotenten Befehl .create-or-alter gegenüber dem regulären Befehl .create vorzuziehen.

Eine Datenbank kann auf verschiedene Arten mit Skripts konfiguriert werden. In diesem Artikel konzentrieren wir uns auf die folgenden Methoden mit ARM-Vorlagenbereitstellungen:

1. Inlineskript: Das Skript wird inline als Parameter für eine JSON-ARM-Vorlage bereitgestellt.
2. Bicep-Skript: Das Skript wird als separate Datei bereitgestellt, die von einer Bicep-ARM-Vorlage verwendet wird.
3. Speicherkonto: Das Skript wird als BLOB in einem Azure-Speicherkonto und seine Details (URL und freigegebene Zugriffssignaturen, SaS) erstellt, die als Parameter für die ARM-Vorlage bereitgestellt werden.

Beispielskript mit Verwaltungsbefehlen

Das folgende Beispiel ist ein Skript mit Befehlen, die zwei Tabellen erstellen: MyTable und 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)

Beachten Sie, dass die beiden Befehle idempotent sind. Bei der ersten Ausführung erstellen sie die Tabellen, bei nachfolgenden Ausführungen haben sie keine Auswirkungen.

Voraussetzungen

• Ein Azure-Abonnement. Erstellen Sie ein kostenloses Azure-Konto.
• Schnellstart: Erstellen eines Azure Data Explorer-Clusters und einer Datenbank. Erstellen eines Clusters und einer Datenbank

Sicherheit

Der Prinzipal, z. B. ein Benutzer oder Dienstprinzipal, der zum Bereitstellen eines Skripts verwendet wird, muss über die folgenden Sicherheitsrollen verfügen:

• Rolle „Mitwirkender“ im Cluster
• Administratorrolle für die Datenbank

Inlineskript

Verwenden Sie diese Methode, um eine ARM-Vorlage zu erstellen, in der das Skript als Inlineparameter definiert ist. Wenn Ihr Skript über mindestens einen Verwaltungsbefehl verfügt, trennen Sie die Befehle durch mindestens einen Zeilenumbruch.

Ausführen eines Inlineskripts mithilfe einer ARM-Vorlage

Die folgende Vorlage zeigt, wie das Skript mithilfe einer JSON-Azure Resource Manager-Vorlage ausgeführt wird.

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

Verwenden Sie folgende Einstellungen:

Updatetag auslassen

Vom Ausführen eines KQL-Skripts bei jeder Bereitstellung einer ARM-Vorlage wird abgeraten, da dies Clusterressourcen verbraucht. Sie können die Ausführung des Skripts in aufeinanderfolgenden Bereitstellungen mithilfe der folgenden Methoden verhindern:

• Geben Sie die forceUpdateTag Eigenschaft an, und behalten Sie denselben Wert zwischen Bereitstellungen bei.
• Lassen Sie die forceUpdateTag-Eigenschaft aus, oder lassen Sie sie leer, und verwenden Sie zwischen den Bereitstellungen das gleiche Skript.

Die bewährte Methode besteht darin, die forceUpdateTag Eigenschaft auszulassen, sodass skriptänderungen beim nächsten Bereitstellen der Vorlage ausgeführt werden. Verwenden Sie die forceUpdateTag-Eigenschaft nur, wenn Sie die Ausführung des Skripts erzwingen müssen.

Bicep-Skript

Das Übergeben eines Skripts als Parameter an eine Vorlage kann umständlich sein. Die Bicep Azure Resource Manager-Vorlage ermöglicht es Ihnen, das Skript in einer separaten Datei zu speichern und zu verwalten und es mithilfe der Bicep-Funktion loadTextContent in die Vorlage zu laden.

Wenn das Skript in einer Datei script.kql gespeichert ist, die sich im selben Ordner wie die Bicep-Datei befindet, erzeugt die folgende Vorlage dasselbe Ergebnis wie im vorherigen Beispiel:

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
    }
}

Verwenden Sie folgende Einstellungen:

Die Bicep-Vorlage kann mit ähnlichen Tools wie die JSON-ARM-Vorlage bereitgestellt werden. Sie können zum Bereitstellen der Vorlage z. B. die folgenden Azure CLI-Befehle verwenden:

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

Bicep-Vorlagen werden vor der Bereitstellung in eine JSON-ARM-Vorlage transpiliert. Im Beispiel ist die Skriptdatei inline in die JSON ARM-Vorlage eingebettet. Weitere Informationen finden Sie unter Was ist Bicep (Vorschau)?.

Speicherkontoskript

Bei dieser Methode wird davon ausgegangen, dass Sie bereits über ein Blob in einem Azure-Speicherkonto verfügen und die zugehörigen Details (URL und Shared Access Signatures (SAS)) direkt in der ARM-Vorlage angeben.

Erstellen der Skriptressource

Der erste Schritt besteht darin, ein Skript zu erstellen und es in ein Speicherkonto hochzuladen.

1. Erstellen Sie ein Skript mit den Verwaltungsbefehlen , die Sie zum Erstellen der Tabelle in Ihrer Datenbank verwenden möchten.

2. Laden Sie Ihr Skript in Ihr Azure-Speicherkonto hoch. Sie können Ihr Speicherkonto mithilfe des Azure-Portals, PowerShell oder der Azure CLI erstellen.

3. Gewähren Sie Zugriff auf diese Datei mithilfe von Shared Access Signatures (SAS). Sie können Zugriff über PowerShell, Azure CLI oder .NET bereitstellen.

Ausführen des Skripts mithilfe einer ARM-Vorlage

In diesem Abschnitt erfahren Sie, wie Sie ein in Azure Storage gespeichertes Skript mit einer Azure Resource Manager-Vorlage ausführen.

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

Verwenden Sie folgende Einstellungen:

Begrenzungen

• Skripts werden nur im Azure-Daten-Explorer unterstützt. Skripts werden in Synapse-Daten-Explorer-Pools nicht unterstützt.
• Zwei Skripts können nicht parallel auf demselben Cluster hinzugefügt, geändert oder entfernt werden. Wenn dies der Fall ist, wird der folgende Fehler ausgelöst: Code="ServiceIsInMaintenance" Sie können das Problem umgehen, indem Sie eine Abhängigkeit zwischen den beiden Skripts platzieren, sodass sie nacheinander erstellt oder aktualisiert werden.
• Um Funktionen mit clusterübergreifenden Abfragen mithilfe von Skripts zu erstellen, müssen Sie die skipvalidation Eigenschaft true im Befehl ".create-Funktion" festlegen.

Problembehandlung

Befehle, die von einer Skriptressource ausgeführt werden, werden nicht in den Ergebnissen des Befehls .show commands-and-queries angezeigt. Sie können die Skriptausführung mit dem Befehl .show journal verfolgen.

Zugehöriger Inhalt

• Übersicht über Verwaltungsbefehle