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

Článek
03/21/2024

Během nasazení šablony Azure Resource Management (ARM) můžete spustit dotazovací jazyk Kusto skript pro konfiguraci databáze. 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 musí být spuštěny 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ů, aby pokud jsou volána více než jednou se stejnými vstupními parametry, neměly žá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 .create-or-alter idempotentní před běžným .create příkazem.

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 využívající nasazení šablon ARM:

Vložený skript: Skript se poskytuje jako vložený parametr šablony JSON ARM.
Skript Bicep: Skript je k dispozici jako samostatný soubor používaný šablonou BIcep ARM.
Úč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) se zadají 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ů se doporučuje sloučit několik malých skriptů do méně velkých, aby se uvolnilo místo pro nové skripty. Odstraněním skriptu se nevrátí zpět 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é vytvoří 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 tyto dva příkazy jsou idempotentní. Při prvním spuštění vytvoří tabulky, na další spuštění nemají žádný vliv.

Požadavky

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

Zabezpečení

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

Role přispěvatele v clusteru
Správa role v databázi

Důležité

Objekt zabezpečení zřizování clusteru automaticky získá All Databases Admin roli v clusteru.

Vložený skript

Tato metoda slouží k vytvoření šablony ARM se skriptem definovaným jako vložený parametr. Pokud váš skript obsahuje 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 skript spustit pomocí šablony JSON Azure Resource Manager.

{
    "$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.
název_clusteru	Název clusteru, ve kterém se skript spouští.
databaseName	Název databáze, ve které 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.

Vynechání značky 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 pomocí následujících metod:

forceUpdateTag Zadejte vlastnost a zachovejte stejnou hodnotu mezi nasazeními.
Vynechte forceUpdateTag vlastnost nebo ji ponechte prázdnou a mezi nasazeními použijte stejný skript.

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 pouze v forceUpdateTag případě, že potřebujete vynutit spuštění skriptu.

Bicepový skript

Předání skriptu jako parametru do šablony může být náročné. Šablona Bicep Azure Resource Manager umožňuje uchovávat 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, následující šablona vytvoří 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.
název_clusteru	Název clusteru, ve kterém se skript spouští.
databaseName	Název databáze, ve které 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 například použít 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 transpilují do šablony JSON ARM. V tomto příkladu je soubor skriptu vložený do šablony JSON ARM. Další informace najdete v tématu Přehled bicepu.

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 (adresu URL a sdílené přístupové podpisy (SaS)) přímo v šabloně ARM.

Poznámka

Skripty není možné načíst z účtů úložiště nakonfigurovaných pomocí brány firewall služby Azure Storage nebo pravidel Virtual Network.

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í Azure Portal, PowerShellu nebo Azure CLI.
Poskytnout přístup 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 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": {
  }
}

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

Nastavení	Popis
adresa URL skriptu	Adresa URL objektu blob. Příklad: .https://myaccount.blob.core.windows.net/mycontainer/myblob
skriptUrlSastoken	Ř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.
název_clusteru	Název clusteru, ve kterém se skript spouští.
databaseName	Název databáze, pod kterou se skript spouští.
název skriptu	Název skriptu při použití externího souboru k poskytnutí skriptu.

Omezení

Skripty se podporují jenom v Azure Data Explorer. Skripty nejsou podporovány ve fondech synapse Data Explorer.
Ve stejném clusteru není možné paralelně přidat, upravit nebo odebrat dva skripty. Pokud k tomu dojde, vyvolá se 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 napříč clustery pomocí skriptů, musíte v příkazu .create function nastavit skipvalidation vlastnost na true .

Poradce při potížích

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

Vynechání značky aktualizace

Bicepový skript

Skript účtu úložiště

Vytvoření prostředku skriptu

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

Omezení

Poradce při potížích

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

Vynechání značky aktualizace

Bicepový skript

Skript účtu úložiště

Vytvoření prostředku skriptu

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

Omezení

Poradce při potížích

Související obsah

Váš názor

Další materiály