Mengonfigurasi database menggunakan skrip Bahasa Kueri Kusto

Anda dapat menjalankan skrip Bahasa Kueri Kusto untuk mengonfigurasi database Anda selama penyebaran templat Azure Resource Management (ARM). Skrip adalah daftar satu atau beberapa perintah manajemen, masing-masing dipisahkan oleh satu hentian baris, dan dibuat sebagai sumber daya yang dapat diakses menggunakan templat ARM.

Skrip hanya dapat menjalankan perintah manajemen tingkat database yang dimulai dengan kata kerja berikut:

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

Catatan

Perintah yang didukung harus dijalankan di tingkat database. Misalnya, Anda dapat mengubah tabel menggunakan perintah .create-or-alter table. Perintah tingkat kluster, seperti kebijakan .alter cluster, tidak didukung.

Secara umum, sebaiknya gunakan versi perintah idempogen sehingga jika dipanggil lebih dari sekali dengan parameter input yang sama, mereka tidak memiliki efek tambahan. Dengan kata lain, menjalankan perintah beberapa kali memiliki efek yang sama seperti menjalankannya sekali. Misalnya, jika memungkinkan, sebaiknya gunakan perintah .create-or-alter idempoten daripada perintah reguler .create.

Ada berbagai metode yang dapat Anda gunakan untuk mengonfigurasi database dengan skrip. Dalam artikel ini, kami berfokus pada metode berikut menggunakan penyebaran templat ARM:

Skrip Sebaris: Skrip disediakan sebaris sebagai parameter untuk templat JSON ARM.
Bicep script: Skrip ini disediakan sebagai file terpisah yang digunakan oleh template ARM Bicep.
Akun Penyimpanan: Skrip dibuat sebagai blob di akun penyimpanan Azure dan detailnya (URL serta tanda tangan akses bersama (SaS)) disediakan sebagai parameter ke templat ARM.

Catatan

Setiap kluster dapat memiliki maksimum 50 skrip (lebih banyak skrip akan memicu Code:TooManyScripts kesalahan.) Disarankan untuk menggabungkan beberapa skrip kecil menjadi lebih sedikit skrip besar, setelah menghapus skrip yang ada untuk mengosongkan ruang untuk skrip baru. Menghapus skrip tidak mengembalikan perintah yang dijalankan dari skrip tersebut.

Contoh skrip dengan perintah manajemen

Contoh berikut adalah skrip dengan perintah yang membuat dua tabel: MyTable dan 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)

Perhatikan bahwa kedua perintah tersebut idempotensi. Saat pertama kali dijalankan, mereka membuat tabel, pada eksekusi berikutnya, tabel tersebut tidak berpengaruh.

Prasyarat

Langganan Azure. Membuat akun Azure gratis.
Kluster dan database Azure Data Explorer. Membuat kluster dan database.

Keamanan

Prinsipal, seperti pengguna atau perwakilan layanan, yang digunakan untuk menyebarkan skrip harus memiliki peran keamanan berikut:

Peran kontributor pada kluster
Peran admin pada database

Penting

Penyedia utama kluster secara otomatis mendapatkan All Databases Admin peran pada kluster.

Skrip inline

Gunakan metode ini untuk membuat templat ARM dengan skrip yang didefinisikan sebagai parameter sebaris. Jika skrip Anda memiliki satu atau beberapa perintah manajemen, pisahkan perintah dengan setidaknya satu hentian baris.

Menjalankan skrip sebaris menggunakan templat ARM

Templat berikut menunjukkan cara menjalankan skrip menggunakan templat JSON Azure Resource Manager.

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

Gunakan pengaturan berikut:

Pengaturan	Deskripsi
kqlScript	Skrip Bahasa Kueri Kusto sebaris. Gunakan `\n` untuk menambahkan karakter baris baru.
forceUpdateTag	String unik. Jika diubah, skrip diterapkan lagi.
lanjutkanJikaTerjadiKesalahan	Bendera yang menunjukkan apakah akan melanjutkan jika salah satu perintah gagal. Nilai default: salah.
clusterName	Nama kluster tempat skrip berjalan.
databaseName	Nama database tempat skrip berjalan.
scriptName	Nama skrip saat menggunakan file eksternal untuk menyediakan skrip. Ini adalah nama sumber daya templat ARM aktual dari jenis skrip.

Hilangkan tag pembaruan

Menjalankan skrip KQL di setiap penyebaran templat ARM tidak disarankan karena menggunakan sumber daya kluster. Anda dapat mencegah berjalannya skrip dalam penyebaran berturut-turut menggunakan metode berikut:

Tentukan properti forceUpdateTag dan pertahankan nilai yang sama di antara tiap kali penerapan.
Hilangkan properti forceUpdateTag, atau biarkan kosong, dan gunakan skrip yang sama di antara penerapan.

Praktik terbaik adalah menghilangkan properti forceUpdateTag sehingga setiap perubahan skrip dijalankan ketika templat disebarkan selanjutnya. Hanya gunakan forceUpdateTag properti jika Anda perlu memaksa skrip untuk dijalankan.

