Compartir a través de

Configuración de una base de datos mediante un script del lenguaje de consulta Kusto

  • Artículo

Puede ejecutar un script del lenguaje de consulta Kusto para configurar la base de datos durante la implementación de la plantilla de Azure Resource Manager (ARM). Un script es una lista de uno o varios comandos de administración, cada uno separado por un salto de línea y se crea como un recurso al que se accede con la plantilla de ARM.

El script solo puede ejecutar comandos de administración de nivel de base de datos que empiecen por los verbos siguientes:

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

Nota:

Los comandos admitidos deben ejecutarse en el nivel de base de datos. Por ejemplo, puede modificar una tabla mediante el comando .create-or-alter table. No se admiten comandos de nivel de clúster, como .alter cluster directivas.

En general, se recomienda usar la versión idempotente de los comandos para que, si se les llama más de una vez con los mismos parámetros de entrada, no tengan ningún efecto adicional. En otras palabras, ejecutar el comando varias veces tiene el mismo efecto que ejecutarlo una vez. Por ejemplo, siempre que sea posible, se recomienda usar el comando idempotente .create-or-alter en lugar del comando .create normal.

Hay varios métodos que puede usar para configurar una base de datos con scripts. En este artículo, nos centramos en los métodos siguientes mediante implementaciones de plantillas de ARM:

  1. Script en línea: el script se proporciona en línea como un parámetro para una plantilla de ARM en formato JSON.
  2. Script de Bicep: el script se proporciona como un archivo independiente que una plantilla de ARM de Bicep usa.
  3. Cuenta de almacenamiento: el script se crea como un blob en una cuenta de Azure Storage y sus detalles (dirección URL y firmas de acceso compartido (SaS) proporcionados como parámetros para la plantilla de ARM.

Nota:

Cada clúster puede tener un máximo de 50 scripts (más scripts desencadenarán un Code:TooManyScripts error). Se recomienda combinar varios scripts pequeños en menos grandes, después de eliminar los scripts existentes para liberar espacio para los nuevos scripts. La eliminación de un script no revierte los comandos que se ejecutaron desde ese script.

Script de ejemplo con comandos de administración

El ejemplo siguiente es un script con comandos que crean dos tablas: MyTable y 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 los dos comandos son idempotentes. Cuando se ejecutan por primera vez, crean las tablas y, en las ejecuciones posteriores, no tienen ningún efecto.

Requisitos previos

Seguridad

La entidad de seguridad como, por ejemplo, un usuario o una entidad de servicio, que se usa para implementar un script debe tener los siguientes roles de seguridad:

Importante

La entidad de seguridad que aprovisiona el clúster obtiene automáticamente el rol All Databases Admin en el clúster.

Script en línea

Use este método para crear una plantilla de ARM con el script definido como parámetro insertado. Si el script tiene uno o varios comandos de administración, separe los comandos por al menos un salto de línea.

Ejecución de un script en línea mediante una plantilla de ARM

En la plantilla siguiente se muestra cómo ejecutar el script mediante una plantilla de Azure Resource Manager en formato 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 la configuración siguiente:

Configuración Descripción
kqlScript Script insertado del lenguaje de consulta Kusto Use \n para agregar caracteres de nueva línea.
forceUpdateTag Cadena única. Si se cambia, el script se vuelve a aplicar.
continueOnErrors Marca que indica si se debe continuar si se produce un error en uno de los comandos. Valor predeterminado: falso.
clusterName Nombre del clúster donde se ejecuta el script.
databaseName Nombre de la base de datos en la que se ejecuta el script.
scriptName Nombre del script si se usa un archivo externo para proporcionar el script. Este es el nombre del recurso de la plantilla de ARM real del tipo script.

Omisión de la etiqueta de actualización

No se recomienda ejecutar un script de KQL en cada implementación de plantilla de ARM ya que consume recursos del clúster. Puede evitar la ejecución del script en implementaciones sucesivas mediante los métodos siguientes:

  • Especifique la forceUpdateTag propiedad y mantenga el mismo valor entre implementaciones.
  • Omita la propiedad forceUpdateTag o déjela vacía y use el mismo script entre implementaciones.

El procedimiento recomendado consiste en omitir la forceUpdateTag propiedad para que los cambios de script se ejecuten la próxima vez que se implemente la plantilla. Use solo la propiedad forceUpdateTag si necesita forzar la ejecución del script.

Script de Bicep

Pasar un script como parámetro a una plantilla puede resultar complicado. La plantilla de Azure Resource Manager de Bicep le permite mantener y conservar el script en un archivo independiente y cargarlo en la plantilla mediante la función loadTextContent de Bicep.

Suponiendo que el script se almacena en un archivo script.kql ubicado en la misma carpeta que el archivo de Bicep, la plantilla siguiente genera el mismo resultado que el ejemplo 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 la configuración siguiente:

Configuración Descripción
forceUpdateTag Cadena única. Si se cambia, el script se vuelve a aplicar.
continueOnErrors Marca que indica que se debe continuar si se produce un error en uno de los comandos. Valor predeterminado: falso.
clusterName Nombre del clúster donde se ejecuta el script.
databaseName Nombre de la base de datos en la que se ejecuta el script.
scriptName Nombre del script si se usa un archivo externo para proporcionar el script.

La plantilla de Bicep se puede implementar mediante herramientas similares a la plantilla de ARM en formato JSON. Por ejemplo, puede usar los siguientes comandos de la CLI de Azure para implementar la plantilla:

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

Las plantillas de Bicep se transpilan en una plantilla de ARM en formato JSON antes de la implementación. En el ejemplo, el archivo de script está insertado en línea en la plantilla de ARM json. Para más información, consulte Información general de Bicep.

Script de la cuenta de almacenamiento

Este método supone que ya tiene un blob en una cuenta de Azure Storage y que proporciona sus detalles (dirección URL y firmas de acceso compartido) directamente en la plantilla de ARM.

Nota:

Los scripts no se pueden cargar desde cuentas de almacenamiento configuradas con un firewall de Azure Storage o reglas de Virtual Network.

Creación del recurso de script

El primer paso consiste en crear un script y cargarlo en una cuenta de almacenamiento.

  1. Cree un script que contenga los comandos de administración que desea usar para crear la tabla en la base de datos.

  2. Cargue el script en la cuenta de Azure Storage. Puede crear la cuenta de almacenamiento mediante Azure Portal, PowerShell o la CLI de Azure.

  3. Proporcione acceso a este archivo mediante firmas de acceso compartido (SaS). Puede proporcionar acceso mediante PowerShell, la CLI de Azure o .NET.

Ejecución de un script mediante una plantilla de ARM

En esta sección, aprenderá a ejecutar un script almacenado en Azure Storage con una plantilla de 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 la configuración siguiente:

Configuración Descripción
scriptUrl Dirección URL del blob. Por ejemplo: 'https://myaccount.blob.core.windows.net/mycontainer/myblob'.
scriptUrlSastoken Cadena con las firmas de acceso compartido (SaS).
forceUpdateTag Cadena única. Si se cambia, el script se vuelve a aplicar.
continueOnErrors Marca que indica si se debe continuar si se produce un error en uno de los comandos. Valor predeterminado: falso.
clusterName Nombre del clúster donde se ejecuta el script.
databaseName Nombre de la base de datos en la que se ejecuta el script.
scriptName Nombre del script si se usa un archivo externo para proporcionar el script.

Limitaciones

  • Los scripts solo se admiten en Azure Data Explorer; Los scripts no se admiten en grupos de Synapse Data Explorer.
  • No se pueden agregar, modificar ni quitar dos scripts en paralelo en el mismo clúster. Si esto ocurre, se produce el siguiente error: Code="ServiceIsInMaintenance" . Puede solucionar el problema colocando una dependencia entre los dos scripts para que se creen o actualicen secuencialmente.
  • Para crear funciones con consultas entre clústeres mediante scripts, debe establecer la skipvalidation propiedad true en el comando .create function.

Solución de problemas

Los comandos que ejecuta un recurso de script no aparecen en los resultados del comando .show commands-and-queries. Puede realizar un seguimiento de la ejecución del script mediante el comando .show journal.

Contenido relacionado