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

Artykuł
11/23/2024

Możesz uruchomić skrypt język zapytań Kusto, aby skonfigurować bazę danych podczas wdrażania szablonu usługi Azure Resource Management (ARM). Skrypt jest listą co najmniej jednego polecenia zarządzania, z których każdy jest oddzielony jednym podziałem wiersza i jest tworzony jako zasób, do którego uzyskuje się dostęp za pomocą szablonu usługi 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 zasady, 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 usługi ARM:

Skrypt wbudowany: skrypt jest podany w tekście jako parametr szablonu usługi ARM w formacie JSON.
Skrypt Bicep: skrypt jest dostarczany jako oddzielny plik używany przez szablon usługi ARM Bicep.
Konto magazynu: skrypt jest tworzony jako obiekt blob na koncie usługi Azure Storage i jego szczegóły (adres URL i sygnatury dostępu współdzielonego (SaS) podane jako parametry szablonu usługi 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, które nie mają 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

Podmiot zabezpieczeń, taki jak użytkownik lub jednostka 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

Jednostka aprowizacji klastra automatycznie pobiera 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 wbudowanego przy użyciu szablonu usługi 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	Wbudowany skrypt język 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 usługi ARM typu skryptu.

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 usługi 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 arm JSON przed wdrożeniem. W tym przykładzie plik skryptu jest osadzony w tekście w szablonie usługi ARM JSON. Aby uzyskać więcej informacji, zobacz Omówienie 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 usługi Azure Storage lub reguł sieci wirtualnej.

Tworzenie zasobu skryptu

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

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 magazynu można utworzyć przy użyciu witryny Azure Portal, programu PowerShell lub interfejsu wiersza polecenia platformy Azure.
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; Skrypty nie są obsługiwane w pulach usługi Synapse 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ć skipvalidation właściwość na true wartość w poleceniu .create function.

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

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 wbudowanego przy użyciu szablonu usługi 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

Opinia

Dodatkowe zasoby

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 wbudowanego przy użyciu szablonu usługi 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