Condividi tramite

Configurare un database usando uno script del Linguaggio di query Kusto

  • Articolo

È possibile eseguire uno script di Linguaggio di query Kusto per configurare il database durante la distribuzione del modello di Gestione risorse di Azure. Uno script è un elenco di uno o più comandi di gestione, ognuno separato da un'interruzione di riga e viene creato come risorsa a cui si accede con il modello di Resource Manager.

Lo script può eseguire solo comandi di gestione a livello di database che iniziano con i verbi seguenti:

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

Nota

I comandi supportati devono essere eseguiti a livello di database. Ad esempio, è possibile modificare una tabella usando il comando .create-or-alter table. I comandi a livello di cluster, ad esempio .alter cluster i criteri, non sono supportati.

In generale, è consigliabile usare la versione idempotente dei comandi in modo che, se vengono chiamati più volte con gli stessi parametri di input, non hanno alcun effetto aggiuntivo. In altre parole, l'esecuzione del comando più volte ha lo stesso effetto dell'esecuzione una sola volta. Se possibile, ad esempio, è consigliabile usare il comando .create-or-alter idempotente sul comando normale .create .

Esistono diversi metodi che è possibile usare per configurare un database con script. In questo articolo vengono illustrati i metodi seguenti usando le distribuzioni di modelli di Resource Manager:

  1. Script inline: lo script viene fornito inline come parametro per un modello di Resource Manager JSON.
  2. Script Bicep: lo script viene fornito come file separato usato da un modello di Resource Manager Bicep.
  3. Account di archiviazione: lo script viene creato come BLOB in un account di archiviazione di Azure e i relativi dettagli (URL e firme di accesso condiviso) forniti come parametri per il modello di Resource Manager.

Nota

Ogni cluster può avere un massimo di 50 script (più script attiveranno un Code:TooManyScripts errore). È consigliabile unire più script di piccole dimensioni in meno grandi, dopo aver eliminato gli script esistenti per liberare spazio per i nuovi script. L'eliminazione di uno script non esegue il rollback dei comandi eseguiti da tale script.

Script di esempio con comandi di gestione

L'esempio seguente è uno script con comandi che creano due tabelle: MyTable e 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)

Si noti che i due comandi sono idempotenti. Quando viene eseguita per la prima volta, creano le tabelle, nelle esecuzioni successive non hanno alcun effetto.

Prerequisiti

Sicurezza

L'entità, ad esempio un utente o un'entità servizio, usata per distribuire uno script deve avere i ruoli di sicurezza seguenti:

Importante

Il provisioning principale del cluster ottiene automaticamente il All Databases Admin ruolo nel cluster.

Script inline

Usare questo metodo per creare un modello di Resource Manager con lo script definito come parametro inline. Se lo script dispone di uno o più comandi di gestione, separare i comandi per almeno un'interruzione di riga.

Eseguire script inline usando un modello di Resource Manager

Il modello seguente illustra come eseguire lo script usando un modello di Azure Resource Manager 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": {
    }
}

Utilizzare le seguenti impostazioni:

Impostazione Descrizione
kqlScript Script Linguaggio di query Kusto inline. Usare \n per aggiungere nuovi caratteri di riga.
forceUpdateTag Stringa univoca. Se modificato, lo script viene nuovamente applicato.
continueOnErrors Flag che indica se continuare se uno dei comandi ha esito negativo. Valore predefinito: false.
clusterName Nome del cluster in cui viene eseguito lo script.
databaseName Nome del database in cui viene eseguito lo script.
scriptName Nome dello script quando si usa un file esterno per fornire lo script. Si tratta del nome della risorsa modello di Resource Manager effettiva di tipo script.

Omettere il tag di aggiornamento

L'esecuzione di uno script KQL in ogni distribuzione di modelli di Resource Manager non è consigliata perché usa le risorse del cluster. È possibile impedire l'esecuzione dello script in distribuzioni consecutive usando i metodi seguenti:

  • Specificare la forceUpdateTag proprietà e mantenere lo stesso valore tra le distribuzioni.
  • Omettere la forceUpdateTag proprietà o lasciarla vuota e usare lo stesso script tra le distribuzioni.

