Настройка базы данных с помощью скрипта языка запросов Kusto

Статья
11/23/2024

Чтобы настроить базу данных во время развертывания шаблона Azure Resource Manager (ARM), можно выполнить скрипт на языке запросов Kusto. Скрипт — это список одной или нескольких команд управления, разделенных по одной строке, и создается в качестве ресурса, доступ к которому осуществляется с помощью шаблона ARM.

Скрипт может выполнять только команды управления на уровне базы данных, которые начинаются со следующих команд:

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

Примечание.

Поддерживаемые команды должны выполняться на уровне базы данных. Например, можно изменить таблицу с помощью команды .create-or-alter table. Команды уровня кластера, такие как .alter cluster политики, не поддерживаются.

Обычно мы рекомендуем использовать идемпотентную версию команд, чтобы в случае, если они вызываются более одного раза с одними и теми же входными параметрами, они не имели побочных эффектов. Иными словами, многократное выполнение команды приводит к тому же результату, что и однократное. Например, мы рекомендуем по возможности использовать идемпотентную команду .create-or-alter вместо обычной команды .create.

Существует несколько методов, которые можно использовать для настройки базы данных с помощью скриптов. В этой статье мы рассмотрим следующие методы с помощью развертываний шаблонов ARM:

Встроенный скрипт. Скрипт предоставляется в виде параметра для шаблона ARM в формате JSON.
Скрипт Bicep. Скрипт предоставляется в виде отдельного файла, используемого шаблоном ARM Bicep.
Учетная запись хранения. Скрипт создается в качестве большого двоичного объекта в учетной записи хранения Azure и его сведения (URL-адреса и подписанные URL-адреса (SaS), предоставляемые в качестве параметров для шаблона ARM.

Примечание.

Каждый кластер может иметь не более 50 скриптов (больше сценариев активирует ошибку Code:TooManyScripts .) Рекомендуется объединить несколько небольших скриптов в менее крупные, после удаления существующих скриптов , чтобы освободить место для новых сценариев. Удаление скрипта не откатывает команды, которые были выполнены из этого скрипта.

Пример скрипта с командами управления

В следующем примере приведен сценарий с командами, создающими две таблицы: MyTable и 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)

Обратите внимание, что эти две команды идемпотентны. При первом выполнении они создают таблицы, при последующих — не имеют никакого эффекта.

Необходимые компоненты

Подписка Azure. Создайте бесплатную учетную запись Azure.
Кластер и база данных Azure Data Explorer. Создайте кластер и базу данных.

Безопасность

Субъект, например пользователь или субъект-служба, используемый для развертывания скрипта, должен иметь следующие роли безопасности:

роль участника в кластере;
роль администратора в базе данных.

Внимание

Субъект, подготавливающий кластер, автоматически получает в нем роль All Databases Admin.

Встроенный скрипт

Этот метод используется для создания шаблона ARM со скриптом, определенным в качестве встроенного параметра. Если в скрипте есть одна или несколько команд управления, разделите команды по крайней мере по одному разрыву строки.

Выполнение встроенного скрипта с помощью шаблона ARM

В следующем шаблоне показано, как запустить скрипт с помощью шаблона 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": {
    }
}

Используйте следующие параметры:

Параметр	Description
kqlScript	Встроенный сценарий на языке запросов Kusto. Используйте `\n` для добавления символов новой строки.
forceUpdateTag	Уникальная строка. При изменении скрипт снова применяется.
continueOnErrors	Флаг, указывающий, следует ли продолжать выполнение в случае сбоя одной из команд. Значение по умолчанию: false.
clusterName	Имя кластера, на котором выполняется скрипт.
databaseName	Имя базы данных, в которой выполняется скрипт.
scriptName	Имя скрипта в случае использования внешнего файла для предоставления скрипта. Это имя фактического ресурса шаблона ARM типа script.

Пропуск тега обновления

Запуск скрипта KQL при каждом развертывании шаблона ARM не рекомендуется, так как он потребляет ресурсы кластера. Запретить выполнение скрипта в последующих развертываниях можно с помощью следующих методов:

forceUpdateTag Укажите свойство и сохраните одно и то же значение между развертываниями.
Опустите свойство forceUpdateTag или оставьте его пустым и используйте один и тот же скрипт для всех развертываний.

Рекомендуется опустить forceUpdateTag свойство, чтобы все изменения скрипта выполнялись при следующем развертывании шаблона. Используйте свойство forceUpdateTag только в том случае, если необходимо принудительно выполнить скрипт.

Скрипт Bicep

Передача скрипта в качестве параметра шаблону может быть сложной. Шаблон Azure Resource Manager Bicep позволяет хранить и поддерживать скрипт в отдельном файле и загружать его в шаблон с помощью функции Bicep loadTextContent.

