Konfigurowanie bazy danych przy użyciu skryptu języka zapytań Kusto

Możesz uruchomić skrypt język zapytań Kusto, aby skonfigurować bazę danych podczas wdrażania szablonu usługi Azure Resource Management (ARM). Skrypt to lista jednego lub więcej poleceń zarządzania, z których każde jest oddzielone jednym znakiem nowej linii i tworzony jako zasób, do którego dostęp uzyskuje się przy użyciu szablonu ARM.

Skrypt może uruchamiać tylko polecenia zarządzania na poziomie bazy danych, które zaczynają się od następujących zleceń:

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

Uwaga

Obsługiwane polecenia muszą być uruchamiane na poziomie bazy danych. Na przykład możesz zmienić tabelę przy użyciu polecenia .create-or-alter table. Polecenia na poziomie klastra, takie jak .alter cluster polityki, nie są obsługiwane.

Ogólnie rzecz biorąc, zalecamy użycie idempotentnej wersji poleceń, aby jeśli są wywoływane więcej niż raz z tymi samymi parametrami wejściowymi, nie mają one dodatkowego efektu. Innymi słowy, uruchomienie polecenia wiele razy ma taki sam efekt, jak uruchomienie go raz. Jeśli to możliwe, zalecamy użycie idempotentnego polecenia .create-or-alter za pomocą zwykłego .create polecenia.

Istnieją różne metody, których można użyć do skonfigurowania bazy danych za pomocą skryptów. W tym artykule skoncentrujemy się na następujących metodach przy użyciu wdrożeń szablonów ARM.

Skrypt załączony w linii: Skrypt jest podany bezpośrednio w linii jako parametr szablonu ARM w formacie JSON.
Skrypt Bicep: skrypt jest dostarczany jako oddzielny plik używany przez szablon usługi ARM Bicep.
Konto magazynowania: skrypt jest tworzony jako blob na koncie Azure Storage i jego szczegóły takie jak adres URL i sygnatury dostępu współdzielonego (SaS) są podane jako parametry szablonu ARM.

Uwaga

Każdy klaster może mieć maksymalnie 50 skryptów (więcej skryptów wyzwoli Code:TooManyScripts błąd). Zaleca się scalanie wielu małych skryptów z mniejszą liczbą dużych skryptów po usunięciu istniejących skryptów, aby zwolnić miejsce na nowe skrypty . Usunięcie skryptu nie powoduje wycofania poleceń wykonanych z tego skryptu.

Przykładowy skrypt z poleceniami zarządzania

Poniższy przykład to skrypt z poleceniami, które tworzą dwie tabele: MyTable i 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)

Zwróć uwagę, że dwa polecenia są idempotentne. Po pierwszym uruchomieniu tworzą tabele, w kolejnych uruchomieniach nie mają już wpływu.

Wymagania wstępne

Subskrypcja platformy Azure. Utwórz bezpłatne konto platformy Azure.
Baza danych i klaster usługi Azure Data Explorer. Utwórz klaster i bazę danych.

Zabezpieczenia

Główny podmiot, taki jak użytkownik lub podmiot usługi, używany do wdrażania skryptu, musi mieć następujące role zabezpieczeń:

Rola współautora w klastrze
Rola administratora w bazie danych

Ważne

Główny dostawca klastra automatycznie otrzymuje All Databases Admin rolę w klastrze.

Skrypt wbudowany

Użyj tej metody, aby utworzyć szablon usługi ARM ze skryptem zdefiniowanym jako wbudowany parametr. Jeśli skrypt ma co najmniej jedno polecenie zarządzania, rozdziel polecenia co najmniej jednym podziałem wiersza.

Uruchamianie skryptu inline przy użyciu szablonu ARM

Poniższy szablon przedstawia sposób uruchamiania skryptu przy użyciu szablonu usługi Azure Resource Manager w formacie 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": {
    }
}

Użyj następujących ustawień:

Ustawienie	opis
kqlScript	Skrypt linijny dla języka zapytań Kusto. Użyj `\n` polecenia , aby dodać nowe znaki wiersza.
forceUpdateTag	Unikatowy ciąg. W przypadku zmiany skrypt zostanie ponownie zastosowany.
continueOnErrors	Flaga wskazująca, czy kontynuować, jeśli jedno z poleceń zakończy się niepowodzeniem. Wartość domyślna: false
nazwa_klastra	Nazwa klastra, w którym jest uruchamiany skrypt.
databaseName	Nazwa bazy danych, w której jest uruchamiany skrypt.
scriptName	Nazwa skryptu podczas używania pliku zewnętrznego do podawania skryptu. Jest to nazwa rzeczywistego zasobu szablonu ARM typu skrypt.

Pomijanie tagu aktualizacji

Uruchamianie skryptu KQL w każdym wdrożeniu szablonu usługi ARM nie jest zalecane, ponieważ zużywa zasoby klastra. Uruchamianie skryptu w kolejnych wdrożeniach można uniemożliwić przy użyciu następujących metod:

forceUpdateTag Określ właściwość i zachowaj tę samą wartość między wdrożeniami.
Pomiń forceUpdateTag właściwość lub pozostaw ją pustą i użyj tego samego skryptu między wdrożeniami.

Najlepszym rozwiązaniem jest pominięcie forceUpdateTag właściwości, tak aby wszystkie zmiany skryptu zostały uruchomione przy następnym wdrożeniu szablonu. Użyj forceUpdateTag właściwości tylko wtedy, gdy musisz wymusić uruchomienie skryptu.

