適用于 Azure Data Explorer 的 Azure DevOps 工作

Azure DevOps Services提供開發共同作業工具，例如高效能管線、免費的私人 Git 存放庫、可設定的 Kanban 面板，以及廣泛的自動化和持續測試功能。 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 資料總管叢集和資料庫。 建立叢集和資料庫。
• 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 實例擁有者，請連絡您的 擁有者 ，並要求他們加以安裝。

準備您的內容以發行

是針對工作中的叢集執行系統管理員命令的三種方式。

• 使用搜尋模式從本機代理程式資料夾取得多個命令檔案， (建置來源或發行成品)

  

• 內嵌撰寫命令

  

• 指定要直接從 git 原始檔控制取得命令檔案的檔案路徑， (建議)

  

  在 Git 存放庫中建立下列範例資料夾， (Functions、 Policies、 Tables) 。 將檔案從 此處 複製到個別的資料夾，如下所示，並認可變更。 系統會提供範例檔案來執行下列工作流程。

  

  提示

  建立您自己的工作流程時，建議您讓程式碼具有等冪性。 例如，使用 .create-merge table 而非 .create table ，並使用 函式，而不是 .create 函 .create-or-alter 式。

建立發行管線

1. 登入您的 Azure DevOps 組織。

2. 從左側功能表中選取 [管線>發行]，然後選取 [新增管線]。

   

3. [ 新增發行管線 ] 視窗隨即開啟。 在 [ 管線] 索引 標籤的 [ 選取範本 ] 窗格中，選取 [空白作業]。

   

4. 選取 [階段] 按鈕。 在 [階段] 窗格中，新增 [階段名稱]。 選取 [ 儲存 ] 以儲存管線。

   

5. 選取 [新增成品] 按鈕。 在 [ 新增成品] 窗格中，選取程式碼所在的存放庫、填寫相關資訊，然後按一下 [ 新增]。 選取 [ 儲存 ] 以儲存管線。

   

6. 在 [ 變數] 索引 標籤中，選取 [+ 新增 ] 來建立要用於工作的 端點 URL 變數。 寫入端點的名稱和值。 選取 [ 儲存 ] 以儲存管線。

   

   若要尋找您的Endpoint_URL，Azure 入口網站中 Azure Data Explorer 叢集的概觀頁面包含 Azure Data Explorer 叢集 URI。 以下列格式 https://<Azure Data Explorer cluster URI>?DatabaseName=<DBName> 建構 URI。 例如，https://kustodocs.westus.kusto.windows.net?DatabaseName=SampleDB

   

建立工作以部署資料夾

1. 在 [ 管線 ] 索引標籤中，按一下 1 個作業，0 個工作以新增工作。

   

2. 重複下列步驟來建立命令工作，以從 [資料表]、 [函式] 和 [ 原則 ] 資料夾部署檔案：

   

   1. 在 [工作]索引標籤中，依[代理程式作業] 選取 + 並搜尋Azure Data Explorer。

   2. 在[執行 Azure Data Explorer 命令]底下，選取 [新增]。

   3. 選取 [Kusto 命令 ]，並使用下列資訊更新工作：

      • 顯示名稱：工作的名稱。 例如， Deploy <FOLDER> 其中 <FOLDER> 是您要建立之部署工作的資料夾名稱。

      • 檔案路徑：針對每個資料夾，將路徑指定為 */<FOLDER>/*.csl 工作的相關資料夾。 <FOLDER>

      • 端點 URL：指定在上一個步驟中建立的 EndPoint URL 變數。

      • 使用服務端點：選取此選項。

      • 服務端點：選取現有的服務端點或建立新的服務端點， (+ 新增) 在 [新增 Azure Data Explorer服務連線] 視窗中提供下列資訊：

        設定	建議的值
        連線名稱	輸入名稱以識別此服務端點
        叢集 URL	您可以在 Azure Data Explorer 叢集的概觀一節中找到Azure 入口網站
        服務主體識別碼	輸入Microsoft Entra應用程式識別碼 (建立為必要條件)
        服務主體應用程式金鑰	輸入Microsoft Entra應用程式金鑰 (建立為必要條件)
        Microsoft Entra租使用者識別碼	輸入您的Microsoft Entra租使用者 (，例如 microsoft.com 或 contoso.com)

      選取 [允許所有管線使用此連線 ] 核取方塊，然後選取 [ 確定]。

      

3. 選取 [ 儲存 ]，然後在 [ 工作 ] 索引標籤中，確認有三項工作： 部署資料表、 部署函式和 部署原則。

   

建立查詢工作

如有需要，請建立工作以針對叢集執行查詢。 在組建或發行管線中執行查詢可用來驗證資料集，並根據查詢結果執行步驟成功或失敗。 工作成功準則可以根據資料列計數閾值或單一值，視查詢傳回的內容而定。

1. 在 [工作]索引標籤中，依[代理程式作業] 選取 + 並搜尋Azure Data Explorer。

2. 在[執行 Azure Data Explorer查詢] 底下，選取 [新增]。

3. 選取 [Kusto 查詢 ]，並使用下列資訊更新工作：

   • 顯示名稱：工作的名稱。 例如， 查詢叢集。
   • 類型：選取 [內嵌]。
   • 查詢：輸入您要執行的查詢。
   • 端點 URL：指定稍早建立的 EndPoint URL 變數。
   • 使用服務端點：選取此選項。
   • 服務端點：選取服務端點。

   

4. 在 [工作結果] 底下，根據查詢的結果選取工作的成功準則，如下所示：

   • 如果您的查詢傳回資料列，請選取 [ 資料列計數 ]，並提供您需要的準則。

     

   • 如果您的查詢傳回值，請選取 [單一值 ]，並提供預期的結果。

     

建立查詢伺服器閘道工作

如有需要，請建立工作以針對叢集執行查詢，並網關發行進度擱置的查詢結果資料列計數。 伺服器查詢閘道工作是無代理程式作業，這表示查詢會直接在Azure DevOps Server上執行。

1. 在 [工作]索引標籤中，依無代理程式作業選取 + 並搜尋Azure Data Explorer。

2. 在[執行 Azure Data Explorer查詢伺服器閘道] 底下，選取 [新增]。

3. 選取 [Kusto 查詢伺服器閘道 ]，然後選取 [ 伺服器閘道測試]。

   

4. 設定提供下列資訊的工作：

   • 顯示名稱：閘道的名稱。
   • 服務端點：選取服務端點。
   • 資料庫名稱：指定資料庫名稱。
   • 類型：選取 [內嵌查詢]。
   • 查詢：輸入您要執行的查詢。
   • 閾值上限：指定查詢成功準則的資料列計數上限。

   

注意

您應該會在執行版本時看到如下的結果。

執行版本

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