Konfigurace databáze s využitím skriptu KQL (dotazovací jazyk Kusto)

Článek
11/23/2024

Můžete spustit dotazovací jazyk Kusto skript pro konfiguraci databáze během nasazení šablony Azure Resource Management (ARM). Skript je seznam jednoho nebo více příkazů pro správu oddělených jedním koncem řádku a je vytvořen jako prostředek, ke kterému se přistupuje pomocí šablony ARM.

Skript může spouštět pouze příkazy pro správu na úrovni databáze, které začínají následujícími příkazy:

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

Poznámka:

Podporované příkazy se musí spouštět na úrovni databáze. Tabulku můžete například změnit pomocí příkazu .create-or-alter table. Příkazy na úrovni clusteru, jako .alter cluster jsou zásady, se nepodporují.

Obecně doporučujeme použít idempotentní verzi příkazů, takže pokud se volají více než jednou se stejnými vstupními parametry, nemají žádný další účinek. Jinými slovy, spuštění příkazu několikrát má stejný účinek jako jeho spuštění jednou. Pokud je to možné, doporučujeme například použít příkaz idempotentní .create-or-alter pro běžný .create příkaz.

Existují různé metody, které můžete použít ke konfiguraci databáze se skripty. V tomto článku se zaměříme na následující metody použití nasazení šablon ARM:

Vložený skript: Skript je vložený jako parametr šablony JSON ARM.
Skript Bicep: Skript se poskytuje jako samostatný soubor používaný šablonou ARM Bicep.
Účet úložiště: Skript se vytvoří jako objekt blob v účtu úložiště Azure a jeho podrobnosti (adresa URL a sdílené přístupové podpisy (SaS) poskytnuté jako parametry šablony ARM.

Poznámka:

Každý cluster může mít maximálně 50 skriptů (více skriptů aktivuje Code:TooManyScripts chybu.) Po odstranění existujících skriptů doporučujeme sloučit několik malých skriptů do méně velkých skriptů, aby se uvolnilo místo pro nové skripty . Odstraněním skriptu se nevrácejí příkazy, které byly z daného skriptu spuštěny.

Ukázkový skript s příkazy pro správu

Následující příklad je skript s příkazy, které vytvářejí dvě tabulky: MyTable a 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)

Všimněte si, že dva příkazy jsou idempotentní. Při prvním spuštění vytvoří tabulky při následných spuštěních, které nemají žádný vliv.

Požadavky

Předplatné Azure. Vytvořte bezplatný účet Azure.
Cluster a databáze Azure Data Exploreru. Vytvořte cluster a databázi.

Zabezpečení

Objekt zabezpečení, například uživatel nebo instanční objekt použitý k nasazení skriptu, musí mít následující role zabezpečení:

Role přispěvatele v clusteru
Role správce v databázi

Důležité

Objekt zabezpečení, který cluster zřídí, automaticky získá All Databases Admin roli v clusteru.

Vložený skript

Tuto metodu použijte k vytvoření šablony ARM se skriptem definovaným jako vložený parametr. Pokud má váš skript jeden nebo více příkazů pro správu, oddělte je alespoň jedním koncem řádku.

Spuštění vloženého skriptu pomocí šablony ARM

Následující šablona ukazuje, jak spustit skript pomocí šablony Azure Resource Manageru 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": {
    }
}

Použijte následující nastavení:

Nastavení	Popis
kqlScript	Vložený dotazovací jazyk Kusto skript. Slouží `\n` k přidání nových znaků řádku.
forceUpdateTag	Jedinečný řetězec. Pokud se změní, skript se znovu použije.
continueOnErrors	Příznak označující, jestli se má pokračovat, pokud některý z příkazů selže. Výchozí hodnota: false.
clusterName	Název clusteru, ve kterém se skript spouští.
databaseName	Název databáze, pod kterou se skript spouští.
scriptName	Název skriptu při použití externího souboru k zadání skriptu. Toto je název skutečného prostředku šablony ARM typu skriptu.

Vynechat značku aktualizace

Spuštění skriptu KQL při každém nasazení šablony ARM se nedoporučuje, protože využívá prostředky clusteru. Spuštění skriptu v po sobě jdoucích nasazeních můžete zabránit následujícími metodami:

forceUpdateTag Zadejte vlastnost a ponechte stejnou hodnotu mezi nasazeními.
Tuto vlastnost vynecháte nebo ponechte prázdnou forceUpdateTag a použijte stejný skript mezi nasazeními.

Osvědčeným postupem je vynechat forceUpdateTag vlastnost, aby se při příštím nasazení šablony spustily všechny změny skriptu. Vlastnost použijte forceUpdateTag pouze v případě, že potřebujete vynutit spuštění skriptu.

Skript Bicep

Předání skriptu jako parametru šabloně může být těžkopádné. Šablona Bicep Azure Resource Manageru umožňuje zachovat a udržovat skript v samostatném souboru a načíst ho do šablony pomocí funkce loadTextContent Bicep.

