Adatbázis konfigurálása a Kusto lekérdezésnyelvi szkript használatával

Futtathat egy Kusto lekérdezésnyelv szkriptet az adatbázis konfigurálásához az Azure Resource Management-sablon üzembe helyezése során. A szkript 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 adatbázisszinten kell futtatni. Módosíthatja például a táblát a paranccsal .create-or-alter table. A fürtszintű parancsok, például .alter cluster a szabályzatok nem támogatottak.

Általában azt javasoljuk, hogy használja a parancsok idempotens verzióját, hogy ha többször hívják 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 parancs. Ha lehetséges, javasoljuk például az idempotens parancs .create-or-alter használatát a normál .create parancson keresztül.

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 van megadva.
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 fürt legfeljebb 50 szkripttel rendelkezhet (több szkript hibát vált ki Code:TooManyScripts .) Javasoljuk, hogy több kis szkriptet egyesítsen kevesebb nagy szkripttel, miután törölték a meglévő szkripteket , hogy helyet szabadítson fel az új szkriptek számára. A szkriptek törlése nem veti vissza a 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ásokra nincs hatásuk.

Előfeltételek

• 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 fürtöt és egy adatbázist.

Biztonság

A parancsfájl üzembe helyezéséhez használt egyszerű felhasználónak vagy szolgáltatásnévnek a következő biztonsági szerepköröknek kell rendelkeznie:

• Közreműködői szerepkör a fürtön
• Rendszergazda szerepkör az adatbázisban

Fontos

A fürtöt kiépítő egyszerű rendszer automatikusan lekéri a All Databases Admin szerepkört a fürtön.

Beágyazott szkript

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

Beágyazott szkript futtatása ARM-sablonnal

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

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

Beállítás	Leírás
kqlScript	A beágyazott Kusto lekérdezésnyelv szkript. Új vonalkarakterek hozzáadására használható \n .
forceUpdateTag	Egy egyedi sztring. Ha módosítja a parancsprogramot, a rendszer ismét alkalmazza a szkriptet.
continueOnErrors	Egy jelző, amely jelzi, hogy az egyik parancs meghiúsul-e. Alapértelmezett érték: hamis.
clusterName	Annak a fürtnek a neve, amelyen a szkript fut.
databaseName	Annak az adatbázisnak a neve, amely alatt a szkript fut.
scriptName	A szkript neve, amikor külső fájl használatával adja meg a szkriptet. Ez a szkript típusú ARM-sablon tényleges erőforrásának neve.

Frissítési címke kihagyás

KQL-szkript futtatása minden ARM-sablon üzembe helyezésekor nem ajánlott, 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 az, hogy kihagyja a forceUpdateTag tulajdonságot, hogy a szkript módosításai a sablon következő üzembe helyezésekor fussanak. Csak akkor használja a forceUpdateTag tulajdonságot, ha a szkript futtatására van szüksége.

Bicep-szkript

Nehézkes lehet paraméterként átadni egy szkriptet egy sablonnak. A Bicep Azure Resource Manager sablon lehetővé teszi, hogy a szkriptet egy külön fájlban tárolja és karbantartsa, majd betöltse a sablonba a loadTextContent Bicep függvénnyel.

Feltételezve, 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éldában:

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:

Beállítás	Leírás
forceUpdateTag	Egy egyedi sztring. Ha módosítja a parancsprogramot, a rendszer ismét alkalmazza a szkriptet.
continueOnErrors	A folytatást jelző jelző, ha az egyik parancs meghibásodik. Alapértelmezett érték: hamis.
clusterName	Annak a fürtnek a neve, amelyen a szkript fut.
databaseName	Annak az adatbázisnak a neve, amely alatt a szkript fut.
scriptName	A szkript neve, amikor külső fájl használatával adja meg a szkriptet.

A Bicep-sablon a JSON ARM-sablonhoz hasonló eszközökkel helyezhető üzembe. A sablon üzembe helyezéséhez például a következő 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 JSON ARM-sablonba vannak lefordítva az üzembe helyezés előtt. 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árfiókszkript

Ez a módszer feltételezi, hogy már van blobja egy Azure Storage-fiókban, és annak részleteit (URL-címet é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 Virtual Network szabályokkal konfigurált tárfiókokból.

A szkripterőforrás létrehozása

Első lépésként hozzon létre egy szkriptet, és töltse fel egy tárfiókba.

1. Hozzon létre egy szkriptet, amely tartalmazza azokat a felügyeleti parancsokat , amelyeket a tábla adatbázisában való létrehozásához szeretne használni.

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

3. Hozzáférés biztosítása 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:

Beállítás	Leírás
scriptUrl	A blob URL-címe. Például: ""https://myaccount.blob.core.windows.net/mycontainer/myblob.
scriptUrlSastoken	A közös hozzáférésű jogosultságkódokkal (SaS) rendelkező sztring.
forceUpdateTag	Egy egyedi sztring. Ha módosítja, a szkript újra alkalmazva lesz.
continueOnErrors	Jelölő, amely jelzi, hogy folytatódjon-e, ha az egyik parancs meghibásodik. Alapértelmezett érték: hamis.
clusterName	Annak a fürtnek a neve, ahol a szkript fut.
databaseName	Annak az adatbázisnak a neve, amely alatt a szkript fut.
scriptName	A szkript neve, amikor külső fájl használatával adja meg a szkriptet.

Korlátozások

• A szkriptek csak az Azure Data Explorer támogatottak; A Synapse-Data Explorer-készletek nem támogatják a szkripteket.
• Ugyanazon a fürtön párhuzamosan nem adható hozzá, nem módosítható vagy távolítható el két szkript. 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 hoz létre a két szkript között, hogy azok egymás után legyenek létrehozva vagy frissítve.
• Ha szkriptekkel szeretne függvényeket létrehozni fürtök közötti lekérdezésekkel, a tulajdonságot true a skipvalidation.create függvény parancsban kell beállítania.

Hibaelhárítás

A szkripterőforrás által futtatott parancsok nem jelennek meg a .show commands-and-queries parancs eredményei között. A szkript végrehajtását a .show journal paranccsal követheti nyomon.

Kapcsolódó tartalom

• Felügyeleti parancsok áttekintése