Configurar um banco de dados usando um script Kusto Query Language

Você pode executar um script Kusto Query Language para configurar seu banco de dados durante a implantação do modelo Azure Resource Management (ARM). 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 ARM.

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

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

Em geral, recomendamos o uso da versão idempotente dos 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, recomendamos o uso do 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 ARM:

1. Inline script: o script é fornecido inline como um parâmetro para um modelo JSON ARM.
2. Bicep script: O script é fornecido como um ficheiro separado utilizado por um modelo ARM Bicep.
3. Conta de armazenamento: o script é criado como um blob em uma conta de armazenamento do Azure e seus detalhes (URL e assinaturas de acesso compartilhado (SaS) fornecidas como parâmetros para o modelo ARM.

Exemplo de script com comandos de gerenciamento

O exemplo a seguir é 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)

Observe que os dois comandos são idempotentes. Quando executados pela primeira vez, o programa cria as tabelas; em execuções subsequentes, não tem efeito.

Pré-requisitos

• Uma assinatura do Azure. Crie uma conta do Azure gratuita.
• Um cluster e um banco de dados do Azure Data Explorer. Crie um cluster e um banco de dados.

Segurança

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

• Função de colaborador no cluster
• Função de administrador no banco de dados

Script em linha

Use esse método para criar um modelo 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 inline usando um modelo ARM

O modelo a seguir mostra como executar o script usando um modelo JSON 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:

Omitir tag de atualização

A execução de um script KQL em cada implantação de modelo 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 implantações.
• Omita a forceUpdateTag propriedade ou deixe-a vazia e use o mesmo script entre implantações.

A prática recomendada é omitir a forceUpdateTag propriedade para que quaisquer alterações de script sejam executadas na próxima vez que o modelo for implantado. Use a forceUpdateTag propriedade somente se precisar forçar a execução do script.

Script Bicep

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

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 do 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:

O modelo Bicep pode ser implantado usando ferramentas semelhantes ao modelo JSON ARM. 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 transpilados em modelo ARM em JSON antes da implantação. No exemplo, o ficheiro de script é incorporado no modelo JSON ARM. Para mais informações, consulte Visão geral sobre Bicep.

Script de conta de armazenamento

Esse método pressupõe que você já tenha um blob em uma conta de Armazenamento do Azure e forneça seus detalhes (URL e assinaturas de acesso compartilhado (SaS)) diretamente no modelo ARM.

Criar o recurso de script

O primeiro passo é criar um script e carregá-lo para 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 seu script em sua conta de 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 assinaturas de acesso compartilhado (SaS). Você pode fornecer acesso usando PowerShell, CLI do Azure ou .NET.

Executar o script usando um modelo 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": {
  }
}

Utilize as seguintes definições:

Limitações

• Os scripts só são suportados no Azure Data Explorer; Não há suporte para scripts nos pools do Synapse Data Explorer.
• Dois scripts não podem ser adicionados, modificados ou 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 trueno comando .create function.

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 rastrear a execução do script usando o comando .show journal .

Conteúdo relacionado

• Visão geral dos comandos de gerenciamento