Kusto Sorgu Dili betiği kullanarak veritabanı yapılandırma

Azure Kaynak Yönetimi (ARM) şablonu dağıtımı sırasında veritabanınızı yapılandırmak için bir Kusto Sorgu Dili betiği çalıştırabilirsiniz. Betik, her biri bir satır sonuyla ayrılmış bir veya daha fazla yönetim komutu listesidir ve ARM şablonu kullanılarak erişilen bir kaynak olarak oluşturulur.

Betik yalnızca aşağıdaki fiillerle başlayan veritabanı düzeyinde yönetim komutlarını çalıştırabilir:

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

Genel olarak, aynı giriş parametreleriyle birden çok kez çağrılsalar bile ek bir etkisi olmaması için komutların idempotent sürümünü kullanmanızı öneririz. Başka bir deyişle, komutu birden çok kez çalıştırmak, bir kez çalıştırmakla aynı etkiye sahiptir. Örneğin, mümkün olduğunda, normal .create-or-alter komut üzerinde idempotent komutunu .create kullanmanızı öneririz.

Veritabanını betiklerle yapılandırmak için kullanabileceğiniz çeşitli yöntemler vardır. Bu makalede ARM şablonu dağıtımlarını kullanarak aşağıdaki yöntemlere odaklanacağız:

1. Satır içi betik: Betik, bir JSON ARM şablonunun parametresi olarak satır içi olarak sağlanır.
2. Bicep betiği: Betik, Bicep ARM şablonu tarafından kullanılan ayrı bir dosya olarak sağlanır.
3. Depolama Hesabı: Betik, Azure depolama hesabında bir blob olarak oluşturulur ve detayları (URL ve paylaşılan erişim imzaları (SAS) ARM şablonuna parametre olarak sağlanmaktadır.

Yönetim komutlarıyla örnek script

Aşağıdaki örnek, iki tablo oluşturan komutları içeren bir betiktir: MyTable ve 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)

İki komutun idempotent olduğuna dikkat edin. İlk çalıştırmada tabloları oluştururlar, sonraki çalıştırmalarda hiçbir etkisi olmaz.

Önkoşullar

• Azure aboneliği. Ücretsiz bir Azure hesabı oluşturun.
• Azure Veri Gezgini kümesi ve veritabanı. Küme ve veritabanı oluşturma.

Güvenlik

Bir betiği dağıtmak için kullanılan kullanıcı veya hizmet sorumlusu gibi sorumlu aşağıdaki güvenlik rollerine sahip olmalıdır:

• Kümede katkıda bulunan rolü
• Veritabanında yönetici rolü

Satır içi betik

Bir ARM şablonu oluşturmak için betiği satır içi parametre olarak tanımlayarak bu yöntemi kullanın. Betiğinizde bir veya daha fazla yönetim komutu varsa, komutları en az bir satır sonu ile ayırın.

ARM şablonu kullanarak satır içi betik çalıştırma

Aşağıdaki şablonda, bir JSON Azure Resource Manager şablonu kullanarak betiğin nasıl çalıştırılacakları gösterilmektedir.

{
    "$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": {
    }
}

Aşağıdaki ayarları kullanın:

Güncelleştirme etiketini atla

Küme kaynaklarını tükettiği için her ARM şablonu dağıtımında bir KQL betiği çalıştırılması önerilmez. Aşağıdaki yöntemleri kullanarak betiğin ardışık dağıtımlarda çalıştırılmasını engelleyebilirsiniz:

• forceUpdateTag özelliğini belirtin ve dağıtımlar arasında aynı değeri koruyun.
• forceUpdateTag özelliğini atlamayın veya boş bırakın ve dağıtımlar arasında aynı betiği kullanmaya devam edin.

En iyi uygulama, şablon bir sonraki kez dağıtıldığında tüm betik değişikliklerinin uygulanmasını sağlamak için forceUpdateTag özelliğinin atlanmasıdır. Yalnızca betiği çalıştırmaya zorlamanız gerekiyorsa forceUpdateTag özelliğini kullanın.

Bicep betiği

Betiği şablona parametre olarak aktarmak zorlayıcı olabilir. Bicep Azure Resource Manager şablonu, betiği ayrı bir dosyada tutmanızı ve korumanızı ve loadTextContent Bicep işlevini kullanarak şablona yüklemenizi sağlar.

Betiğin, Bicep dosyasıyla script.kql aynı klasörde bulunan bir dosyada saklandığını varsayarsak, aşağıdaki şablon önceki örnekle aynı sonucu verir.

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

Aşağıdaki ayarları kullanın:

Bicep şablonu, JSON ARM şablonuyla benzer araçlar kullanılarak dağıtılabilir. Örneğin, şablonu dağıtmak için aşağıdaki Azure CLI komutlarını kullanabilirsiniz:

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

Bicep şablonları dağıtımdan önce JSON ARM şablonuna dönüştürülür. Örnekte, betik dosyası JSON ARM şablonuna satır içine eklenmiştir. Daha fazla bilgi için Bicep'e genel bakış bölümüne bakın.

Depolama hesabı betiği

Bu yöntem, Azure Depolama hesabında zaten bir bloba sahip olduğunuzu ve ayrıntılarını (URL ve paylaşılan erişim imzaları (SaS)) doğrudan ARM şablonunda sağladığınızı varsayar.

Betik kaynağını oluştur

İlk adım bir betik oluşturmak ve bunu bir depolama hesabına yüklemektir.

1. Veritabanınızda tablo oluşturmak için kullanmak istediğiniz yönetim komutlarını içeren bir betik oluşturun.

2. Betiğinizi Azure Depolama hesabınıza yükleyin. Depolama hesabınızı Azure portalı, PowerShell veya Azure CLI kullanarak oluşturabilirsiniz.

3. Paylaşılan erişim imzalarını (SaS) kullanarak bu dosyaya erişim sağlayın. PowerShell, Azure CLI veya .NET kullanarak erişim sağlayabilirsiniz.

ARM şablonu kullanarak betiği çalıştırma

Bu bölümde, Azure Resource Manager şablonuyla Azure Depolama'da depolanan bir betiği çalıştırmayı öğreneceksiniz.

{
  "$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": {
  }
}

Aşağıdaki ayarları kullanın:

Sınırlamalar

• Betikler yalnızca Azure Veri Gezgini'nde desteklenir.
• Aynı kümede iki script paralel olarak eklenemez, değiştirilemez veya kaldırılamaz. Bu durum oluşursa, aşağıdaki hata oluşur: Code="ServiceIsInMaintenance" İki betik arasına bir bağımlılık yerleştirip bunların sırayla oluşturulmasını veya güncelleştirilmesini sağlayarak sorunu çözebilirsiniz.
• Betikleri kullanarak kümeler arası sorgularla işlevler oluşturmak için ,create function komutunda skipvalidationözelliğini true olarak ayarlamanız gerekir.
• Kimliğe bürünme kullanan çapraz küme sorguları ve çağrılar desteklenmez.

Sorun giderme

Betik kaynağı tarafından çalıştırılan komutlar, .show commands-and-queries komutunun sonuçlarında görünmez. .show journal komutunu kullanarak betik yürütmesini izleyebilirsiniz.

İlgili içerik

• Yönetim komutlara genel bakış