Configurar uma base de dados com um script de Linguagem de Pesquisa Kusto

Pode executar um script Linguagem de Pesquisa Kusto para configurar a base de dados durante a implementação do modelo do Azure Resource Management (ARM). Um script é uma lista de um ou mais comandos de gestão, cada um separado por uma quebra de linha, e é criado como um recurso que é acedido com o modelo do ARM.

O script só pode executar comandos de gestão ao nível da base de dados que comecem com os seguintes verbos:

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

Nota

Os comandos suportados têm de ser executados ao nível da base de dados. Por exemplo, pode alterar uma tabela com o comando .create-or-alter table. Os comandos ao nível do cluster, como .alter cluster as políticas, não são suportados.

Em geral, recomendamos a utilização da versão idempotente dos comandos para que, se forem chamados mais do que uma vez com os mesmos parâmetros de entrada, não tenham qualquer efeito adicional. Por outras palavras, executar o comando várias vezes tem o mesmo efeito que executá-lo uma vez. Por exemplo, sempre que possível, recomendamos que utilize o comando .create-or-alter idempotent através do comando normal .create .

Existem vários métodos que pode utilizar para configurar uma base de dados com scripts. Neste artigo, focamo-nos nos seguintes métodos através de implementações de modelos do ARM:

1. Script inline: o script é fornecido inline como um parâmetro para um modelo arm JSON.
2. Script bicep: o script é fornecido como um ficheiro separado utilizado por um modelo bicep do ARM.
3. Conta de Armazenamento: o script é criado como um blob numa conta de armazenamento do Azure e os respetivos detalhes (URL e assinaturas de acesso partilhado (SaS) fornecidos como parâmetros para o modelo do ARM.

Nota

Cada cluster pode ter um máximo de 50 scripts (mais scripts irão acionar um Code:TooManyScripts erro.) É recomendado intercalar vários scripts pequenos em menos scripts grandes, depois de eliminar scripts existentes para libertar espaço para novos scripts. Eliminar um script não reverte os comandos que foram executados a partir desse script.

Script de exemplo com comandos de gestão

O exemplo seguinte é um script com comandos que criam duas tabelas: 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)

Repare que os dois comandos são idempotentes. Quando são executadas pela primeira vez, criam as tabelas, nas execuções subsequentes não têm qualquer efeito.

Pré-requisitos

• Uma subscrição do Azure. Crie uma conta gratuita do Azure.
• Um cluster e uma base de dados do Azure Data Explorer. Criar um cluster e uma base de dados.

Segurança

O principal, como um utilizador ou principal de serviço, utilizado para implementar um script tem de ter as seguintes funções de segurança:

• Função de contribuidor no cluster
• Administração função na base de dados

Importante

O principal que aprovisiona o cluster obtém automaticamente a All Databases Admin função no cluster.

Script inline

Utilize este método para criar um modelo do ARM com o script definido como um parâmetro inline. Se o script tiver um ou mais comandos de gestão, separe os comandos por , pelo menos , uma quebra de linha.

Executar script inline com um modelo do ARM

O modelo seguinte mostra como executar o script com um modelo JSON do Azure Resource Manager.

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

Utilize as seguintes definições:

Definições	Descrição
kqlScript	O script de Linguagem de Pesquisa Kusto inline. Utilize \n para adicionar novos carateres de linha.
forceUpdateTag	Uma cadeia exclusiva. Se for alterado, o script será aplicado novamente.
continueOnErrors	Um sinalizador que indica se deve continuar se um dos comandos falhar. Valor Predefinido: falso.
clusterName	O nome do cluster onde o script é executado.
databaseName	O nome da base de dados na qual o script é executado.
scriptName	O nome do script ao utilizar um ficheiro externo para fornecer o script. Este é o nome do recurso de modelo arm real do tipo script.

Omitir etiqueta de atualização

A execução de um script KQL em cada implementação de modelo do ARM não é recomendada, uma vez que consome recursos de cluster. Pode impedir a execução do script em implementações consecutivas com os seguintes métodos:

• Especifique a forceUpdateTag propriedade e mantenha o mesmo valor entre implementações.
• Omita a propriedade ou deixe-a forceUpdateTag vazia e utilize o mesmo script entre implementações.

