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

Můžete spustit skript v Kusto Query Language 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

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:

1. Vložený skript: Skript je vložený jako parametr šablony JSON ARM.
2. Skript Bicep: Skript je poskytován jako samostatný soubor používaný šablonou Bicep ARM.
3. Úč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)) jsou poskytnuty jako parametry do šablony ARM.

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, a při následných spuštěních 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í

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

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

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í:

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.
• Vynechte vlastnost forceUpdateTag nebo ji ponechte prázdnou a použijte stejný skript při nasazeních.

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í:

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

Vytvořte prostředek skriptu

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

1. Vytvořte skript obsahující příkazy pro správu, které chcete použít k vytvoření tabulky v databázi.

2. Nahrajte skript do účtu azure Storage. Účet úložiště můžete vytvořit pomocí webu Azure Portal, PowerShellu nebo Azure CLI.

3. 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í:

Omezení

• Skripty se podporují jenom v Azure Data Exploreru.
• 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 nastavit vlastnost skipvalidation na true v příkazu .create function.
• Dotazy napříč clusterem a volání, která využívají zosobnění, nejsou podporovány.

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

Související obsah

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