Za předpokladu, že je skript uložený v souboru script.kql umístěném ve stejné složce jako soubor Bicep, vytvoří následující šablona stejný výsledek jako v předchozím příkladu:

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

Použijte následující nastavení:

Nastavení	Popis
forceUpdateTag	Jedinečný řetězec. Pokud se změní, skript se znovu použije.
continueOnErrors	Příznak označující pokračování v případě, že některý z příkazů selže. Výchozí hodnota: false.
clusterName	Název clusteru, ve kterém se skript spouští.
databaseName	Název databáze, pod kterou se skript spouští.
scriptName	Název skriptu při použití externího souboru k zadání skriptu.

Šablonu Bicep je možné nasadit pomocí podobných nástrojů jako šablona JSON ARM. K nasazení šablony můžete použít například následující příkazy Azure CLI:

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

Šablony Bicep se před nasazením překládají do šablony JSON ARM. V příkladu je soubor skriptu vložený do šablony JSON ARM. Další informace najdete v tématu Přehled bicep.

Skript účtu úložiště

Tato metoda předpokládá, že už máte objekt blob v účtu služby Azure Storage a zadáte jeho podrobnosti (URL a sdílené přístupové podpisy (SaS) přímo v šabloně ARM.

Poznámka:

Skripty nelze načíst z účtů úložiště nakonfigurovaných pomocí brány firewall služby Azure Storage nebo pravidel virtuální sítě.

Vytvoření prostředku skriptu

Prvním krokem je vytvoření skriptu a jeho nahrání do účtu úložiště.

Vytvořte skript obsahující příkazy pro správu, které chcete použít k vytvoření tabulky v databázi.
Nahrajte skript do účtu azure Storage. Účet úložiště můžete vytvořit pomocí webu Azure Portal, PowerShellu nebo Azure CLI.
Poskytnutí přístupu k tomuto souboru pomocí sdílených přístupových podpisů (SaS) Přístup můžete poskytnout pomocí PowerShellu, Azure CLI nebo .NET.

Spuštění skriptu pomocí šablony ARM

V této části se dozvíte, jak spustit skript uložený ve službě Azure Storage pomocí šablony Azure Resource Manageru.

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

Použijte následující nastavení:

Nastavení	Popis
scriptUrl	Adresa URL objektu blob. Například 'https://myaccount.blob.core.windows.net/mycontainer/myblob'.
scriptUrlSastoken	Řetězec se sdílenými přístupovými podpisy (SaS)
forceUpdateTag	Jedinečný řetězec. Pokud se změní, skript se znovu použije.
continueOnErrors	Příznak označující, jestli se má pokračovat, pokud některý z příkazů selže. Výchozí hodnota: false.
clusterName	Název clusteru, ve kterém se skript spouští.
databaseName	Název databáze, pod kterou se skript spouští.
scriptName	Název skriptu při použití externího souboru k zadání skriptu.

Omezení

Skripty jsou podporovány pouze v Azure Data Exploreru; Ve fondech Průzkumníka dat Synapse nejsou podporované skripty.
Ve stejném clusteru není možné paralelně přidat, upravit nebo odebrat dva skripty. V takovém případě se vyvolá následující chyba: Code="ServiceIsInMaintenance" Tento problém můžete obejít tak, že pro tyto dva skripty vytvoříte závislost, aby se vytvořily nebo aktualizovaly po sobě.
Pokud chcete vytvářet funkce s dotazy mezi clustery pomocí skriptů , musíte vlastnost nastavit skipvalidation na true příkaz .create function.

Řešení problému

Příkazy spouštěné prostředkem skriptu se nezobrazují ve výsledcích příkazu .show commands-and-queries . Spuštění skriptu můžete sledovat pomocí příkazu .show journal .

Přehled příkazů pro správu

Sdílet prostřednictvím

Konfigurace databáze s využitím skriptu KQL (dotazovací jazyk Kusto)

Ukázkový skript s příkazy pro správu

Požadavky

Zabezpečení

Vložený skript

Spuštění vloženého skriptu pomocí šablony ARM

Vynechat značku aktualizace

Skript Bicep

Skript účtu úložiště

Vytvoření prostředku skriptu

Spuštění skriptu pomocí šablony ARM

Omezení

Řešení problému

Váš názor

Další materiály

Sdílet prostřednictvím

Konfigurace databáze s využitím skriptu KQL (dotazovací jazyk Kusto)

Ukázkový skript s příkazy pro správu

Požadavky

Zabezpečení

Vložený skript

Spuštění vloženého skriptu pomocí šablony ARM

Vynechat značku aktualizace

Skript Bicep

Skript účtu úložiště

Vytvoření prostředku skriptu

Spuštění skriptu pomocí šablony ARM

Omezení

Řešení problému

Související obsah

Váš názor

Další materiály