Azure Data Explorer の Azure DevOps タスク

Azure DevOps Services は、高性能パイプライン、無料のプライベート Git リポジトリ、構成可能なかんばんボード、広範囲で自動化された継続的テスト機能など、開発向け共同作業ツールを提供します。 Azure Pipelines は Azure DevOps の機能であり、あらゆる言語、プラットフォーム、クラウドと連動する高性能パイプラインでコードをデプロイするよう、CI/CD を管理できます。 Azure Data Explorer - Pipeline Tools は Azure Pipelines のタスクであり、リリース パイプラインを作成し、データベースの変更を Azure Data Explorer データベースにデプロイできます。 Visual Studio Marketplace から無料で入手できます。 この拡張機能には、次の 3 つの基本的なタスクが含まれています。

• Azure Data Explorer コマンド - Azure Data Explorer クラスターに対して管理コマンドを実行する

• Azure Data Explorer クエリ - Azure Data Explorer クラスターに対してクエリを実行し、結果を解析する

• Azure Data Explorer クエリ サーバー ゲート - クエリの結果に応じてリリースをゲートするエージェントレス タスク

  

このドキュメントでは、Azure Data Explorer – Pipeline Tools タスクを使用し、スキーマの変更をデータベースにデプロイする簡単な例について説明します。 完全な CI/CD パイプラインについては、Azure DevOps ドキュメントを参照してください。

前提条件

• Azure サブスクリプション。 無料の Azure アカウントを作成します。
• Azure Data Explorer クラスターとデータベース。 クラスターとデータベースを作成します。
• Azure Data Explorer クラスターのセットアップ:
  • Microsoft Entra アプリケーションMicrosoft Entraプロビジョニングしてアプリを作成します。
  • Azure Data Explorer データベースのアクセス許可を管理して、Azure Data Explorer データベース上のMicrosoft Entra アプリへのアクセス権を付与します。
• Azure DevOps セットアップ:
  • 無料組織の新規登録。
  • 組織の作成。
  • Azure DevOps でのプロジェクトの作成。
  • Git を使用したコード。
• 拡張機能のインストール
  • Azure DevOps インスタンス所有者の場合は、Marketplace から拡張機能をインストールします。
  • Azure DevOps インスタンス所有者でない場合は、所有者に問い合わせ、インストールを依頼してください。

リリース用にコンテンツを準備する

タスクでクラスターに対して管理コマンドを実行するには 3 つの方法があります。

• 検索パターンを使用して、ローカル エージェント フォルダーから複数のコマンド ファイルを取得します (ビルド ソースまたはリリース成果物)

  

• コマンドをインラインで記述します

  

• Git ソース管理からコマンド ファイルを直接取得するファイル パスを指定します (推奨)

  

  Git リポジトリでサンプル フォルダー (Functions、Policies、Tables) を作成します。 下の画像のようにここから個々のフォルダーにファイルをコピーし、変更内容をコミットします。 次のワークフローを実行するためのサンプル ファイルが提供されます。

  

  ヒント

  独自のワークフローを作成するとき、コードをべき等にすることをお勧めします。 たとえば、.create tableの代わりに .create-merge table を使用し、.create関数の代わりに .create-or-alter 関数を使用します。

リリース パイプラインを作成する

1. Azure DevOps 組織にサインインします。

2. 左側のメニューから [パイプライン]>、 [リリース] の順に選択し、 [新しいパイプライン] を選択します。

   

3. [新しいリリース パイプライン] ウィンドウが開きます。 [パイプライン] タブの [テンプレートの選択] ウィンドウで [空のジョブ] を選択します。

   

4. [ステージ] ボタンを選択します。 [ステージ] ウィンドウで [ステージ名] を追加します。 [保存] を選択し、パイプラインを保存します。

   

5. [成果物の追加] ボタンを選択します。 [成果物の追加] ウィンドウで、コードが存在するリポジトリを選択し、関連情報を入力し、 [追加] をクリックします。 [保存] を選択し、パイプラインを保存します。

   

