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

Чтобы настроить базу данных во время развертывания шаблона 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:

Встроенный скрипт: Скрипт предоставляется как встроенный параметр для JSON-шаблона ARM.
Скрипт 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": {
    }
}

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

Настройка	Описание
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
    }
}

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

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

Ограничения

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

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

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

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

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

Были ли сведения на этой странице полезными?

Last updated on 2026-03-12

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

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

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

Предварительные требования

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

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

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

Исключить тег обновления

Скрипт Bicep

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

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

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

Ограничения

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

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

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

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