Skrypt Bicep

Przekazywanie skryptu jako parametru do szablonu może być kłopotliwe. Szablon usługi Azure Resource Manager Bicep umożliwia przechowywanie i konserwowanie skryptu w osobnym pliku i ładowanie go do szablonu przy użyciu funkcji loadTextContent Bicep.

Zakładając, że skrypt jest przechowywany w pliku script.kql znajdującym się w tym samym folderze co plik Bicep, poniższy szablon generuje taki sam wynik jak w poprzednim przykładzie:

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

Użyj następujących ustawień:

Ustawienie	opis
forceUpdateTag	Unikatowy ciąg. W przypadku zmiany skrypt zostanie ponownie zastosowany.
continueOnErrors	Flaga wskazująca, aby kontynuować, jeśli jedno z poleceń zakończy się niepowodzeniem. Wartość domyślna: false
nazwa_klastra	Nazwa klastra, w którym jest uruchamiany skrypt.
databaseName	Nazwa bazy danych, w której jest uruchamiany skrypt.
scriptName	Nazwa skryptu podczas używania pliku zewnętrznego do podawania skryptu.

Szablon Bicep można wdrożyć przy użyciu podobnych narzędzi jak szablon ARM w formacie JSON. Na przykład do wdrożenia szablonu można użyć następujących poleceń interfejsu wiersza polecenia platformy Azure:

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

** Szablony Bicep są transpilowane do szablonu JSON ARM przed wdrożeniem. W tym przykładzie plik skryptu jest osadzony w szablonie ARM JSON jako element wbudowany. Aby uzyskać więcej informacji, zobacz Przegląd Bicep.

Skrypt konta magazynu

W tej metodzie przyjęto założenie, że masz już obiekt blob na koncie usługi Azure Storage i podajesz jego szczegóły (adres URL i sygnatury dostępu współdzielonego) bezpośrednio w szablonie usługi ARM.

Uwaga

Skryptów nie można załadować z kont magazynu skonfigurowanych przy użyciu zapory Azure Storage lub reguł sieci wirtualnej.

Tworzenie zasobu skryptu

Pierwszym krokiem jest utworzenie skryptu i przekazanie go do konta przechowywania.

Utwórz skrypt zawierający polecenia zarządzania, których chcesz użyć do utworzenia tabeli w bazie danych.
Przekaż skrypt do konta usługi Azure Storage. Konto magazynowe można utworzyć przy użyciu portalu Azure, programu PowerShell lub Azure CLI.
Zapewnij dostęp do tego pliku przy użyciu sygnatur dostępu współdzielonego (SaS). Dostęp można zapewnić przy użyciu programu PowerShell, interfejsu wiersza polecenia platformy Azure lub platformy .NET.

Uruchamianie skryptu przy użyciu szablonu usługi ARM

W tej sekcji dowiesz się, jak uruchomić skrypt przechowywany w usłudze Azure Storage przy użyciu szablonu usługi 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": {
  }
}

Użyj następujących ustawień:

Ustawienie	Opis
scriptUrl	Adres URL obiektu blob. Na przykład 'https://myaccount.blob.core.windows.net/mycontainer/myblob'.
scriptUrlSastoken	Ciąg z sygnaturami dostępu współdzielonego (SaS).
forceUpdateTag	Unikatowy ciąg. W przypadku zmiany skrypt zostanie ponownie zastosowany.
continueOnErrors	Flaga wskazująca, czy kontynuować, jeśli jedno z poleceń zakończy się niepowodzeniem. Wartość domyślna: false
nazwa_klastra	Nazwa klastra, w którym jest uruchamiany skrypt.
databaseName	Nazwa bazy danych, w której jest uruchamiany skrypt.
scriptName	Nazwa skryptu podczas używania pliku zewnętrznego do podawania skryptu.

Ograniczenia

Skrypty są obsługiwane tylko w usłudze Azure Data Explorer.
Nie można dodawać, modyfikować ani usuwać dwóch skryptów równolegle w tym samym klastrze. W takim przypadku zostanie zgłoszony następujący błąd: Code="ServiceIsInMaintenance" Problem można obejść, umieszczając zależność między dwoma skryptami, aby były tworzone lub aktualizowane sekwencyjnie.
Aby utworzyć funkcje z zapytaniami między klastrami przy użyciu skryptów, należy ustawić właściwość skipvalidation na wartość true w poleceniu .create function.
Zapytania międzyklastrowe i wywołania korzystające z podszywania się nie są obsługiwane.

Rozwiązywanie problemów

Polecenia uruchamiane przez zasób skryptu nie są wyświetlane w wynikach polecenia .show commands-and-queries . Wykonywanie skryptu można śledzić za pomocą polecenia .show journal .

Omówienie poleceń zarządzania

Opinia

Czy ta strona była pomocna?

Last updated on 2026-03-12

Udostępnij za pośrednictwem

Konfigurowanie bazy danych przy użyciu skryptu języka zapytań Kusto

Przykładowy skrypt z poleceniami zarządzania

Wymagania wstępne

Zabezpieczenia

Skrypt wbudowany

Uruchamianie skryptu inline przy użyciu szablonu ARM

Pomijanie tagu aktualizacji

Skrypt Bicep

Skrypt konta magazynu

Tworzenie zasobu skryptu

Uruchamianie skryptu przy użyciu szablonu usługi ARM

Ograniczenia

Rozwiązywanie problemów

Powiązana zawartość

Opinia

Dodatkowe zasoby