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

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

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

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

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

スクリプトを使用してデータベースを構成するには、さまざまな方法があります。 この記事では、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 クラスターとデータベース。 クラスターとデータベースを作成します。

Security

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

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

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

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

トラブルシューティング

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

関連コンテンツ

• 管理コマンドの概要