Configurar um banco de dados usando um script na Linguagem de Consulta Kusto
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:
- Script embutido: o script é fornecido embutido como um parâmetro para um modelo do ARM do JSON.
- Script Bicep: o script é fornecido como um arquivo separado usado por um modelo do ARM do Bicep.
- 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.
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.
- Uma assinatura do Azure. Criar uma conta gratuita do Azure.
- Um cluster e um banco de dados do Azure Data Explorer. Criar um cluster e um banco de dados.
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:
- Função Colaborador no cluster
- Função Administrador no banco de dados
Importante
A entidade de segurança que provisiona o cluster recebe automaticamente a função All Databases Admin
no cluster.
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.
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. |
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.
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.
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.
A primeira etapa é criar um script e carregá-lo em uma conta de armazenamento.
Crie um script contendo os comandos de gerenciamento que você deseja usar para criar a tabela em seu banco de dados.
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.
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.
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. |
- 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 comotrue
no comando de função .create.
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.