6. [変数] タブで [+ 追加] を選択し、タスクで使用される [エンドポイント URL] の変数を作成します。 エンドポイントの [名前] と [値] を書きます。 [保存] を選択し、パイプラインを保存します。

   

   Azure portal の Azure Data Explorer クラスターの概要ページに Azure Data Explorer クラスター URI が含まれています。自分のエンドポイント URL はそこで見つかります。 URI は形式 https://<Azure Data Explorer cluster URI>?DatabaseName=<DBName> で構築します。 たとえば、https://kustodocs.westus.kusto.windows.net?DatabaseName=SampleDB のように指定します。

   

フォルダーをデプロイするタスクを作成する

1. [パイプライン] タブで、 [1 ジョブ、0 タスク] をクリックし、タスクを追加します。

   

2. 次の手順を繰り返して、テーブル、関数、およびポリシーの各フォルダーからファイルをデプロイするコマンド タスクを作成します。

   

   1. [タスク] タブで、[エージェント ジョブ] の横の + を選択し、Azure Data Explorer を検索します。

   2. [Run Azure Data Explorer Command](Azure Data Explorer コマンドの実行) の [追加] を選択します。

   3. [Kusto Command](Kusto コマンド) を選択し、次の情報でタスクを更新します。

      • 表示名: タスクの名前。 たとえば、 Deploy <FOLDER> とします。ここで、<FOLDER> は作成するデプロイ タスクのフォルダーの名前です。

      • ファイル パス: 各フォルダーのパスを */<FOLDER>/*.csl として指定します。ここで、<FOLDER> はタスクの関連するフォルダーです。

      • エンドポイント URL: 前の手順で作成した EndPoint URL 変数を指定します。

      • Use Service Endpoint (サービス エンドポイントを使用する) : このオプションを選択します。

      • Service Endpoint (サービス エンドポイント) : 既存のサービスエンドポイントを選択するか、新しいものを作成し ( [+ 新規] )、 [Add Azure Data Explorer service connection](Azure Data Explorer サービス接続の追加) ウィンドウに次の情報を入力します。

        設定	推奨値
        接続名	このサービス エンドポイントを識別する名前を入力します
        クラスター URL	値は、Azure portal の Azure Data Explorer クラスターの概要セクションにあります
        サービス プリンシパル ID	Microsoft Entra アプリ ID (前提条件として作成) を入力します
        サービス プリンシパル アプリのキー	Microsoft Entra アプリ キーを入力します (前提条件として作成)
        Microsoft Entra テナント ID	Microsoft Entra テナント (microsoft.com や contoso.com など) を入力します

      [この接続の使用をすべてのパイプラインに許可します] チェックボックスを選択し、 [OK] を選択します。

      

3. [保存] を選択し、 [タスク] タブで、 [Deploy Tables](テーブルのデプロイ) 、 [Deploy Functions](関数のデプロイ) 、 [Deploy Policies](ポリシーのデプロイ) の 3 つのタスクがあることを確認します。

   

クエリ タスクを作成する

必要に応じて、クラスターに対してクエリを実行するタスクを作成します。 Build または Release パイプラインでクエリを実行すると、データセットを検証し、クエリ結果に基づいてステップを成功または失敗させることができます。 タスクの成功条件は、クエリによって返される内容に応じて、行数のしきい値または 1 つの値に基づくことができます。

1. [タスク] タブで、[エージェント ジョブ] の横の + を選択し、Azure Data Explorer を検索します。

2. [Run Azure Data Explorer Query](Azure Data Explorer クエリの実行) の [追加] を選択します。

3. [Kusto Query](Kusto クエリ) を選択し、次の情報でタスクを更新します。

   • 表示名: タスクの名前。 たとえば、「Query cluster」にします。
   • 種類: [Inline](インライン) を選択します。
   • クエリ: 実行するクエリを入力します。
   • エンドポイント URL: 前に作成した EndPoint URL 変数を指定します。
   • Use Service Endpoint (サービス エンドポイントを使用する) : このオプションを選択します。
   • Service Endpoint (サービス エンドポイント) : サービス エンドポイントを選択します。

   

4. [タスクの結果] で、次のようにクエリの結果に基づいてタスクの成功条件を選択します。

   • クエリから行が返される場合は、 [行数] を選択 し、必要な条件を指定します。

     

   • クエリから値が返される場合は、 [単一値] を選択し、期待される結果を指定します。

     

クエリ サーバー ゲート タスクを作成する

必要に応じて、クラスターに対してクエリを実行するタスクを作成し、クエリ結果の行数に応じてリリースの進行状況を制限します。 サーバー クエリ ゲート タスクはエージェントレス ジョブです。つまり、クエリは Azure DevOps Server 上で直接実行されます。

1. [タスク] タブで、[エージェントレス ジョブ] の横の + を選択し、Azure Data Explorer を検索します。

2. [Run Azure Data Explorer Query Server Gate](Azure Data Explorer クエリ サーバー ゲートの実行) の [追加] を選択します。

3. [Kusto Query Server Gate](Kusto クエリ サーバー ゲート) を選択し、 [Server Gate Test](サーバー ゲート テスト) を選択します。

   

4. 次の情報を入力してタスクを構成します。

   • 表示名: ゲートの名前。
   • Service Endpoint (サービス エンドポイント) : サービス エンドポイントを選択します。
   • データベース名: データベース名を指定します。
   • 種類: [Inline query](インライン クエリ) を選択します。
   • クエリ: 実行するクエリを入力します。
   • [Maximum threshold](最大しきい値) : クエリの成功条件となる最大行数を指定します。

   

注意

リリースを実行すると、次のような結果が表示されます。

リリースを実行する

1. [+ リリース]>、 [リリースの作成] の順に選択し、リリースを作成します。

   

2. [ログ] タブで、デプロイ状態が成功であることを確認します。

   

これで、実稼働前環境にデプロイするためのリリース パイプラインを作成できました。

Yaml パイプラインの構成

タスクは、Azure DevOps Web UI (上に示すように) とパイプライン スキーマ内の Yaml コードの両方を使用して構成できます。

管理コマンドの使用例

steps:
- task: Azure-Kusto.PublishToADX.PublishToADX.PublishToADX@1
  displayName: '<Task Name>'
  inputs:
    script: '<inline Script>'
    waitForOperation: true
    kustoUrls: '$(CONNECTIONSTRING):443?DatabaseName=""'
    customAuth: true
    connectedServiceName: '<Service Endpoint Name>'
    serialDelay: 1000
  continueOnError: true
  condition: ne(variables['ProductVersion'], '') ## Custom condition Sample

クエリの使用例

steps:
- task: Azure-Kusto.PublishToADX.ADXQuery.ADXQuery@1
  displayName: '<Task Display Name>'
  inputs:
    script: |  
     let badVer=
     RunnersLogs | where Timestamp > ago(30m)
         | where EventText startswith "$$runnerresult" and Source has "ShowDiagnostics"
         | extend State = extract(@"Status='(.*)', Duration.*",1, EventText)
         | where State == "Unhealthy"
         | extend Reason = extract(@'"NotHealthyReason":"(.*)","IsAttentionRequired.*',1, EventText)
         | extend Cluster = extract(@'Kusto.(Engine|DM|CM|ArmResourceProvider).(.*).ShowDiagnostics',2, Source)
         | where Reason != "Merge success rate past 60min is < 90%"
         | where Reason != "Ingestion success rate past 5min is < 90%"
         | where Reason != "Ingestion success rate past 5min is < 90%, Merge success rate past 60min is < 90%"
         | where isnotempty(Cluster)
         | summarize max(Timestamp) by Cluster,Reason 
         | order by  max_Timestamp desc      
         | where Reason startswith "Differe"
         | summarize by Cluster
     ;   
      DimClusters | where Cluster in (badVer)
     | summarize by Cluster , CmConnectionString , ServiceConnectionString ,DeploymentRing
     | extend ServiceConnectionString = strcat("#connect ", ServiceConnectionString)
     | where DeploymentRing == "$(DeploymentRing)"
    kustoUrls: 'https://<ClusterName>.kusto.windows.net?DatabaseName=<DataBaneName>'
    customAuth: true
    connectedServiceName: '<Service Endpoint Name>'
  continueOnError: true