Freigeben über

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

  • Artikel

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 mindestens einem Verwaltungsbefehl, die jeweils durch einen Zeilenumbruch getrennt sind und als Ressource erstellt wird, 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

Hinweis

Die unterstützten Befehle müssen auf Datenbankebene ausgeführt werden. Beispielsweise können Sie eine Tabelle mit dem Befehl .create-or-alter tableändern. Befehle auf Clusterebene, z .alter cluster . B. Richtlinien, werden nicht unterstützt.

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, die ARM-Vorlagenbereitstellungen verwenden:

  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 seinen Details (URL und Shared Access Signatures (SaS) erstellt, die als Parameter für die ARM-Vorlage bereitgestellt werden.

Hinweis

Jeder Cluster kann über maximal 50 Skripts verfügen (weitere Skripts lösen einen Fehler aus Code:TooManyScripts .) Es wird empfohlen, mehrere kleine Skripts in weniger große zusammenzuführen, nachdem sie vorhandene Skripts gelöscht haben, um Speicherplatz für neue Skripts freizugeben. Durch das Löschen eines Skripts wird kein Rollback für die Befehle ausgeführt, die in diesem Skript ausgeführt wurden.

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

Sicherheit

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

Wichtig

Der Prinzipal, der den Cluster bereitstellt, erhält automatisch die All Databases Admin-Rolle im Cluster.

Inlineskript

Verwenden Sie diese Methode, um eine ARM-Vorlage zu erstellen, in der das Skript als Inlineparameter definiert ist. Wenn Ihr Skript über einen oder mehrere Verwaltungsbefehle 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:

Einstellung BESCHREIBUNG
kqlScript Das Inlineskript für die Kusto-Abfragesprache. Verwenden Sie \n, um Zeilenvorschubzeichen hinzuzufügen.
forceUpdateTag Eine eindeutige Zeichenfolge. Wenn das Skript geändert wird, wird es erneut angewendet.
continueOnErrors Ein Flag, das angibt, ob der Vorgang fortgesetzt werden soll, wenn bei einem der Befehle ein Fehler auftritt. Standardwert: False
clusterName Der Name des Clusters, in dem das Skript ausgeführt wird.
databaseName Der Name der Datenbank, unter der das Skript ausgeführt wird.
scriptName Der Name des Skripts, wenn eine externe Datei zum Bereitstellen des Skripts verwendet wird. Dies ist der Name der tatsächlichen ARM-Vorlagenressource des TypsSkript.

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 den gleichen 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 wegzulassen, damit alle Skriptänderungen bei der nächsten Bereitstellung 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 gleichen Ordner wie die Bicep-Datei befindet, erzeugt die folgende Vorlage das gleiche 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:

Einstellung BESCHREIBUNG
forceUpdateTag Eine eindeutige Zeichenfolge. Wenn das Skript geändert wird, wird es erneut angewendet.
continueOnErrors Ein Flag, das angibt, ob der Vorgang fortgesetzt werden soll, wenn bei einem der Befehle ein Fehler auftritt. Standardwert: False
clusterName Der Name des Clusters, in dem das Skript ausgeführt wird.
databaseName Der Name der Datenbank, unter der das Skript ausgeführt wird.
scriptName Der Name des Skripts, wenn eine externe Datei zum Bereitstellen des Skripts verwendet wird.

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

Hinweis

Skripts können nicht aus Speicherkonten geladen werden, die mit einer Azure Storage-Firewall oder mit Virtual Network-Regeln konfiguriert sind.

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 den Zugriff mithilfe von PowerShell, der 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:

Einstellung Beschreibung
scriptUrl Die URL des Blobs. Beispiel: „https://myaccount.blob.core.windows.net/mycontainer/myblob“.
scriptUrlSastoken Eine Zeichenfolge mit den Shared Access Signatures (SaS).
forceUpdateTag Eine eindeutige Zeichenfolge. Wenn das Skript geändert wird, wird es erneut angewendet.
continueOnErrors Ein Flag, das angibt, ob der Vorgang fortgesetzt werden soll, wenn bei einem der Befehle ein Fehler auftritt. Standardwert: False
clusterName Der Name des Clusters, in dem das Skript ausgeführt wird.
databaseName Der Name der Datenbank, unter der das Skript ausgeführt wird.
scriptName Der Name des Skripts, wenn eine externe Datei zum Bereitstellen des Skripts verwendet wird.

Einschränkungen

  • Skripts werden nur in Azure Data Explorer unterstützt. Skripts werden in Synapse Data Explorer-Pools nicht unterstützt.
  • Zwei Skripts können nicht parallel auf demselben Cluster hinzugefügt, geändert oder entfernt werden. In diesem Fall 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 im Funktionsbefehl ".create" auf true 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.

Verwandte Inhalte