Azure Data Explorer の Azure DevOps タスク

[アーティクル]
07/23/2024

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

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 インスタンスの所有者である場合は、Marketplace から拡張機能をインストールします。それ以外の場合は、Azure DevOps インスタンスの所有者に問い合わせてインストールを依頼してください。

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

次の方法を使用して、タスク内のクラスターに対して管理者コマンドを実行できます。

コマンドのソース管理オプションを示すスクリーンショット。

検索パターンを使用して、ローカルエージェントフォルダーから複数のコマンドファイルを取得します (ビルドソースまたはリリース成果物)
コマンドをインラインで記述します
Git ソース管理からコマンドファイルを直接取得するファイルパスを指定します (推奨)

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

ヒント

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

リリースパイプラインの作成

Azure DevOps 組織にサインインします。
左側のメニューから [パイプライン]>、[リリース] の順に選択し、[新しいパイプライン] を選択します。
[新しいリリースパイプライン] ウィンドウが開きます。 [パイプライン] タブの [テンプレートの選択] ウィンドウで [空のジョブ] を選択します。
[ステージ] ボタンを選択します。 [ステージ] ウィンドウで [ステージ名] を追加します。保存を選択して、パイプラインを保存します。
[成果物の追加] ボタンを選択します。 [成果物の追加] ペイン内で、コードが存在するリポジトリを選択し、関連情報を入力して、[追加] を選択します。保存を選択して、パイプラインを保存します。
[変数] タブ内で [+ 追加] を選択し、タスク内で使用される [エンドポイント URL] の変数を作成します。エンドポイントの [名前] と [値] を書きます。保存を選択して、パイプラインを保存します。

エンドポイント URL を見つけるには、Azure portal 内で Azure Data Explorer クラスターの [概要] ページに移動し、クラスター URI をコピーします。変数 URI は https://<ClusterURI>?DatabaseName=<DBName> の形式で作成します。たとえば、https://kustodocs.westus.kusto.windows.net?DatabaseName=SampleDB のように指定します。

フォルダーを展開するタスクを作成する

[パイプライン] タブ内で、[1 個のジョブ、0 個のタスク] を選択し、タスクを追加します。

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

Azure Data Explorer 管理者コマンドを追加する方法を示すスクリーンショット。

[タスク] タブで、[エージェントジョブ] の横の + を選択し、Azure Data Explorer を検索します。
[Run Azure Data Explorer Command]\(Azure Data Explorer コマンドの実行\) の [追加] を選択します。

[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 サービス接続の追加\) ウィンドウに次の情報を入力します。

設定	提案された値
認証方法	フェデレーション ID 資格情報 (FIC) を設定する (推奨)、またはサービスプリンシパル認証 (SPA) を選択します。
接続名	このサービスエンドポイントを識別する名前を入力します
クラスター URL	値は、Azure portal の Azure Data Explorer クラスターの概要セクションにあります
サービスプリンシパル ID	Microsoft Entra アプリ ID (前提条件として作成) を入力します
サービスプリンシパルアプリのキー	Microsoft Entra アプリキー (前提条件として作成) を入力します
Microsoft Entra テナント ID	Microsoft Entra テナント (microsoft.com や contoso.com など) を入力します

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

サービス接続を追加する方法を示すスクリーンショット。

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

クエリタスクを作成する

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

[タスク] タブで、[エージェントジョブ] の横の + を選択し、Azure Data Explorer を検索します。
[Run Azure Data Explorer Query]\(Azure Data Explorer クエリの実行\) の [追加] を選択します。
[Kusto Query]\(Kusto クエリ\) を選択し、次の情報でタスクを更新します。
- 表示名: タスクの名前。たとえば、「Query cluster」にします。
- 種類: [Inline]\(インライン\) を選択します。
- クエリ: 実行するクエリを入力します。
- エンドポイント URL: 前に作成した EndPoint URL 変数を指定します。
- Use Service Endpoint (サービスエンドポイントを使用する): このオプションを選択します。
- Service Endpoint (サービスエンドポイント): サービスエンドポイントを選択します。
[タスクの結果] で、次のようにクエリの結果に基づいてタスクの成功条件を選択します。
- クエリから行が返される場合は、[行数] を選択し、必要な条件を指定します。
- クエリから値が返される場合は、[単一値] を選択し、期待される結果を指定します。

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

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

