Adatbázis konfigurálása Kusto Query Language-szkripttel

Kusto Query Language-szkript futtatásával konfigurálhatja az adatbázist az Azure Resource Management (ARM) sablon üzembe helyezése során. A szkriptek egy vagy több felügyeleti parancs listája, amelyek mindegyike egy sortöréssel van elválasztva, és az ARM-sablonnal elérhető erőforrásként jön létre.

A szkript csak olyan adatbázisszintű felügyeleti parancsokat futtathat, amelyek a következő parancsokkal kezdődnek:

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

Megjegyzés:

A támogatott parancsokat az adatbázis szintjén kell futtatni. Módosíthatja például a táblázatot a parancs használatával .create-or-alter table. A cluster szintű parancsok, például .alter cluster az irányelvek, nem támogatottak.

Általában azt javasoljuk, hogy a parancsok idempotens verzióját használjuk, hogy ha többször hívjuk meg őket ugyanazokkal a bemeneti paraméterekkel, akkor nincs további hatásuk. Más szóval a parancs többszöri futtatása ugyanolyan hatással van, mint az egyszer futtatott parancsra. Ha lehetséges, javasoljuk például az idempotens parancs .create-or-alter használatát a normál .create parancs felett.

Az adatbázisok parancsfájlokkal való konfigurálásához többféle módszer is használható. Ebben a cikkben a következő módszerekre összpontosítunk ARM-sablontelepítések használatával:

1. Beágyazott szkript: A szkript egy JSON ARM-sablon paramétereként beágyazottan érhető el.
2. Bicep-szkript: A szkript egy Bicep ARM-sablon által használt különálló fájlként van megadva.
3. Tárfiók: A szkript blobként jön létre egy Azure Storage-fiókban, és annak részletei (URL-cím és közös hozzáférésű jogosultságkódok (SaS) az ARM-sablon paramétereiként.

Megjegyzés:

Minden klaszter legfeljebb 50 szkripttel rendelkezhet (több szkript hibát vált ki Code:TooManyScripts.) Javasoljuk, hogy több kisebb szkriptet úgy egyesítsen kevesebb nagyobb szkripttel, hogy törli a meglévő szkripteket, így felszabadul a hely az új szkriptek számára. A szkriptek törlése nem veti vissza az adott szkriptből végrehajtott parancsokat.

Példaszkript felügyeleti parancsokkal

Az alábbi példa egy parancsokat tartalmazó szkript, amely két táblát hoz létre: MyTable és 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)

Figyelje meg, hogy a két parancs idempotens. Az első futtatáskor létrehozzák a táblákat, a későbbi futtatásokon nincs hatásuk.

Előfeltételek

• Egy Azure-előfizetés. Hozzon létre egy ingyenes Azure-fiókot.
• Egy Azure Data Explorer-fürt és adatbázis. Hozzon létre egy klasztert és egy adatbázist.

Biztonság

A parancsfájl üzembe helyezésére használt felhasználói azonosítónak vagy szolgáltatásfelelőnek a következő biztonsági szerepkörökkel kell rendelkeznie:

• Közreműködői szerepkör a klaszteren
• Rendszergazdai szerepkör az adatbázisban

Fontos

A fürtöt kiépítő hierarchikus entitás automatikusan megkapja a All Databases Admin szerepkört a fürtön.

Beágyazott szkript

Ezzel a módszerrel létrehozhat egy ARM-sablont beágyazott paraméterként definiált szkripttel. Ha a szkript egy vagy több felügyeleti parancsot használ, a parancsokat legalább egy sortöréssel válassza el egymástól.

Beágyazott szkript futtatása ARM-sablonnal

Az alábbi sablon bemutatja, hogyan futtathatja a szkriptet egy JSON Azure Resource Manager-sablonnal.

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

Használja a következő beállításokat:

Setting	Description
kqlScript	A beágyazott Kusto Query Language szkript. Új sorkarakterek hozzáadására használható \n .
forceUpdateTag	Egyedi karakterlánc. Ha módosult, a szkript ismét alkalmazva lesz.
hibák_ellenére_folytatás	Egy jelző, amely megmutatja, hogy folytassuk-e, ha az egyik parancs meghiúsul. Alapértelmezett érték: hamis.
clusterName	Annak a fürtnek a neve, ahol a program fut.
databaseName	Annak az adatbázisnak a neve, amely alatt a szkript fut.
scriptName	A szkript neve, ha egy külső fájllal látja el a szkriptet. Ez a script típusú tényleges ARM-sablon erőforrás neve.

Frissítési címke kihagyása

Nem ajánlott KQL-szkriptet futtatni minden ARM-sablon üzembe helyezésekor, mivel fürterőforrásokat használ. Az alábbi módszerekkel megakadályozhatja a szkript futtatását egymást követő üzemelő példányokban:

• Adja meg a forceUpdateTag tulajdonságot, és tartsa meg ugyanazt az értéket az üzemelő példányok között.
• Hagyja ki a forceUpdateTag tulajdonságot, vagy hagyja üresen, és használja ugyanazt a szkriptet az üzemelő példányok között.

