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

[アーティクル]
02/16/2024

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

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

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

Note

サポートされているコマンドは、データベースレベルで実行する必要があります。たとえば、コマンド .create-or-alter tableを使用してテーブルを変更できます。 .alter cluster ポリシーなどのクラスターレベルのコマンドはサポートされていません。

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

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

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

Note

各クラスターには最大 50 個のスクリプトを含めることができます (さらに多くのスクリプトを使用すると、 Code:TooManyScripts エラーが発生します)。既存のスクリプトをした後、新しいスクリプトの領域を解放するために複数の小さなスクリプトをより少ない大きなスクリプトにマージすることをお勧めします。スクリプトを削除しても、そのスクリプトから実行されたコマンドはロールバックされません。

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

次の例は、 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 クラスターとデータベース。クラスターとデータベースを作成します。

セキュリティ

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

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

重要

クラスターをプロビジョニングするプリンシパルは、クラスターに対する All Databases Admin ロールを自動的に取得します。

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

インラインパラメーターとして定義したスクリプトを使用して 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": {
    }
}

次の設定を使用します。

設定	説明
kqlScript	インラインの Kusto クエリ言語スクリプト。 `\n` を使用して、改行文字を追加します。
forceUpdateTag	一意の文字列。変更された場合は、スクリプトが再び適用されます。
continueOnErrors	コマンドのいずれかが失敗した場合に続行するかどうかを示すフラグ。既定値: false
clusterName	スクリプトが実行されるクラスターの名前。
databaseName	スクリプトを実行するデータベースの名前。
scriptName	外部ファイルを使用してスクリプトを指定する場合のスクリプトの名前。これは、型 script の実際の 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 が既にあり、その詳細 (URL と Shared Access Signatures (SaS)) を ARM テンプレートに直接指定することを前提としています。

Note

Azure Storage ファイアウォールまたは仮想ネットワークルールで構成されたストレージアカウントからスクリプトをロードすることはできません。

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

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

データベース内のテーブルの作成に使用する管理コマンドを含むスクリプトを作成します。
Azure ストレージアカウントにスクリプトをアップロードします。ストレージアカウントは、Azure portal、PowerShell、または Azure CLI を使用して作成できます。
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": {
  }
}

次の設定を使用します。

設定	説明
scriptUrl	Blob の URL。例: 'https://myaccount.blob.core.windows.net/mycontainer/myblob'。
scriptUrlSastoken	Shared access signature (SaS) を含む文字列。
forceUpdateTag	一意の文字列。変更された場合は、スクリプトが再び適用されます。
continueOnErrors	コマンドのいずれかが失敗した場合に続行するかどうかを示すフラグ。既定値: false
clusterName	スクリプトが実行されるクラスターの名前。
databaseName	スクリプトを実行するデータベースの名前。
scriptName	外部ファイルを使用してスクリプトを指定する場合のスクリプトの名前。

制限事項

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

トラブルシューティング

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

管理コマンドの概要

次の方法で共有

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

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

前提条件

セキュリティ

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

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

更新タグを省略する

Bicep スクリプト

ストレージアカウントのスクリプト

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

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

制限事項

トラブルシューティング

フィードバック

その他のリソース

次の方法で共有

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

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

前提条件

セキュリティ

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

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

更新タグを省略する

Bicep スクリプト

ストレージ アカウントのスクリプト

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

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

制限事項

トラブルシューティング

関連するコンテンツ

フィードバック

その他のリソース

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

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

ストレージアカウントのスクリプト

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