La procedura consigliata consiste nell'omettere la forceUpdateTag proprietà in modo che tutte le modifiche dello script vengano eseguite alla successiva distribuzione del modello. Usare la forceUpdateTag proprietà solo se è necessario forzare l'esecuzione dello script.

Script Bicep

Il passaggio di uno script come parametro a un modello può essere complesso. Il modello bicep di Azure Resource Manager consente di mantenere e gestire lo script in un file separato e caricarlo nel modello usando la funzione loadTextContent Bicep.

Supponendo che lo script sia archiviato in un file script.kql che si trova nella stessa cartella del file Bicep, il modello seguente produce lo stesso risultato dell'esempio precedente:

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

Utilizzare le seguenti impostazioni:

Impostazione Descrizione
forceUpdateTag Stringa univoca. Se modificato, lo script viene nuovamente applicato.
continueOnErrors Flag che indica di continuare se uno dei comandi ha esito negativo. Valore predefinito: false.
clusterName Nome del cluster in cui viene eseguito lo script.
databaseName Nome del database in cui viene eseguito lo script.
scriptName Nome dello script quando si usa un file esterno per fornire lo script.

Il modello Bicep può essere distribuito usando strumenti simili come il modello di Resource Manager JSON. Ad esempio, è possibile usare i comandi seguenti dell'interfaccia della riga di comando di Azure per distribuire il modello:

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

I modelli Bicep vengono traspilati nel modello ARM JSON prima della distribuzione. Nell'esempio il file di script è incorporato inline nel modello DI Resource Manager JSON. Per altre informazioni, vedere Panoramica di Bicep.

Script dell'account di archiviazione

Questo metodo presuppone che sia già presente un BLOB in un account Archiviazione di Azure e si forniscano i relativi dettagli (URL e firme di accesso condiviso) direttamente nel modello di Resource Manager.

Nota

Gli script non possono essere caricati dagli account di archiviazione configurati con un firewall Archiviazione di Azure o regole di Rete virtuale.

Creare la risorsa script

Il primo passaggio consiste nel creare uno script e caricarlo in un account di archiviazione.

  1. Creare uno script contenente i comandi di gestione da usare per creare la tabella nel database.

  2. Caricare lo script nell'account Archiviazione di Azure. È possibile creare l'account di archiviazione usando il portale di Azure, PowerShell o l'interfaccia della riga di comando di Azure.

  3. Fornire l'accesso a questo file usando le firme di accesso condiviso (SaS). È possibile fornire l'accesso usando PowerShell, l'interfaccia della riga di comando di Azure o .NET.

Eseguire lo script usando un modello di Resource Manager

In questa sezione viene illustrato come eseguire uno script archiviato in Archiviazione di Azure con un modello di 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": {
  }
}

Utilizzare le seguenti impostazioni:

Impostazione Descrizione
scriptUrl URL del BLOB. Ad esempio, 'https://myaccount.blob.core.windows.net/mycontainer/myblob'.
scriptUrlSastoken Stringa con le firme di accesso condiviso (SaS).
forceUpdateTag Stringa univoca. Se modificato, lo script viene nuovamente applicato.
continueOnErrors Flag che indica se continuare se uno dei comandi ha esito negativo. Valore predefinito: false.
clusterName Nome del cluster in cui viene eseguito lo script.
databaseName Nome del database in cui viene eseguito lo script.
scriptName Nome dello script quando si usa un file esterno per fornire lo script.

Limiti

  • Gli script sono supportati solo in Azure Esplora dati; Gli script non sono supportati nei pool di Esplora dati Synapse.
  • Non è possibile aggiungere, modificare o rimuovere due script in parallelo nello stesso cluster. In questo caso, viene generato l'errore seguente: Code="ServiceIsInMaintenance" È possibile risolvere il problema inserendo una dipendenza tra i due script in modo che vengano creati o aggiornati in sequenza.
  • Per creare funzioni con query tra cluster usando script, è necessario impostare la skipvalidation proprietà su true nel comando .create function.

Risoluzione dei problemi

I comandi eseguiti da una risorsa script non vengono visualizzati nei risultati del comando .show commands-and-queries . È possibile tracciare l'esecuzione dello script usando il comando .show journal .

Contenuto correlato