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

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

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

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

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

注意

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

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

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

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

注意

各クラスターには最大 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 クラスターとデータベース。クラスターとデータベースを作成します。

Security

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

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

重要

クラスターをプロビジョニングするプリンシパルは、クラスターに対する 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 テンプレートに直接指定することを前提としています。

注意

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 関数コマンドでプロパティをにtrue設定skipvalidationする必要があります。

トラブルシューティング

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

管理コマンドの概要

次の方法で共有

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

管理コマンドを使用したスクリプトの例

前提条件

Security

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

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

更新タグを省略する

Bicep スクリプト

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

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

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

制限事項

トラブルシューティング

フィードバック

その他のリソース

次の方法で共有

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

管理コマンドを使用したスクリプトの例

前提条件

Security

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

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

更新タグを省略する

Bicep スクリプト

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

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

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

制限事項

トラブルシューティング

関連コンテンツ

フィードバック

その他のリソース

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

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

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

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