使用 Kusto 查詢語言指令碼設定資料庫

發行項
11/23/2024

您可以在 Azure 資源管理（ARM）樣本部署期間執行 Kusto 查詢語言腳本來設定資料庫。腳本是一或多個管理命令的清單，每個命令都會以一個換行符分隔，並建立為使用ARM範本存取的資源。

文稿只能執行以下列動詞開頭的資料庫層級管理命令：

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

注意

支援的命令必須在資料庫層級執行。例如，您可以使用命令 .create-or-alter table來改變資料表。不支援叢集層級命令，例如 .alter cluster 原則。

一般而言，我們建議使用命令的等冪版本，如此一來，如果使用相同的輸入參數呼叫一次以上，它們就沒有額外的效果。換句話說，執行命令多次的效果與一次執行命令的效果相同。例如，在可能的情況下，建議您在一般.create命令上使用等冪命令.create-or-alter。

您可以使用各種方法來設定具有文稿的資料庫。在本文中，我們著重於使用ARM範本部署的下列方法：

內嵌腳本：腳本會以 JSON ARM 範本的參數形式內嵌提供。
Bicep 腳本：腳本會以 Bicep ARM 範本所使用的個別檔案的形式提供。
記憶體帳戶：腳本會在 Azure 記憶體帳戶中建立為 Blob，以及其詳細數據（URL 和共用存取簽章（SaS）作為 ARM 範本的參數。

注意

每個叢集最多可以有50個 Code:TooManyScripts 腳本（更多腳本會觸發錯誤。建議您在刪除現有的腳本以釋放新腳本的空間之後，將多個小型腳本合併成較少的大型腳本。刪除文稿並不會回復從該腳本執行的命令。

使用管理命令的範例腳本

下列範例是具有建立兩個數據表之命令的腳本： MyTable 和 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)

請注意，這兩個命令具有等冪性。第一次執行時，他們會在後續執行時建立數據表，不會有任何作用。

必要條件

Azure 訂用帳戶。建立免費的 Azure 帳戶。
Azure 資料總管叢集和資料庫。建立叢集和資料庫。

安全性

用來部署腳本的用戶或服務主體等主體必須具有下列安全性角色：

叢集上的參與者角色
資料庫上的管理員角色

重要

布建叢集的主體會自動取得 All Databases Admin 叢集上的角色。

內嵌指令碼

使用這個方法來建立 ARM 範本，並將腳本定義為內嵌參數。如果您的腳本有一或多個管理命令，請至少以一個換行符分隔命令。

使用ARM樣本執行內嵌腳本

下列範本示範如何使用 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": {
    }
}

使用下列設定：

設定	描述
kqlScript	內嵌 Kusto 查詢語言腳本。使用 `\n` 來新增行字元。
forceUpdateTag	唯一字串。如果已變更，則會再次套用腳本。
continueOnErrors	旗標，指出如果其中一個命令失敗，是否要繼續。預設值：false。
clusterName	腳本執行所在的叢集名稱。
databaseName	文本執行所在的資料庫名稱。
scriptName	使用外部檔案來提供腳本時，腳本的名稱。這是類型文本的實際ARM樣本資源名稱。

省略更新標籤

不建議在每個 ARM 範本部署上執行 KQL 腳本，因為它會取用叢集資源。您可以使用下列方法，防止在連續部署中執行腳稿：

指定屬性， forceUpdateTag 並在部署之間保留相同的值。
省略 forceUpdateTag 屬性，或將它保留空白，並在部署之間使用相同的腳本。

最佳做法是省略 forceUpdateTag 屬性，以便在下次部署範本時執行任何腳本變更。只有在您需要強制腳本執行時，才使用 forceUpdateTag 屬性。

Bicep 腳本

將腳本當做參數傳遞至範本可能很麻煩。 Bicep Azure Resource Manager 範本可讓您將腳本保留在個別的檔案中，並使用 loadTextContent Bicep 函式將其載入範本中。

