Kusto 쿼리 언어 스크립트를 사용하여 데이터베이스 구성

ARM(Azure Resource Management) 템플릿을 배포하는 동안 Kusto 쿼리 언어 스크립트를 실행하여 데이터베이스를 구성할 수 있습니다. 스크립트는 하나 이상의 관리 명령 목록으로, 각각 하나의 줄 바꿈으로 구분되며 ARM 템플릿으로 액세스되는 리소스로 만들어집니다.

스크립트는 다음 동사로 시작하는 데이터베이스 수준 관리 명령만 실행할 수 있습니다.

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

일반적으로 동일한 입력 매개 변수로 두 번 이상 호출되는 경우 추가 효과가 없도록 idempotent 버전의 명령을 사용하는 것이 좋습니다. 즉, 명령을 여러 번 실행해도 명령을 한 번 실행하는 것과 효과가 같습니다. 예를 들어, 가능하면 일반 .create-or-alter 명령보다 idempotent 명령 .create를 사용하는 것이 좋습니다.

스크립트를 사용하여 데이터베이스를 구성하는 데 사용할 수 있는 다양한 방법이 있습니다. 이 문서에서는 ARM 템플릿 배포를 사용하는 다음 방법에 중점을 줍니다.

1. 인라인 스크립트: 스크립트는 JSON ARM 템플릿에 대한 매개 변수로 인라인으로 제공됩니다.
2. Bicep 스크립트: 스크립트는 Bicep ARM 템플릿에서 사용하는 별도의 파일로 제공됩니다.
3. 스토리지 계정: 스크립트는 Azure Storage 계정에서 Blob으로 만들어지고 ARM 템플릿에 대한 매개 변수로 제공되는 세부 정보(URL 및 SaS(공유 액세스 서명))

관리 명령이 있는 예제 스크립트

다음 예제는 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)

두 명령은 idempotent입니다. 처음 실행하면 테이블을 만들고 후속 실행에서는 아무런 영향을 주지 않습니다.

필수 구성 요소

• Azure 구독 평가판 Azure 계정을 만듭니다.
• Azure Data Explorer 클러스터 및 데이터베이스. 클러스터 및 데이터베이스를 만듭니다.

보안

스크립트를 배포하는 데 사용되는 사용자 또는 서비스 주체와 같은 주체에는 다음 보안 역할이 있어야 합니다.

• 클러스터에 대한 기여자 역할
• 데이터베이스에 대한 관리자 역할

인라인 스크립트

인라인 매개 변수로 정의된 스크립트로 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": {
    }
}

다음 설정을 사용합니다.

업데이트 태그 생략

모든 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이 있고 ARM 템플릿에서 사용자가 해당 세부 정보(URL 및 SaS(공유 액세스 서명))를 직접 제공한다고 가정합니다.

스크립트 리소스 만들기

첫 번째 단계는 이 스크립트를 만들어 스토리지 계정에 업로드하는 것입니다.

1. 데이터베이스에서 테이블을 만드는 데 사용할 관리 명령 이 포함된 스크립트를 만듭니다.

2. Azure Storage 계정에 스크립트를 업로드합니다. Azure Portal, PowerShell 또는 Azure CLI를 사용하여 스토리지 계정을 만들 수 있습니다.

3. 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 데이터 탐색기 풀에서 지원되지 않습니다.
• 동일한 클러스터에서 두 개의 스크립트를 병렬로 추가, 수정 또는 제거할 수 없습니다. 이 경우 다음 오류가 Code="ServiceIsInMaintenance" 발생합니다. 순차적으로 만들거나 업데이트되도록 두 스크립트 간에 종속성을 배치하여 문제를 해결할 수 있습니다.
• 스크립트를 사용하여 클러스터 간 쿼리를 사용하여 함수를 만들려면 .create 함수 명령에서 속성을 true 설정 skipvalidation 해야 합니다.

문제 해결

스크립트 리소스에서 실행하는 명령은 .show commands-and-queries 명령의 결과에 나타나지 않습니다. .show journal 명령을 사용하여 스크립트 실행을 추적할 수 있습니다.

관련 콘텐츠

• 관리 명령 개요