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

Makale
02/19/2024

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 şablonuyla 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

Not

Desteklenen komutlar veritabanı düzeyinde çalıştırılmalıdır. Örneğin, komutunu .create-or-alter tablekullanarak bir tabloyu değiştirebilirsiniz. İlkeler gibi .alter cluster küme düzeyi komutları desteklenmez.

Genel olarak, aynı giriş parametreleriyle birden çok kez çağrılırlarsa ek bir etkisi olmaması için komutların bir kez etkili olan 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 komut üzerinde bir kez etkili komutunu .create-or-alter kullanmanızı öneririz.

Bir 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:

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

Not

Her kümede en fazla 50 betik olabilir (daha fazla betik hata Code:TooManyScripts tetikler.) Yeni betikler için yer açmak için mevcut betikleri sildikten sonra birden çok küçük betikleri daha az büyük betikte birleştirmenizi öneririz. Bir betiğin silinmesi, bu betikten yürütülen komutları geri almaz.

Yönetim komutlarını içeren örnek betik

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 bir kez etkili olduğunu fark edin. İlk çalıştırıldığında 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ü

Önemli

Kümeyi sağlama sorumlusu, kümedeki All Databases Admin rolü otomatik olarak alır.

Satır içi betik

Satır içi parametre olarak tanımlanan betikle bir ARM şablonu oluşturmak için 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:

Ayar	Açıklama
kqlScript	Satır içi Kusto Sorgu Dili betiği. Yeni satır karakterleri eklemek için kullanın `\n` .
forceUpdateTag	Benzersiz bir dize. Değiştirilirse, betik yeniden uygulanır.
continueOnErrors	Komutlardan biri başarısız olursa devam edilip edilmeyeceğini belirten bir bayrak. Varsayılan Değer: false.
clusterName	Betiğin çalıştırıldığı kümenin adı.
veritabanıAdı	Betiğin altında çalıştığı veritabanının adı.
scriptName	Betiği sağlamak için bir dış dosya kullanırken betiğin adı. Bu, betik türündeki gerçek ARM şablonu kaynağının adıdır.

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ı önleyebilirsiniz:

forceUpdateTag özelliğini belirtin ve dağıtımlar arasında aynı değeri koruyun.
Özelliğini atlayın forceUpdateTag veya boş bırakın ve dağıtımlar arasında aynı betiği kullanın.

En iyi yöntem, şablonun bir sonraki dağıtılışında forceUpdateTag betik değişikliklerinin çalıştırılması için özelliğinin atlanmış olmasıdır. Yalnızca betiği çalıştırmaya zorlamanız gerekiyorsa özelliğini kullanın forceUpdateTag .

Bicep betiği

Betiği şablona parametre olarak geçirmek zahmetli olabilir. Bicep Azure Resource Manager şablonu, betiği ayrı bir dosyada tutmanızı ve loadTextContent Bicep işlevini kullanarak şablona yüklemenizi sağlar.

Betiğin Bicep dosyasıyla aynı klasörde bulunan bir dosyada script.kql depolandığı varsayıldığında, aşağıdaki şablon önceki örnektekiyle 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:

Ayar	Açıklama
forceUpdateTag	Benzersiz bir dize. Değiştirilirse, betik yeniden uygulanır.
continueOnErrors	Komutlardan biri başarısız olursa devam etmek için bir bayrak. Varsayılan Değer: false.
clusterName	Betiğin çalıştırıldığı kümenin adı.
veritabanıAdı	Betiğin altında çalıştığı veritabanının adı.
scriptName	Betiği sağlamak için bir dış dosya kullanırken betiğin adı.

Bicep şablonu, JSON ARM şablonuna 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 bkz . Bicep'e genel bakış.

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.

Not

Betikler, Azure Depolama güvenlik duvarı veya Sanal Ağ kurallarıyla yapılandırılmış depolama hesaplarından yüklenemez.

Betik kaynağını oluşturma

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

Veritabanınızda tablo oluşturmak için kullanmak istediğiniz yönetim komutlarını içeren bir betik oluşturun.
Betiğinizi Azure Depolama hesabınıza yükleyin. depolama hesabınızı Azure portal, PowerShell'i veya Azure CLI'yı kullanarak oluşturabilirsiniz.
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 Depolama'da depolanan bir betiği Azure Resource Manager şablonuyla ç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:

Ayar	Açıklama
scriptUrl	Blobun URL'si. Örneğin, 'https://myaccount.blob.core.windows.net/mycontainer/myblob'.
scriptUrlSastoken	Paylaşılan erişim imzalarına (SaS) sahip bir dize.
forceUpdateTag	Benzersiz bir dize. Değiştirilirse, betik yeniden uygulanır.
continueOnErrors	Komutlardan biri başarısız olursa devam edilip edilmeyeceğini belirten bir bayrak. Varsayılan Değer: false.
clusterName	Betiğin çalıştığı kümenin adı.
veritabanıAdı	Betiğin altında çalıştığı veritabanının adı.
scriptName	Betiği sağlamak için bir dış dosya kullanırken betiğin adı.

Sınırlamalar

Betikler yalnızca Azure Veri Gezgini'da desteklenir; Synapse Veri Gezgini havuzlarında betikler desteklenmez.
Aynı kümede paralel olarak iki betik 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şlev oluşturmak için .create function komutunda özelliğini true olarak ayarlamanız skipvalidation gerekir.

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.

Yönetim komutlarını genel bakış

Aracılığıyla paylaş

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

Yönetim komutlarını içeren örnek betik

Önkoşullar

Güvenlik

Satır içi betik

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

Güncelleştirme etiketini atla

Bicep betiği

Depolama hesabı betiği

Betik kaynağını oluşturma

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

Sınırlamalar

Sorun giderme

Geri Bildirim

Ek kaynaklar

Aracılığıyla paylaş

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

Yönetim komutlarını içeren örnek betik

Önkoşullar

Güvenlik

Satır içi betik

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

Güncelleştirme etiketini atla

Bicep betiği

Depolama hesabı betiği

Betik kaynağını oluşturma

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

Sınırlamalar

Sorun giderme

İlgili içerik

Geri Bildirim

Ek kaynaklar