Skrip Bicep

Meneruskan skrip sebagai parameter ke templat bisa rumit. Templat Bicep Azure Resource Manager memungkinkan Anda menyimpan dan memelihara skrip dalam file terpisah dan memuatnya ke dalam templat menggunakan fungsi loadTextContent Bicep.

Dengan asumsi skrip disimpan dalam file script.kql yang terletak di folder yang sama dengan file Bicep, templat berikut menghasilkan hasil yang sama dengan contoh sebelumnya:

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

Gunakan pengaturan berikut:

Pengaturan	Deskripsi
forceUpdateTag	String unik. Jika diubah, skrip diterapkan lagi.
lanjutkanJikaTerjadiKesalahan	Bendera yang menunjukkan untuk melanjutkan jika salah satu perintah gagal. Nilai default: salah.
clusterName	Nama kluster tempat skrip berjalan.
databaseName	Nama database tempat skrip berjalan.
scriptName	Nama skrip saat menggunakan file eksternal untuk menyediakan skrip.

Templat Bicep dapat disebarkan menggunakan alat serupa seperti templat JSON ARM. Misalnya, Anda dapat menggunakan perintah Azure CLI berikut untuk menyebarkan templat:

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

Templat Bicep ditranspilasi ke templat JSON ARM sebelum penyebaran. Dalam contoh, file skrip disematkan sebaris dalam templat JSON ARM. Untuk informasi selengkapnya, lihat gambaran umum Bicep.

Skrip untuk akun penyimpanan

Metode ini mengasumsikan bahwa Anda sudah memiliki blob di akun Azure Storage dan Anda memberikan detailnya (URL dan tanda tangan akses bersama (SaS)) langsung di templat ARM.

Catatan

Skrip tidak dapat dimuat dari akun penyimpanan yang dikonfigurasi dengan firewall Azure Storage atau aturan Virtual Network.

Membuat sumber daya skrip

Langkah pertama adalah membuat skrip dan mengunggahnya ke akun penyimpanan.

Buat skrip yang berisi perintah manajemen yang ingin Anda gunakan untuk membuat tabel di database Anda.
Unggah skrip Anda ke akun Azure Storage Anda. Anda dapat membuat akun penyimpanan menggunakan portal Azure, PowerShell, atau Azure CLI.
Berikan akses ke file ini menggunakan tanda tangan akses bersama (SaS). Anda dapat menyediakan akses menggunakan PowerShell, Azure CLI, atau .NET.

Menjalankan skrip menggunakan templat ARM

Di bagian ini, Anda mempelajari cara menjalankan skrip yang disimpan di Azure Storage dengan templat 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": {
  }
}

Gunakan pengaturan berikut:

Pengaturan	Keterangan
scriptUrl	URL dari blob. Misalnya, 'https://myaccount.blob.core.windows.net/mycontainer/myblob'.
scriptUrlSastoken	String dengan tanda tangan akses bersama (SaS).
forceUpdateTag	String unik. Jika diubah, skrip diterapkan lagi.
continueOnErrors	Bendera yang menunjukkan apakah akan melanjutkan jika salah satu perintah gagal. Nilai default: salah.
clusterName	Nama kluster tempat skrip berjalan.
databaseName	Nama database tempat skrip berjalan.
scriptName	Nama skrip saat menggunakan file eksternal untuk menyediakan skrip.

Batasan

Skrip hanya didukung di Azure Data Explorer.
Dua skrip tidak dapat ditambahkan, dimodifikasi, atau dihapus secara paralel pada kluster yang sama. Jika ini terjadi, kesalahan berikut: Code="ServiceIsInMaintenance" akan muncul. Anda dapat mengatasi masalah ini dengan menempatkan dependensi antara dua skrip sehingga dibuat atau diperbarui secara berurutan.
Untuk membuat fungsi dengan kueri lintas kluster menggunakan skrip, Anda harus mengatur properti ke dalam perintah .create function.
Kueri lintas kluster dan callout yang menggunakan peniruan tidak didukung.

Pemecahan Masalah

Perintah yang dijalankan oleh sumber daya skrip tidak muncul di hasil perintah .show commands-and-queries . Anda dapat melacak eksekusi skrip menggunakan perintah jurnal .show.

Gambaran umum perintah manajemen

Saran dan Komentar

Apakah halaman ini membantu?

Last updated on 2026-03-12

Bagikan melalui

Mengonfigurasi database menggunakan skrip Bahasa Kueri Kusto

Contoh skrip dengan perintah manajemen

Prasyarat

Keamanan

Skrip inline

Menjalankan skrip sebaris menggunakan templat ARM

Hilangkan tag pembaruan

Skrip Bicep

Skrip untuk akun penyimpanan

Membuat sumber daya skrip

Menjalankan skrip menggunakan templat ARM

Batasan

Pemecahan Masalah

Konten terkait

Saran dan Komentar

Sumber Daya Tambahan: