共用方式為

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

  • 發行項

您可以在 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範本部署的方法：

  1. 內嵌腳本：腳本會內嵌為 JSON ARM 範本的參數。
  2. Bicep 腳本：腳本會以 Bicep ARM 範本所使用的個別檔案的形式提供。
  3. 儲存器帳戶：腳本會建立為 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)

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

必要條件

安全性

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

重要

布建叢集的主體會自動取得 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": {
    }
}

套用下列設定：

設定 Description
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
    }
}

套用下列設定：

設定 Description
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 記憶體防火牆或 虛擬網路 規則設定的記憶體帳戶載入腳本。

建立腳本資源

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

  1. 建立 文稿，其中包含 您想要用來在資料庫中建立數據表的管理命令。

  2. 將您的腳本上傳至 Azure 記憶體帳戶。 您可以使用 Azure 入口網站、PowerShell 或 Azure CLI 來建立記憶體帳戶。

  3. 使用 共用存取簽章提供此檔案的存取權， (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 Data Explorer 才支援腳本;Synapse Data Explorer 集區不支援腳本。
  • 無法在相同叢集上平行新增、修改或移除兩個指令碼。 如果發生這種情況，就會引發下列錯誤： Code="ServiceIsInMaintenance" 您可以在兩個指令碼之間放置相依性，以循序建立或更新指令碼，藉此解決問題。
  • 若要使用文稿建立具有跨叢集查詢的函式，您必須在 .create 函式命令中將 skipvalidation 屬性設定為 true 。

疑難排解

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

相關內容