Een database configureren met behulp van een Kusto-querytaal-script

U kunt een Kusto-querytaal-script uitvoeren om uw database te configureren tijdens de implementatie van Arm-sjablonen (Azure Resource Management). Een script is een lijst met een of meer beheeropdrachten, elk gescheiden door één regeleinde, en wordt gemaakt als een resource die wordt geopend met de ARM-sjabloon.

Het script kan alleen beheeropdrachten op databaseniveau uitvoeren die beginnen met de volgende werkwoorden:

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

Notitie

De ondersteunde opdrachten moeten worden uitgevoerd op databaseniveau. U kunt bijvoorbeeld een tabel wijzigen met behulp van de opdracht .create-or-alter table. Opdrachten op clusterniveau, zoals .alter cluster beleidsregels, worden niet ondersteund.

Over het algemeen raden we aan om de idempotente versie van opdrachten te gebruiken, zodat ze geen extra effect hebben als ze meer dan één keer worden aangeroepen met dezelfde invoerparameters. Met andere woorden, het meerdere keren uitvoeren van de opdracht heeft hetzelfde effect als één keer uitvoeren. We raden u bijvoorbeeld aan om waar mogelijk de opdracht .create-or-alter idempotent te gebruiken in plaats van de reguliere .create opdracht.

Er zijn verschillende methoden die u kunt gebruiken om een database met scripts te configureren. In dit artikel richten we ons op de volgende methoden met arm-sjabloonimplementaties:

1. Inlinescript: het script wordt inline geleverd als een parameter voor een JSON ARM-sjabloon.
2. Bicep-script: het script wordt geleverd als een afzonderlijk bestand dat wordt gebruikt door een Bicep ARM-sjabloon.
3. Opslagaccount: Het script wordt gemaakt als een blob in een Azure-opslagaccount en de details (URL en Shared Access Signatures (SaS) worden opgegeven als parameters voor de ARM-sjabloon.

Notitie

Elk cluster kan maximaal 50 scripts bevatten (meer scripts activeren een Code:TooManyScripts fout).) Het is raadzaam om meerdere kleine scripts samen te voegen in minder grote scripts, nadat u bestaande scripts hebt verwijderd om ruimte vrij te maken voor nieuwe scripts. Als u een script verwijdert, worden de opdrachten die vanuit dat script zijn uitgevoerd, niet teruggedraaid.

Voorbeeldscript met beheeropdrachten

Het volgende voorbeeld is een script met opdrachten waarmee twee tabellen worden gemaakt: MyTable en 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)

U ziet dat de twee opdrachten idempotent zijn. Wanneer ze voor het eerst worden uitgevoerd, maken ze de tabellen, bij volgende uitvoeringen hebben ze geen effect.

Vereisten

• Een Azure-abonnement. Maak een gratis Azure-account.
• Een Azure Data Explorer-cluster en -database. Maak een cluster en database.

Beveiliging

De principal, zoals een gebruiker of service-principal, die wordt gebruikt om een script te implementeren, moet de volgende beveiligingsrollen hebben:

• De rol Inzender in het cluster
• Beheer rol voor de database

Belangrijk

De principal die het cluster inricht, krijgt automatisch de All Databases Admin rol in het cluster.

Inlinescript

Gebruik deze methode om een ARM-sjabloon te maken met het script dat is gedefinieerd als een inlineparameter. Als uw script een of meer beheeropdrachten bevat, scheidt u de opdrachten met ten minste één regeleinde.

Inlinescript uitvoeren met behulp van een ARM-sjabloon

In de volgende sjabloon ziet u hoe u het script uitvoert met behulp van een JSON Azure Resource Manager-sjabloon.

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

Gebruik de volgende instellingen:

Instelling	Beschrijving
kqlScript	Het inline Kusto-querytaal script. Gebruik \n om nieuwe regeltekens toe te voegen.
forceUpdateTag	Een unieke tekenreeks. Als het script is gewijzigd, wordt het opnieuw toegepast.
continueOnErrors	Een vlag die aangeeft of moet worden voortgezet als een van de opdrachten mislukt. Standaardwaarde: false.
clusterName	De naam van het cluster waarin het script wordt uitgevoerd.
databaseName	De naam van de database waaronder het script wordt uitgevoerd.
scriptName	De naam van het script wanneer u een extern bestand gebruikt om het script op te geven. Dit is de naam van de werkelijke ARM-sjabloonresource van het type script.

Updatetag weglaten

Het uitvoeren van een KQL-script bij elke ARM-sjabloonimplementatie wordt niet aanbevolen, omdat dit clusterresources verbruikt. U kunt het uitvoeren van het script in opeenvolgende implementaties voorkomen met behulp van de volgende methoden:

• Geef de forceUpdateTag eigenschap op en behoud dezelfde waarde tussen implementaties.
• Laat de forceUpdateTag eigenschap weg of laat deze leeg en gebruik hetzelfde script tussen implementaties.