A melhor prática é omitir a forceUpdateTag propriedade para que quaisquer alterações de script sejam executadas da próxima vez que o modelo for implementado. Utilize apenas a forceUpdateTag propriedade se precisar de forçar a execução do script.

Script bicep

Transmitir um script como um parâmetro para um modelo pode ser complicado. O modelo bicep do Azure Resource Manager permite-lhe manter e manter o script num ficheiro separado e carregá-lo para o modelo com a função loadTextContent Bicep.

Partindo do princípio de que o script está armazenado num ficheiro script.kql localizado na mesma pasta que o ficheiro Bicep, o modelo seguinte produz o mesmo resultado que o exemplo anterior:

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

Utilize as seguintes definições:

Definições	Descrição
forceUpdateTag	Uma cadeia exclusiva. Se for alterado, o script será aplicado novamente.
continueOnErrors	Um sinalizador que indica para continuar se um dos comandos falhar. Valor Predefinido: falso.
clusterName	O nome do cluster onde o script é executado.
databaseName	O nome da base de dados na qual o script é executado.
scriptName	O nome do script ao utilizar um ficheiro externo para fornecer o script.

O modelo Bicep pode ser implementado com ferramentas semelhantes ao modelo arm JSON. Por exemplo, pode utilizar os seguintes comandos da CLI do Azure para implementar o modelo:

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

Os modelos bicep são transpostos para o modelo arm JSON antes da implementação. No exemplo, o ficheiro de script é incorporado inline no modelo arm JSON. Para obter mais informações, veja Descrição geral do Bicep.

Script da conta de armazenamento

Este método pressupõe que já tem um blob numa conta de Armazenamento do Azure e fornece os respetivos detalhes (URL e assinaturas de acesso partilhado (SaS)) diretamente no modelo do ARM.

Nota

Os scripts não podem ser carregados a partir de contas de armazenamento configuradas com uma firewall do Armazenamento do Azure ou regras de Rede Virtual.

Criar o recurso de script

O primeiro passo é criar um script e carregá-lo para uma conta de armazenamento.

1. Crie um script que contenha os comandos de gestão que pretende utilizar para criar a tabela na sua base de dados.

2. Carregue o script para a sua conta de Armazenamento do Azure. Pode criar a sua conta de armazenamento com o portal do Azure, o PowerShell ou a CLI do Azure.

3. Forneça acesso a este ficheiro através de assinaturas de acesso partilhado (SaS). Pode fornecer acesso com o PowerShell, a CLI do Azure ou o .NET.

Executar o script com um modelo do ARM

Nesta secção, vai aprender a executar um script armazenado no Armazenamento do Azure com um modelo de Resource Manager do 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": {
  }
}

Utilize as seguintes definições:

Definição	Descrição
scriptUrl	O URL do blob. Por exemplo, "https://myaccount.blob.core.windows.net/mycontainer/myblob".
scriptUrlSastoken	Uma cadeia com as assinaturas de acesso partilhado (SaS).
forceUpdateTag	Uma cadeia exclusiva. Se for alterado, o script será aplicado novamente.
continueOnErrors	Um sinalizador que indica se deve continuar se um dos comandos falhar. Valor Predefinido: falso.
clusterName	O nome do cluster onde o script é executado.
databaseName	O nome da base de dados na qual o script é executado.
scriptName	O nome do script ao utilizar um ficheiro externo para fornecer o script.

Limitações

• Os scripts só são suportados no Azure Data Explorer; Os scripts não são suportados nos conjuntos de Data Explorer do Synapse.
• Não é possível adicionar, modificar ou remover dois scripts em paralelo no mesmo cluster. Se isto ocorrer, é gerado o seguinte erro: Code="ServiceIsInMaintenance" Pode contornar o problema ao colocar uma dependência entre os dois scripts para que sejam criados ou atualizados sequencialmente.
• Para criar funções com consultas entre clusters através de scripts, tem de definir a skipvalidation propriedade como true no comando de função .create.

Resolução de problemas

Os comandos executados por um recurso de script não aparecem nos resultados do comando .show commands-and-queries . Pode rastrear a execução do script com o comando .show journal .

Conteúdo relacionado

• Descrição geral dos comandos de gestão