Если скрипт хранится в файле, расположенном в той же папке, что и файл script.kql Bicep, следующий шаблон создает тот же результат, что и предыдущий пример:

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

Используйте следующие параметры:

Параметр	Description
forceUpdateTag	Уникальная строка. При изменении скрипт снова применяется.
continueOnErrors	Флаг, указывающий, следует ли продолжать выполнение в случае сбоя одной из команд. Значение по умолчанию: false.
clusterName	Имя кластера, на котором выполняется скрипт.
databaseName	Имя базы данных, в которой выполняется скрипт.
scriptName	Имя скрипта в случае использования внешнего файла для предоставления скрипта.

Шаблон Bicep можно развернуть с помощью тех же средств, что и шаблон ARM JSON. Например, для развертывания шаблона можно использовать следующие команды Azure CLI:

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

Перед развертыванием шаблоны Bicep транскомпилируются в шаблон JSON ARM. В примере файл скрипта внедрен в шаблон JSON ARM. См. общие сведения о Bicep.

Скрипт учетной записи хранения

В этом методе предполагается, что вы уже создали BLOB-объект в учетной записи хранения Azure и указываете сведения о нем (URL-адрес и подписанные URL-адреса (SAS)) прямо в шаблоне ARM.

Примечание.

Скрипты нельзя загружать из учетных записей хранения, настроенных с помощью брандмауэра службы хранилища Azure или правил виртуальной сети.

Создание ресурса сценария

Первый шаг — создание скрипта и его отправка в учетную запись хранения.

Создайте скрипт, содержащий команды управления, которые вы хотите использовать для создания таблицы в базе данных.
Отправьте скрипт в учетную запись хранения Azure. Учетную запись хранения можно создать с помощью портала Azure, PowerShell или Azure CLI.
Предоставьте доступ к этому файлу, используя сигнатуры общего доступа (SAS). Вы можете предоставить доступ с помощью PowerShell, Azure CLI или .NET.

Выполнение скрипта с помощью шаблона ARM

В этом разделе описано, как запустить скрипт, хранящийся в служба хранилища Azure с помощью шаблона 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": {
  }
}

Используйте следующие параметры:

Параметр	Description
scriptUrl	URL-адрес большого двоичного объекта. Например, https://myaccount.blob.core.windows.net/mycontainer/myblob.
scriptUrlSastoken	Строка с подписанными URL-адресами (SAS).
forceUpdateTag	Уникальная строка. При изменении скрипт снова применяется.
continueOnErrors	Флаг, указывающий, следует ли продолжать выполнение в случае сбоя одной из команд. Значение по умолчанию: false.
clusterName	Имя кластера, на котором выполняется скрипт.
databaseName	Имя базы данных, в которой выполняется скрипт.
scriptName	Имя скрипта в случае использования внешнего файла для предоставления скрипта.

Ограничения

Скрипты поддерживаются только в Azure Data Explorer; Скрипты не поддерживаются в пулах Synapse Data Explorer.
В одном кластере нельзя одновременно добавить, изменить или удалить два скрипта. В этом случае возникает следующая ошибка: Code="ServiceIsInMaintenance" Эту проблему можно обойти, создав зависимость между двумя скриптами, чтобы они создавались или обновлялись последовательно.
Чтобы создать функции с запросами между кластерами с помощью скриптов, необходимо задать skipvalidation для свойства true значение в команде .create function.

Устранение неполадок

Команды, выполняемые ресурсом скрипта, не отображаются в результатах выполнения команды .show commands-and-queries. Выполнение скрипта можно отслеживать с помощью команды .show journal.

Обзор команд управления

Поделиться через

Настройка базы данных с помощью скрипта языка запросов Kusto

Пример скрипта с командами управления

Необходимые компоненты

Безопасность

Встроенный скрипт

Выполнение встроенного скрипта с помощью шаблона ARM

Пропуск тега обновления

Скрипт Bicep

Скрипт учетной записи хранения

Создание ресурса сценария

Выполнение скрипта с помощью шаблона ARM

Ограничения

Устранение неполадок

Обратная связь

Дополнительные ресурсы

Поделиться через

Настройка базы данных с помощью скрипта языка запросов Kusto

Пример скрипта с командами управления

Необходимые компоненты

Безопасность

Встроенный скрипт

Выполнение встроенного скрипта с помощью шаблона ARM

Пропуск тега обновления

Скрипт Bicep

Скрипт учетной записи хранения

Создание ресурса сценария

Выполнение скрипта с помощью шаблона ARM

Ограничения

Устранение неполадок

Связанный контент

Обратная связь

Дополнительные ресурсы