De beste procedure is om de forceUpdateTag eigenschap weg te laten, zodat eventuele scriptwijzigingen worden uitgevoerd wanneer de sjabloon de volgende keer wordt geïmplementeerd. Gebruik de forceUpdateTag eigenschap alleen als u wilt afdwingen dat het script wordt uitgevoerd.

Bicep-script

Het doorgeven van een script als parameter aan een sjabloon kan lastig zijn. Met Bicep Azure Resource Manager sjabloon kunt u het script in een afzonderlijk bestand bewaren en onderhouden en in de sjabloon laden met behulp van de functie loadTextContent Bicep.

Ervan uitgaande dat het script is opgeslagen in een bestand script.kql dat zich in dezelfde map bevindt als het Bicep-bestand, levert de volgende sjabloon hetzelfde resultaat op als in het vorige voorbeeld:

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

Gebruik de volgende instellingen:

Instelling	Beschrijving
forceUpdateTag	Een unieke tekenreeks. Als het script is gewijzigd, wordt het opnieuw toegepast.
continueOnErrors	Een vlag die aangeeft om door te gaan als een van de opdrachten mislukt. Standaardwaarde: false.
clusterName	De naam van het cluster waarin het script wordt uitgevoerd.
databaseName	De naam van de database waaronder het script wordt uitgevoerd.
scriptName	De naam van het script wanneer u een extern bestand gebruikt om het script op te geven.

De Bicep-sjabloon kan worden geïmplementeerd met vergelijkbare hulpprogramma's als de JSON ARM-sjabloon. U kunt bijvoorbeeld de volgende Azure CLI-opdrachten gebruiken om de sjabloon te implementeren:

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

Bicep-sjablonen worden vóór de implementatie omgezet in een JSON ARM-sjabloon. In het voorbeeld is het scriptbestand inline ingesloten in de JSON ARM-sjabloon. Zie Overzicht van Bicep voor meer informatie.

Script voor opslagaccount

Bij deze methode wordt ervan uitgegaan dat u al een blob in een Azure Storage-account hebt en dat u de details (URL en Shared Access Signatures (SaS)) rechtstreeks in de ARM-sjabloon opgeeft.

Notitie

Scripts kunnen niet worden geladen vanuit opslagaccounts die zijn geconfigureerd met een Azure Storage-firewall of Virtual Network-regels.

De scriptresource maken

De eerste stap is het maken van een script en het uploaden naar een opslagaccount.

1. Maak een script met de beheeropdrachten die u wilt gebruiken om de tabel in uw database te maken.

2. Upload uw script naar uw Azure Storage-account. U kunt uw opslagaccount maken met behulp van de Azure Portal, PowerShell of Azure CLI.

3. Geef toegang tot dit bestand met behulp van Shared Access Signatures (SaS). U kunt toegang bieden met behulp van PowerShell, Azure CLI of .NET.

Het script uitvoeren met behulp van een ARM-sjabloon

In deze sectie leert u hoe u een script uitvoert dat is opgeslagen in Azure Storage met een Azure Resource Manager-sjabloon.

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

Gebruik de volgende instellingen:

Instelling	Beschrijving
scriptUrl	De URL van de blob. Bijvoorbeeld: 'https://myaccount.blob.core.windows.net/mycontainer/myblob'.
scriptUrlSastoken	Een tekenreeks met de Shared Access Signatures (SaS).
forceUpdateTag	Een unieke tekenreeks. Als het script wordt gewijzigd, wordt het opnieuw toegepast.
continueOnErrors	Een vlag die aangeeft of u wilt doorgaan als een van de opdrachten mislukt. Standaardwaarde: false.
clusterName	De naam van het cluster waarin het script wordt uitgevoerd.
databaseName	De naam van de database waaronder het script wordt uitgevoerd.
scriptName	De naam van het script wanneer u een extern bestand gebruikt om het script op te geven.

Beperkingen

• Scripts worden alleen ondersteund in Azure Data Explorer; Scripts worden niet ondersteund in Synapse Data Explorer pools.
• Twee scripts kunnen niet parallel worden toegevoegd, gewijzigd of verwijderd in hetzelfde cluster. Als dit gebeurt, treedt de volgende fout Code="ServiceIsInMaintenance" op. U kunt het probleem omzeilen door een afhankelijkheid tussen de twee scripts te plaatsen, zodat ze opeenvolgend worden gemaakt of bijgewerkt.
• Als u functies wilt maken met clusteroverschrijdende query's met behulp van scripts, moet u de skipvalidation eigenschap true instellen op in de functieopdracht .create.

Problemen oplossen

Opdrachten die worden uitgevoerd door een scriptresource worden niet weergegeven in de resultaten van de opdracht .show commands-and-querys . U kunt de uitvoering van het script traceren met behulp van de opdracht .show journal .

Gerelateerde inhoud

• Overzicht van beheeropdrachten