Dela via

Konfigurera en databas med hjälp av ett skript med Kusto-frågespråk

  • Artikel

Du kan köra ett Kusto-frågespråk skript för att konfigurera databasen under distributionen av ARM-mallen (Azure Resource Management). Ett skript är en lista över ett eller flera hanteringskommandon, var och en avgränsad med en radbrytning, och skapas som en resurs som nås med ARM-mallen.

Skriptet kan bara köra hanteringskommandon på databasnivå som börjar med följande verb:

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

Anteckning

Kommandon som stöds måste köras på databasnivå. Du kan till exempel ändra en tabell med kommandot .create-or-alter table. Kommandon på klusternivå, till exempel .alter cluster principer, stöds inte.

I allmänhet rekommenderar vi att du använder idempotent-versionen av kommandon så att om de anropas mer än en gång med samma indataparametrar har de ingen ytterligare effekt. Med andra ord har körning av kommandot flera gånger samma effekt som att köra det en gång. Där det är möjligt rekommenderar vi till exempel att du använder kommandot .create-or-alter idempotent över det vanliga .create kommandot.

Det finns olika metoder som du kan använda för att konfigurera en databas med skript. I den här artikeln fokuserar vi på följande metoder med arm-malldistributioner:

  1. Infogat skript: Skriptet tillhandahålls infogat som en parameter till en JSON ARM-mall.
  2. Bicep-skript: Skriptet tillhandahålls som en separat fil som används av en Bicep ARM-mall.
  3. Lagringskonto: Skriptet skapas som en blob i ett Azure Storage-konto och dess information (URL och signaturer för delad åtkomst (SaS) tillhandahålls som parametrar till ARM-mallen.

Anteckning

Varje kluster kan ha högst 50 skript (fler skript utlöser ett Code:TooManyScripts fel.) Vi rekommenderar att du sammanfogar flera små skript till färre stora skript när du har raderat befintliga skript för att frigöra utrymme för nya skript. Om du tar bort ett skript återställs inte de kommandon som kördes från skriptet.

Exempelskript med hanteringskommandon

Följande exempel är ett skript med kommandon som skapar två tabeller: MyTable och 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)

Observera att de två kommandona är idempotent. När de först körs skapar de tabellerna. På efterföljande körningar har de ingen effekt.

Förutsättningar

Säkerhet

Huvudnamnet, till exempel en användare eller tjänstens huvudnamn, som används för att distribuera ett skript måste ha följande säkerhetsroller:

Viktigt

Huvudkontot som etablerar klustret hämtar All Databases Admin automatiskt rollen i klustret.

Infogat skript

Använd den här metoden för att skapa en ARM-mall med skriptet definierat som en infogad parameter. Om skriptet har ett eller flera hanteringskommandon separerar du kommandona med minst en radbrytning.

Köra infogat skript med hjälp av en ARM-mall

Följande mall visar hur du kör skriptet med hjälp av en JSON Azure Resource Manager-mall.

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

Använd följande inställningar:

Inställningen Beskrivning
kqlScript Det infogade Kusto-frågespråk skriptet. Använd \n för att lägga till nya radtecken.
forceUpdateTag En unik sträng. Om det ändras tillämpas skriptet igen.
continueOnErrors En flagga som anger om du vill fortsätta om något av kommandona misslyckas. Standardvärde: false.
clusterName Namnet på klustret där skriptet körs.
databaseName Namnet på databasen som skriptet körs under.
scriptName Namnet på skriptet när du använder en extern fil för att ange skriptet. Det här är namnet på den faktiska ARM-mallresursen av typen script.

Utelämna uppdateringstagg

Att köra ett KQL-skript vid varje ARM-malldistribution rekommenderas inte eftersom det förbrukar klusterresurser. Du kan förhindra körning av skriptet i efterföljande distributioner med hjälp av följande metoder:

  • forceUpdateTag Ange egenskapen och behåll samma värde mellan distributioner.
  • Utelämna egenskapen forceUpdateTag eller lämna den tom och använd samma skript mellan distributionerna.