假設文本儲存在與 Bicep 檔案位於相同資料夾中的檔案 script.kql 中，下列範本會產生與上一個範例相同的結果：

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

使用下列設定：

設定	描述
forceUpdateTag	唯一字串。如果已變更，則會再次套用腳本。
continueOnErrors	指出其中一個命令失敗時要繼續的旗標。預設值：false。
clusterName	腳本執行所在的叢集名稱。
databaseName	文本執行所在的資料庫名稱。
scriptName	使用外部檔案來提供腳本時，腳本的名稱。

Bicep 範本可以使用與 JSON ARM 樣本類似的工具來部署。例如，您可以使用下列 Azure CLI 命令來部署範本：

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

Bicep 範本會在部署之前轉譯成 JSON ARM 範本。在此範例中，腳本檔案內嵌在 JSON ARM 範本中。如需詳細資訊，請參閱 Bicep 概觀。

記憶體帳戶腳本

此方法假設您已經在 Azure 儲存體帳戶中有 Blob，而且您直接在 ARM 範本中提供其詳細數據（URL 和共用存取簽章（SaS）。

注意

腳本無法從使用 Azure 儲存體防火牆或虛擬網絡規則設定的記憶體帳戶載入。

建立腳本資源

第一個步驟是建立腳本，並將其上傳至記憶體帳戶。

建立文稿，其中包含您想要用來在資料庫中建立數據表的管理命令。
將您的腳本上傳至 Azure 儲存體帳戶。您可以使用 Azure 入口網站、PowerShell 或 Azure CLI 來建立記憶體帳戶。
使用共用存取簽章（SaS）提供此檔案的存取權。您可以使用 PowerShell、Azure CLI 或 .NET 來提供存取權。

使用ARM樣本執行腳本

在本節中，您將瞭解如何使用 Azure Resource Manager 範本執行儲存在 Azure 儲存體中的腳本。

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

使用下列設定：

設定	說明
scriptUrl	Blob 的 URL。例如，'https://myaccount.blob.core.windows.net/mycontainer/myblob'。
scriptUrlSastoken	具有共用存取簽章的字串（SaS）。
forceUpdateTag	唯一字串。如果已變更，則會再次套用腳本。
continueOnErrors	旗標，指出如果其中一個命令失敗，是否要繼續。預設值：false。
clusterName	腳本執行所在的叢集名稱。
databaseName	文本執行所在的資料庫名稱。
scriptName	使用外部檔案來提供腳本時，腳本的名稱。

限制

只有在 Azure 數據總管中才支援腳本;Synapse 數據總管集區不支援腳本。
無法在相同叢集上平行新增、修改或移除兩個指令碼。如果發生這種情況，就會引發下列錯誤： Code="ServiceIsInMaintenance" 您可以在兩個指令碼之間放置相依性，以循序建立或更新指令碼，藉此解決問題。
若要使用文稿建立具有跨叢集查詢的函式，您必須在 .create 函式命令中將屬性設定skipvalidation為 true 。

疑難排解

腳本資源執行的命令不會出現在 .show 命令和查詢命令的結果中。您可以使用 .show journal 命令來追蹤腳本執行。

管理命令概觀

共用方式為

使用 Kusto 查詢語言指令碼設定資料庫

使用管理命令的範例腳本

必要條件

安全性

內嵌指令碼

使用ARM樣本執行內嵌腳本

省略更新標籤

Bicep 腳本

記憶體帳戶腳本

建立腳本資源

使用ARM樣本執行腳本

限制

疑難排解

意見反應

其他資源

共用方式為

使用 Kusto 查詢語言指令碼設定資料庫

使用管理命令的範例腳本

必要條件

安全性

內嵌指令碼

使用ARM樣本執行內嵌腳本

省略更新標籤

Bicep 腳本

記憶體帳戶腳本

建立腳本資源

使用ARM樣本執行腳本

限制

疑難排解

相關內容

意見反應

其他資源