Compartilhar via

Configurar um banco de dados usando um script na Linguagem de Consulta Kusto

  • Artigo

Você pode executar um script da Linguagem de Consulta Kusto a fim de configurar seu banco de dados durante a implantação do modelo do ARM (Azure Resource Manager). Um script é uma lista de um ou mais comandos de gerenciamento, cada um separado por uma quebra de linha, e é criado como um recurso que é acessado com o modelo do ARM.

O script só pode executar comandos de gerenciamento no nível do banco de dados que começam com os seguintes verbos:

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

Observação

Os comandos suportados devem ser executados no nível do banco de dados. Por exemplo, você pode alterar uma tabela usando o comando .create-or-alter table. Comandos de nível de cluster, como .alter cluster políticas, não são suportados.

Em geral, recomendamos usar a versão idempotente de comandos para que, se eles forem chamados mais de uma vez com os mesmos parâmetros de entrada, eles não tenham efeito adicional. Em outras palavras, executar o comando várias vezes tem o mesmo efeito que executá-lo uma vez. Por exemplo, sempre que possível, é recomendável usar o comando idempotente .create-or-alter sobre o comando regular .create.

Há vários métodos que você pode usar para configurar um banco de dados com scripts. Neste artigo, nos concentramos nos seguintes métodos usando implantações de modelo do ARM:

  1. Script embutido: o script é fornecido embutido como um parâmetro para um modelo do ARM do JSON.
  2. Script Bicep: o script é fornecido como um arquivo separado usado por um modelo do ARM do Bicep.
  3. Conta de armazenamento: o script é criado como um blob em uma conta de armazenamento do Azure e seus detalhes (URL e SaS (assinaturas de acesso compartilhado) fornecidos como parâmetros para o modelo do ARM.

Observação

Cada cluster pode ter no máximo 50 scripts (mais scripts acionarão um Code:TooManyScripts erro). É recomendável mesclar vários scripts pequenos em menos scripts grandes, depois de excluir os scripts existentes para liberar espaço para novos scripts. A exclusão de um script não reverte os comandos que foram executados a partir desse script.

Script de exemplo com comandos de gerenciamento

O exemplo a seguir é um script com comandos que criam duas tabelas: MinhaTabela e MinhaTabela2.

.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)

Observe que os dois comandos são idempotentes. Quando executado pela primeira vez, eles criam as tabelas. Nas execuções subsequentes, eles não têm nenhum efeito.

Pré-requisitos

Segurança

A entidade, como um usuário ou uma entidade de serviço, usada para implantar um script precisa ter as seguintes funções de segurança:

Importante

A entidade de segurança que provisiona o cluster recebe automaticamente a função All Databases Admin no cluster.

Script embutido

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

Executar script embutido usando um modelo do ARM

O modelo a seguir mostra como executar o script usando um modelo do Azure Resource Manager do 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": {
    }
}

Use as configurações a seguir:

Configuração Descrição
kqlScript Script da Linguagem de Consulta Kusto embutido. Use \n para adicionar caracteres de nova linha.
forceUpdateTag Uma cadeia de caracteres exclusiva. Se alterado, o script é aplicado novamente.
continueOnErrors Um sinalizador que indica se o processo deve continuar caso um dos comandos falhe. Valor padrão: falso.
clusterName O nome do cluster em que o script é executado.
databaseName O nome do banco de dados no qual o script é executado.
scriptName O nome do script quando você estiver usando um arquivo externo para fornecer o script. Este é o nome do recurso do modelo do ARM real do tipo script.

Omitir marca de atualização

A execução de um script KQL em cada implantação de modelo do ARM não é recomendada, pois consome recursos de cluster. Você pode impedir a execução do script em implantações consecutivas usando os seguintes métodos:

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

A prática recomendada é omitir a forceUpdateTag propriedade para que todas as alterações de script sejam executadas na próxima vez que o modelo for implantado. Apenas use a propriedade forceUpdateTag somente se você precisar forçar o script a ser executado.

Script Bicep

Passar um script como um parâmetro para um modelo pode ser complicado. Modelo do Azure Resource Manager do Bicep permite manter o script em um arquivo separado e carregá-lo no modelo usando a função Bicep loadTextContent.

Supondo que o script esteja armazenado em um arquivo script.kql localizado na mesma pasta que o arquivo Bicep, o modelo a seguir 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
    }
}

Use as configurações a seguir:

Configuração Descrição
forceUpdateTag Uma cadeia de caracteres exclusiva. Se alterado, o script é aplicado novamente.
continueOnErrors Um sinalizador que indica se o processo deve continuar caso um dos comandos falhe. Valor padrão: falso.
clusterName O nome do cluster em que o script é executado.
databaseName O nome do banco de dados no qual o script é executado.
scriptName O nome do script quando você estiver usando um arquivo externo para fornecer o script.

O modelo Bicep pode ser implantado usando ferramentas semelhantes ao modelo do ARM do JSON. Por exemplo, você pode usar os seguintes comandos da CLI do Azure para implantar 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 transcompilados no modelo do ARM do JSON antes da implantação. No exemplo, o arquivo de script é incorporado embutido no modelo JSON ARM. Para saber mais, confira Visão geral do Bicep.

Script da conta de armazenamento

Esse método pressupõe que você já tem um blob na conta de Armazenamento do Azure e fornece os detalhes dele (URL e SaS [assinaturas de acesso compartilhado]) diretamente no modelo do ARM.

Observação

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

Criar o recurso de script

A primeira etapa é criar um script e carregá-lo em uma conta de armazenamento.

  1. Crie um script contendo os comandos de gerenciamento que você deseja usar para criar a tabela em seu banco de dados.

  2. Carregue o seu script na sua conta do Armazenamento do Azure. Você pode criar sua conta de armazenamento usando o portal do Azure, o PowerShell ou a CLI do Azure.

  3. Forneça acesso a esse arquivo usando SAS (assinaturas de acesso compartilhado). Você pode fornecer acesso usando o PowerShell, a CLI do Azure ou o .NET.

Executar o script usando um modelo do ARM

Nesta seção, você aprenderá a executar um script armazenado no Armazenamento do Azure com um modelo do 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": {
  }
}

Use as configurações a seguir:

Configuração Descrição
scriptUrl A URL do blob. Por exemplo: "https://myaccount.blob.core.windows.net/mycontainer/myblob".
scriptUrlSastoken Uma cadeia de caracteres com SaS (assinaturas de acesso compartilhado).
forceUpdateTag Uma cadeia de caracteres exclusiva. Se alterado, o script é aplicado novamente.
continueOnErrors Um sinalizador que indica se o processo deve continuar caso um dos comandos falhe. Valor padrão: falso.
clusterName O nome do cluster em que o script é executado.
databaseName O nome do banco de dados no qual o script é executado.
scriptName O nome do script quando você estiver usando um arquivo externo para fornecer o script.

Limitações

  • Os scripts só têm suporte no Azure Data Explorer; Não há suporte para scripts em pools do Synapse Data Explorer.
  • Dois scripts não podem ser adicionados, modificados nem removidos em paralelo no mesmo cluster. Se isso ocorrer, o seguinte erro: Code="ServiceIsInMaintenance" é gerado. Você pode contornar o problema colocando uma dependência entre os dois scripts para que eles sejam criados ou atualizados sequencialmente.
  • Para criar funções com consultas entre clusters usando scripts, você deve definir a skipvalidation propriedade como true no comando de função .create.

Solução de problemas

Os comandos executados por um recurso de script não aparecem nos resultados do comando .show commands-and-queries. Você pode acompanhar a execução do script usando o comando .show journal.

Conteúdo relacionado