[タスク] タブで、[エージェントレスジョブ] の横の + を選択し、Azure Data Explorer を検索します。
[Run Azure Data Explorer Query Server Gate]\(Azure Data Explorer クエリサーバーゲートの実行\) の [追加] を選択します。
[Kusto Query Server Gate]\(Kusto クエリサーバーゲート\) を選択し、[Server Gate Test]\(サーバーゲートテスト\) を選択します。
次の情報を入力してタスクを構成します。
- 表示名: ゲートの名前。
- Service Endpoint (サービスエンドポイント): サービスエンドポイントを選択します。
- データベース名: データベース名を指定します。
- 種類: [Inline query]\(インラインクエリ\) を選択します。
- クエリ: 実行するクエリを入力します。
- [Maximum threshold]\(最大しきい値\): クエリの成功条件となる最大行数を指定します。

Note

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

クエリゲートタスクの結果の例を示すスクリーンショット。

リリースを実行する

[+ リリース]>、[リリースの作成] の順に選択し、リリースを作成します。
[ログ] タブで、デプロイ状態が成功であることを確認します。

これで、運用前の展開用リリースパイプラインの作成が完了しました。

Azure Data Explorer DevOps タスクのキーレス認証のサポート

この拡張機能では、Azure Data Explorer クラスターのキーレス認証がサポートされています。キーレス認証を使用すると、キーを使用せずに Azure Data Explorer クラスターに対して認証することができます。また、キーを使用するよりも安全で管理が簡単です。

Azure Data Explorer サービス接続内でフェデレーション ID 資格情報 (FIC) 認証を使用する

DevOps インスタンス内で、[プロジェクト設定]>[サービス接続]>[新しいサービス接続]>[Azure Data Explorer] に移動します。
[フェデレーション ID 資格情報] を選択し、クラスターの URL、サービスプリンシパル ID、テナント ID、サービス接続名を入力し、[保存] を選択します。
Azure portal 内で、Microsoft Entra アプリを開いて指定したサービスプリンシパルを表示します。
[証明書とシークレット] の下で、[フェデレーション資格情報] を選択します。
[資格情報の追加] を選択してから [フェデレーション資格情報のシナリオ] の [その他の発行者] を選択し、次の情報を使用して設定を入力します。
- [発行者]: <https://vstoken.dev.azure.com/{System.CollectionId}>。この {System.CollectionId} は Azure DevOps 組織のコレクション ID です。コレクション ID は、次の方法で確認できます。
  - Azure DevOps クラシックリリースパイプライン内で、[ジョブの初期化] を選択します。ログの中にコレクション ID が表示されます。
- [サブジェクト識別子]: <sc://{DevOps_Org_name}/{Project_Name}/{Service_Connection_Name}>。この {DevOps_Org_name} は Azure DevOps 組織名、{Project_Name} はプロジェクト名、{Service_Connection_Name} は前に作成したサービス接続名です。
  
  Note
  
  サービス接続名にスペースがある場合は、フィールド内でスペースを使用できます。 (例: sc://MyOrg/MyProject/My Service Connection)。
- [名前]: 資格情報の名前を入力します。
[追加] を選択します。

Azure Resource Manager (ARM) サービス接続内でフェデレーション ID 資格情報またはマネージド ID を使用する

DevOps インスタンス内で、[プロジェクト設定]>[サービス接続]>[新しいサービス接続]>[Azure Resource Manager] に移動します。
[認証方法] の下で、 [ワークロード ID フェデレーション (自動)] を選択します。または、手動の [ワークロード ID フェデレーション (手動)] オプションを使用してワークロード ID フェデレーションの詳細を指定するか、[マネージド ID] オプションを使用できます。 Azure Resource Management を使用したマネージド ID の設定の詳細については、Azure Resource Manager (ARM) サービス接続を参照してください。
必要な詳細を入力し、[検証] を選択してから、[保存] を選択します。

Yaml パイプラインの構成

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

管理者コマンドの使用例

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

クエリの使用例

steps:
- task: Azure-Kusto.PublishToADX.ADXQuery.ADXQuery@4
  displayName: '<Task Display Name>'
  inputs:
    targetType: 'inline'
    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>'
    authType: 'kustoserviceconn'
    connectedServiceName: '<connection service name>'
    minThreshold: '0'
    maxThreshold: '10'
  continueOnError: true

次の方法で共有

Azure Data Explorer の Azure DevOps タスク

前提条件

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