Configurare un database mediante uno script del linguaggio di query Kusto

È possibile eseguire uno script di linguaggio di query Kusto per configurare il tuo 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, come i criteri .alter cluster, 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 ci concentriamo sui seguenti metodi usando le distribuzioni di modelli ARM:

Script inline: lo script viene fornito inline come parametro per un modello di Resource Manager JSON.
Script Bicep: lo script viene fornito come file separato usato da un modello Bicep di Azure Resource Manager (ARM).
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 (SaS)) sono 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 annulla i 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 vengono eseguiti per la prima volta, creano le tabelle, nelle esecuzioni successive non hanno alcun effetto.

Prerequisiti

Una sottoscrizione di Azure. Creare un account Azure gratuito.
Un cluster e un database di Azure Data Explorer. Creare un cluster e un database.

Sicurezza

Il principale, ad esempio un utente o un principale di servizio, usato per distribuire uno script deve avere i seguenti ruoli di sicurezza:

Ruolo collaboratore nel cluster
Ruolo di amministratore nel database

Importante

L'entità principale che si occupa del provisioning del cluster riceve automaticamente il ruolo All Databases Admin sul cluster.

script in linea

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

Eseguire script inline usando un modello ARM

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 inline del linguaggio di query Kusto. Usare `\n` per aggiungere nuovi caratteri di riga.
forceUpdateTag	Stringa univoca. Se viene 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 del modello effettivo di ARM di tipo script.

Omettere il tag di aggiornamento

L'esecuzione di uno script KQL in ogni distribuzione dei modelli di Azure Resource Manager (ARM) non è consigliata, poiché consuma 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 viene 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 a quelli del 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 in linea nel modello di Resource Manager JSON. Per ulteriori 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 che si forniscano i relativi dettagli (URL e firme di accesso condiviso (SaS)) direttamente nel modello di Resource Manager.

Nota

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

Creare la risorsa script

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

Creare uno script contenente i comandi di gestione da usare per creare la tabella nel database.
Carica il tuo script nel tuo account di Azure Storage. È possibile creare l'account di archiviazione usando il portale di Azure, PowerShell o l'interfaccia della riga di comando di Azure.
Fornire l'accesso a questo file usando le firme di accesso condiviso (SaS). È possibile fornire l'accesso usando PowerShell, l'interfaccia CLI 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	L'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 viene 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 Esplora dati di Azure.
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 cross-cluster usando script, è necessario impostare la proprietà skipvalidation su true nel comando .create function.
Le interrogazioni e i callout tra cluster che usano l'impersonificazione non sono supportati.

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 .

Panoramica dei comandi di gestione

Commenti e suggerimenti

Questa pagina è stata utile?

Last updated on 2026-03-12

Condividi tramite

Configurare un database mediante uno script del linguaggio di query Kusto

Script di esempio con comandi di gestione

Prerequisiti

Sicurezza

script in linea

Eseguire script inline usando un modello ARM

Omettere il tag di aggiornamento

Script Bicep

Script dell'account di archiviazione

Creare la risorsa script

Eseguire lo script usando un modello di Resource Manager

Limiti

Risoluzione dei problemi

Contenuto correlato

Commenti e suggerimenti

Risorse aggiuntive