Kusto クエリ言語スクリプトを使用してデータベースを構成する

Kusto クエリ言語スクリプトを実行して、Azure Resource Management (ARM) テンプレートのデプロイ中にデータベースを構成できます。 スクリプトは、1 つ以上の 管理コマンドの一覧であり、それぞれが 1 つの改行で区切られ、ARM テンプレートでアクセスされるリソースとして作成されます。

スクリプトは、次の動詞で始まるデータベース レベルの管理コマンドのみを実行できます。

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

一般に、同じ入力パラメーターで複数回呼び出された場合に追加の影響がないよう、冪等性のあるバージョンのコマンドを使用することを推奨します。 つまり、コマンドを複数回実行した場合と、1 回実行した場合とでは得られる効果が同じになります。 たとえば、可能であれば、通常の .create-or-alter コマンドよりも、べき等コマンド .create を使用することをお勧めします。

スクリプトを使用してデータベースを構成するには、さまざまな方法があります。 この記事では、ARM テンプレートのデプロイを使用する次の方法について説明します。

1. インライン スクリプト: スクリプトは、JSON ARM テンプレートのパラメーターとしてインラインで提供されます。
2. Bicep スクリプト: スクリプトは、Bicep ARM テンプレートで使用される別のファイルとして提供されます。
3. ストレージ アカウント: スクリプトは Azure ストレージ アカウントの BLOB として作成され、その詳細 (URL と 共有アクセス署名 (SaS) ARM テンプレートのパラメーターとして提供されます。

管理コマンドを含むスクリプトの例

次の例は、 MyTable と MyTable2 の 2 つのテーブルを作成するコマンドを含むスクリプトです。

.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)

2つのコマンドがべき等であるという点に注目してください。 最初に実行すると、テーブルが作成され、以降の実行では何も効果がありません。

前提条件

• Azure サブスクリプション。 無料の Azure アカウントを作成します。
• Azure Data Explorer クラスターとデータベース。 クラスターとデータベースを作成します。

セキュリティ

スクリプトのデプロイに使用されるプリンシパル (ユーザーやサービス プリンシパルなど) には、次のセキュリティ ロールが必要です。

• クラスター上の共同作成者ロール
• データベースの管理者ロール

[インライン スクリプト]

インライン パラメーターとして定義したスクリプトを使用して ARM テンプレートを作成するにはこのメソッドを使用します。 スクリプトに 1 つ以上の管理コマンドがある場合は、少なくとも 1 行でコマンドを区切ります。

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

次の設定を使用します。

更新タグを省略する

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

次の設定を使用します。

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 が既にあり、その詳細 (URL と Shared Access Signatures (SaS)) を ARM テンプレートに直接指定することを前提としています。

スクリプト リソースを作成する

最初の手順では、スクリプトを作成し、ストレージ アカウントにアップロードします。

1. データベース内のテーブルの作成に使用する管理コマンドを含む スクリプトを作成します 。

2. Azure ストレージ アカウントにスクリプトをアップロードします。 ストレージ アカウントは、Azure portal、PowerShell、または Azure CLI を使用して作成できます。

3. Shared Access Signatures (SaS) を使用して、このファイルへのアクセスを提供します。 PowerShell、Azure CLI、または .NET を使用してアクセスを提供できます。

ARM テンプレートを使用してスクリプトを実行する

このセクションでは、 Azure Resource Manager テンプレートを使用して Azure Storage に格納されているスクリプトを実行する方法について説明します。

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

次の設定を使用します。

制限事項

• スクリプトは、Azure Data Explorer でのみサポートされます。
• 同じクラスター上で 2 つのスクリプトを同時に追加、変更、削除することはできません。 この場合、次のエラーが発生します: Code="ServiceIsInMaintenance" が発生します。 この問題を回避するには、2 つのスクリプト間に依存関係を配置して、順次作成または更新されるようにします。
• スクリプトを使用してクロス クラスター クエリを使用して関数を作成するには、.create 関数コマンドで skipvalidation プロパティをtrueに設定する必要があります。
• 偽装を利用するクロス クラスター クエリとコールアウトはサポートされていません。

トラブルシューティング

スクリプト リソースによって実行されるコマンドは.show commands-and-queries コマンドの結果には表示されません。 .show journal コマンドを使用して、スクリプトの実行をトレースできます。

関連するコンテンツ

• 管理コマンドの概要