Condividi tramite

Configurare un database usando uno script del Linguaggio di query Kusto

  • Articolo

È possibile eseguire uno script Linguaggio di query Kusto per configurare il database durante la distribuzione di modelli di Azure Resource Management (ARM). 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 idempotente sul comando .create-or-alter regolare .create .

Esistono vari metodi che è possibile usare per configurare un database con script. In questo articolo ci si concentra sui metodi seguenti usando le distribuzioni di modelli di Resource Manager:

  1. Script inline: lo script viene fornito inline come parametro a un modello JSON ARM.
  2. Script Bicep: lo script viene fornito come file separato usato da un modello bicep ARM.
  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 al 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 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 la prima esecuzione, 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 dell'entità 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 ha 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": {
    }
}

Usare le seguenti impostazioni:

Impostazione Descrizione
kqlScript Script di 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 specificare lo script. Si tratta del nome della risorsa di modello arm effettiva dello script di tipo.

Omettere il tag di aggiornamento

L'esecuzione di uno script KQL in ogni distribuzione del modello di Resource Manager non è consigliata perché usa le risorse del cluster. È possibile impedire l'esecuzione dello script nelle 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 solo la forceUpdateTag proprietà se è necessario forzare l'esecuzione dello script.

Script Bicep

Il passaggio di uno script come parametro a un modello può essere complesso. Bicep Azure Resource Manager modello 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 che si trova nella stessa cartella del file script.kql Bicep, il modello seguente genera 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
    }
}

Usare 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 specificare lo script.

Il modello Bicep può essere distribuito usando strumenti simili come modello JSON ARM. Ad esempio, è possibile usare i comandi dell'interfaccia della riga di comando di Azure seguenti 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 di Arm JSON prima della distribuzione. Nell'esempio, il file di script è incorporato inline nel modello di ARM 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 di 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 di archiviazione di Azure o Rete virtuale regole.

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 di archiviazione di Azure. È possibile creare l'account di archiviazione usando l'portale di Azure, PowerShell o l'interfaccia della riga di comando di Azure.

  3. Fornire l'accesso a questo file usando 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 Resource Manager di Azure.

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

Usare 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 specificare lo script.

Limitazioni

  • 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 della funzione .create.

Risoluzione dei problemi

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

Contenuti correlati