Az ajánlott eljárás a forceUpdateTag tulajdonság kihagyása: így a szkript változásai a sablon következő üzembe helyezésekor futnak. Csak akkor használja a forceUpdateTag tulajdonságot, ha a szkript futtatására van szüksége.

Bicep-szkript

A szkript paraméterként való átadása nehézkes lehet egy sablonnak. A Bicep Azure Resource Manager-sablon lehetővé teszi a szkript külön fájlban való megőrzését és karbantartását, valamint a sablonba való betöltését a loadTextContent Bicep függvény használatával.

Feltéve, hogy a szkript a Bicep-fájllal azonos mappában található fájlban script.kql van tárolva, a következő sablon ugyanazt az eredményt hozza létre, mint az előző példa:

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

Használja a következő beállításokat:

Setting	Description
forceUpdateTag	Egyedi karakterlánc. Ha módosult, a szkript ismét alkalmazva lesz.
hibák_ellenére_folytatás	A folytatást jelző jelző, ha az egyik parancs meghiúsul. Alapértelmezett érték: hamis.
clusterName	Annak a fürtnek a neve, ahol a program fut.
databaseName	Annak az adatbázisnak a neve, amely alatt a szkript fut.
scriptName	A szkript neve, ha egy külső fájllal látja el a szkriptet.

A Bicep-sablon a JSON ARM-sablonhoz hasonló eszközökkel telepíthető. A sablon üzembe helyezéséhez például az alábbi Azure CLI-parancsokat használhatja:

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

A Bicep-sablonok az üzembe helyezés előtt JSON ARM-sablonná alakulnak át. A példában a szkriptfájl beágyazottan van beágyazva a JSON ARM-sablonba. További információt a Bicep áttekintésében talál.

Tárolófiók szkript

Ez a módszer feltételezi, hogy már rendelkezik egy blobnal egy Azure Storage-fiókban, és annak részleteit (URL- és közös hozzáférésű jogosultságkódokat (SaS)) közvetlenül az ARM-sablonban adja meg.

Megjegyzés:

A szkriptek nem tölthetők be Azure Storage-tűzfallal vagy virtuális hálózati szabályokkal konfigurált tárfiókokból.

A szkripterőforrás létrehozása

Az első lépés egy szkript létrehozása és egy tárfiókba való feltöltése.

1. Hozzon létre egy szkriptet, amely tartalmazza az adatbázis táblájának létrehozásához használni kívánt felügyeleti parancsokat.

2. Töltse fel a szkriptet az Azure Storage-fiókjába. A tárfiókot az Azure Portal, a PowerShell vagy az Azure CLI használatával hozhatja létre.

3. Adjon hozzáférést ehhez a fájlhoz közös hozzáférésű jogosultságkódok (SaS) használatával. Hozzáférést a PowerShell, az Azure CLI vagy a .NET használatával biztosíthat.

A szkript futtatása ARM-sablonnal

Ebben a szakaszban megtudhatja, hogyan futtathat egy Azure Storage-ban tárolt szkriptet egy Azure Resource Manager-sablonnal.

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

Használja a következő beállításokat:

Setting	Leírás
scriptUrl	A blob URL-címe. Például: ""https://myaccount.blob.core.windows.net/mycontainer/myblob.
scriptUrlSastoken	A megosztott hozzáférési aláírásokkal (SaS) rendelkező sztring.
forceUpdateTag	Egyedi karaktersor. Ha módosult, a szkript ismét alkalmazva lesz.
hibák_ellenére_folytatás	Egy jelző, amely megmutatja, hogy folytassuk-e, ha az egyik parancs meghiúsul. Alapértelmezett érték: hamis.
clusterName	Annak a fürtnek a neve, ahol a program fut.
databaseName	Annak az adatbázisnak a neve, amely alatt a szkript fut.
scriptName	A szkript neve, ha egy külső fájllal látja el a szkriptet.

Korlátozások

• A szkriptek csak az Azure Data Explorerben támogatottak.
• Két szkript nem adható hozzá, nem módosítható vagy távolítható el párhuzamosan ugyanazon a fürtön. Ha ez történik, a következő hiba lép fel: Code="ServiceIsInMaintenance" Megkerülheti a problémát, ha függőséget helyez el a két szkript között, így azok egymás után jönnek létre vagy frissülnek.
• Ha szkriptek használatával szeretne kereszt-fürt lekérdezésekkel függvényeket létrehozni, a skipvalidation tulajdonságot true be kell állítania a .create függvény parancsban.
• A cluster-közi lekérdezések és a megszemélyesítést használó meghívások nem támogatottak.

Hibaelhárítás

A szkripterőforrás által futtatott parancsok nem jelennek meg a .show parancsok és lekérdezések parancs eredményei között. A szkript végrehajtásának nyomon követéséhez használja a .show journal parancsot.

Kapcsolódó tartalom

• Felügyeleti parancsok áttekintése