Det bästa sättet är att utelämna forceUpdateTag egenskapen så att eventuella skriptändringar körs nästa gång mallen distribueras. Använd forceUpdateTag endast egenskapen om du behöver tvinga skriptet att köras.

Bicep-skript

Det kan vara besvärligt att skicka ett skript som en parameter till en mall. Med mallen Bicep Azure Resource Manager kan du behålla och underhålla skriptet i en separat fil och läsa in det i mallen med hjälp av Bicep-funktionen loadTextContent.

Förutsatt att skriptet lagras i en fil script.kql som finns i samma mapp som Bicep-filen, ger följande mall samma resultat som i föregående exempel:

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

Använd följande inställningar:

Inställningen Beskrivning
forceUpdateTag En unik sträng. Om det ändras tillämpas skriptet igen.
continueOnErrors En flagga som anger att du vill fortsätta om något av kommandona misslyckas. Standardvärde: false.
clusterName Namnet på klustret där skriptet körs.
databaseName Namnet på databasen som skriptet körs under.
scriptName Namnet på skriptet när du använder en extern fil för att ange skriptet.

Bicep-mallen kan distribueras med liknande verktyg som JSON ARM-mallen. Du kan till exempel använda följande Azure CLI-kommandon för att distribuera mallen:

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

Bicep-mallar överförs till JSON ARM-mallen före distributionen. I exemplet är skriptfilen inbäddad i JSON ARM-mallen. Mer information finns i översikten över Bicep.

Skript för lagringskonto

Den här metoden förutsätter att du redan har en blob i ett Azure Storage-konto och att du anger dess information (URL och signaturer för delad åtkomst (SaS)) direkt i ARM-mallen.

Anteckning

Skript kan inte läsas in från lagringskonton som konfigurerats med en Azure Storage-brandvägg eller Virtual Network regler.

Skapa skriptresursen

Det första steget är att skapa ett skript och ladda upp det till ett lagringskonto.

  1. Skapa ett skript som innehåller de hanteringskommandon som du vill använda för att skapa tabellen i databasen.

  2. Ladda upp skriptet till ditt Azure Storage-konto. Du kan skapa ditt lagringskonto med hjälp av Azure Portal, PowerShell eller Azure CLI.

  3. Ge åtkomst till den här filen med signaturer för delad åtkomst (SaS). Du kan ge åtkomst med Hjälp av PowerShell, Azure CLI eller .NET.

Kör skriptet med hjälp av en ARM-mall

I det här avsnittet får du lära dig hur du kör ett skript som lagras i Azure Storage med en Azure Resource Manager-mall.

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

Använd följande inställningar:

Inställning Beskrivning
scriptUrl URL:en för bloben. Till exempel "https://myaccount.blob.core.windows.net/mycontainer/myblob".
scriptUrlSastoken En sträng med signaturer för delad åtkomst (SaS).
forceUpdateTag En unik sträng. Om skriptet ändras tillämpas det igen.
continueOnErrors En flagga som anger om du vill fortsätta om något av kommandona misslyckas. Standardvärde: false.
clusterName Namnet på klustret där skriptet körs.
databaseName Namnet på databasen som skriptet körs under.
scriptName Namnet på skriptet när du använder en extern fil för att ange skriptet.

Begränsningar

  • Skript stöds bara i Azure Data Explorer; Skript stöds inte i Synapse Data Explorer-pooler.
  • Du kan inte lägga till, ändra eller ta bort två skript parallellt i samma kluster. Om detta inträffar utlöses följande fel: Code="ServiceIsInMaintenance" Du kan kringgå problemet genom att ange ett beroende mellan de två skripten så att de skapas eller uppdateras i sekvens.
  • Om du vill skapa funktioner med frågor mellan kluster med hjälp av skript måste du ange skipvalidation egenskapen till true i funktionskommandot .create.

Felsökning

Kommandon som körs av en skriptresurs visas inte i resultatet av kommandot .show commands-and-queries . Du kan spåra skriptkörningen med hjälp av kommandot .show journal .

Relaterat innehåll