Sdílet prostřednictvím

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

  • Článek

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:

  1. Vložený skript: Skript se poskytuje jako vložený parametr šablony JSON ARM.
  2. Skript Bicep: Skript je k dispozici 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) 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

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

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

  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í Azure Portal, PowerShellu nebo Azure CLI.

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

Související obsah