適用於 Azure 資料瀏覽器的 Azure DevOps 任務

Azure DevOps Services 提供開發共同作業工具，例如高效能管線、免費的私人 Git 存放庫、可設定的工作流程看板，以及廣泛的自動化和持續測試功能。 Azure Pipelines 是 Azure DevOps 功能，可讓您管理 CI/CD，以使用任何語言、平台和雲端的高效能管線來部署程序代碼。 Azure 數據總管 - 管線工具 是 Azure Pipelines 工作，可讓您建立發行管線，並將資料庫變更部署至 Azure 數據總管資料庫。 它可在 Visual Studio Marketplace 中免費取得。 擴充套件包括下列基本任務：

• Azure 資料總管命令 - 針對 Azure 資料總管叢集執行系統管理命令

• Azure 資料總管查詢 - 針對 Azure 資料總管叢集執行查詢，並剖析結果

• Azure 資料總管查詢伺服器閘道操作 - 無代理任務，根據查詢結果控管發行

  

本檔說明使用 Azure 資料總管 - 管線工具 工作將結構描述變更部署至資料庫的簡單範例。 如需完整的 CI/CD 管線，請參閱 Azure DevOps 檔。

必要條件

• Azure 訂用帳戶。 建立免費的 Azure 帳戶。
• Azure 資料總管叢集和資料庫。 建立叢集和資料庫。
• Azure 數據總管叢集設定：
  • 藉由配置 Microsoft Entra 應用程式，建立 Microsoft Entra 應用程式。
  • 藉由管理 Azure 數據總管資料庫許可權，授與 Azure 數據總管資料庫上Microsoft Entra 應用程式的存取權。
• Azure DevOps 設定：
  • 註冊免費組織。
  • 建立組織。
  • 在 Azure DevOps 中建立專案。
  • 使用 Git 編寫程式碼。
• 延伸模組安裝：

  • 如果您是 Azure DevOps 實例擁有者，請從 Marketplace 安裝擴充功能，否則請連絡您的 Azure DevOps 實例 擁有者 ，並要求他們加以安裝。

    

    

準備您的內容以供發布

您可以使用下列方法，針對工作內的叢集執行系統管理員命令：

• 使用搜尋模式，從本端代理程式資料夾取得多個命令檔案 （建置來源或發行構件）。 單行選項支援多個檔案，每個檔案只需一個指令。

  

• 在行內撰寫命令。

  

• 指定檔案路徑，以直接從 Git 原始檔控制取得命令檔案 （建議） 。

  

  在您的 Git 存放庫中建立下列範例資料夾（Functions、Policies、Tables）。 將檔案從 範例存放庫 複製到相應的資料夾中，然後認可變更。 系統會提供範例檔案來執行下列工作流程。

  

  提示

  在建立您自己的工作流程時，建議使您的程式碼具等冪性。 例如，使用 .create-merge table 代替 .create table，並使用 函數 .create-or-alter 代替函數 .create 。

建立發行管線

1. 登入您的 Azure DevOps 組織。

2. 從左側功能表中選取 管道發佈，然後選取 新增管道。

   

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

   

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

   

5. 選取 [ 新增成品 ] 按鈕。 在 [ 新增成品 ] 窗格中，選取程序代碼所在的存放庫、填寫相關信息，然後選取 [ 新增]。 選取 [ 儲存] 以儲存您的管線。

   

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

   

   若要尋找您的端點 URL，請移至 Azure 入口網站 中 Azure 數據總管叢集的概觀頁面，並複製叢集 URI。 以下列格式 https://<ClusterURI>?DatabaseName=<DBName>建構變數 URI。 例如，https://kustodocs.westus.kusto.windows.net?DatabaseName=SampleDB

   

創建一個用於部署資料夾的任務

1. 在 [管道] 索引標籤中，選取 1 個作業、0 個任務 來新增任務。

   

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

   

   1. 在 任務 索引標籤中，按 + 篩選並搜尋 Azure 數據總管。

   2. 在 [執行 Azure 數據總管命令] 底下，選取 [新增]。

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

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

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

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

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

      • 服務端點：選取現有的服務端點，或在 [新增 Azure 數據總管服務連線] 視窗中建立新的服務端點，並提供下列資訊：

        設定	建議的值
        驗證方法	設定聯邦身份認證憑證（FIC）（建議），或選取服務主體認證（SPA）。
        連線名稱	輸入名稱以識別此服務端點
        叢集 URL	您可以在 Azure 入口網站的 Azure 數據資源管理器叢集的概觀區段中找到數值。
        服務主體標識碼	輸入 Microsoft Entra 應用程式識別碼（此識別碼已事先建立為必要條件）
        服務主體應用程式金鑰	輸入 Microsoft Entra 應用程式金鑰（作為作業的前置條件而建立）
        Microsoft Entra 租戶標識符	輸入您的 Microsoft Entra 租戶（例如 microsoft.com 或 contoso.com）

      選取 [ 允許所有管線使用此聯機 ] 複選框，然後選取 [ 確定]。

      

   4. 如果你的管理員指令是長時間執行的非同步操作，請選擇「 等待長非同步管理員指令以完成 」的勾選框。 啟用後，任務會使用 .show operations 輪詢操作狀態，直到指令完成為止。

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

   

建立查詢工作

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

1. 在 [工作] 索引標籤中，依 [代理程序作業] 選取+並搜尋 Azure 數據總管。

2. 在 [執行 Azure 數據總管查詢] 底下，選取 [新增]。

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

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

   

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

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

     

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

     

建立查詢伺服器閘道任務

如有必要，請建立一個任務，以對叢集執行查詢，並根據查詢結果的行數來控制發行進度。 伺服器查詢閘道工作是無代理程式作業，這表示查詢會直接在 Azure DevOps Server 上執行。

1. 在 工作 索引標籤中，選取 無代理程式工作 並搜尋 Azure 數據總管。

2. 在 執行 Azure 數據總管查詢伺服器閘道 下，選取 新增。

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

   

4. 請依照下列資訊設定任務：

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

   

注意

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

執行發佈版本

1. 選取 + 發行>建立發行 以啟動發行。

   

2. 在 [ 記錄] 索引標籤中，檢查部署狀態是否成功。

   

現在已經完成用於部署至預發環境的發行管線的建立。

Azure Data Explorer DevOps 工作的無密鑰驗證支援

此延伸模組支援 Azure 資料總管叢集的無金鑰驗證。 無金鑰驗證可讓您向 Azure 資料總管叢集進行驗證，而不需要使用金鑰。 它更安全、更易於管理。

注意

Kusto Fabric 叢集的 URL 不支援工作負載身份聯盟（WIF）及管理身份驗證。

在 Azure 數據總管服務連線中使用同盟身分識別認證 （FIC） 驗證

注意

從擴充版 4.0.x 開始，Azure 資料總管服務端點除了支援服務主體認證外，還支援工作負載身份聯盟（WIF）認證。

1. 在您的 DevOps 實例中，移至 項目設定>服務連接>新增服務連接>Azure Data Explorer。

2. 選取 [同盟身分識別認證]，然後輸入您的叢集 URL、服務主體標識碼、租使用者標識碼、服務連線名稱，然後選取 [ 儲存]。

3. 在 Azure 入口網站 中，開啟指定服務主體的 Microsoft Entra 應用程式。

4. 在 憑證與秘密 下，選取 聯邦憑證。

   

5. 選取 [新增認證 ]，然後針對 [同盟認證案例]，選取 [其他簽發者]，然後使用下列資訊填寫設定：

   • 簽發者： <https://vstoken.dev.azure.com/{System.CollectionId}> 其中 {System.CollectionId} 是 Azure DevOps 組織的集合標識碼。 您可以透過下列方式找到集合識別碼：

     • 在 Azure DevOps 傳統發行管線中，選取 [ 初始化作業]。 集合 ID 顯示在記錄中。

   • 主體標識碼： <sc://{DevOps_Org_name}/{Project_Name}/{Service_Connection_Name}> 其中 {DevOps_Org_name} 是 Azure DevOps 組織名稱、 {Project_Name} 專案名稱，而 {Service_Connection_Name} 是您稍早建立的服務連線名稱。

     注意

     如果您的服務連線名稱中有空格，您可以將其與欄位中的空格一起使用。 例如： sc://MyOrg/MyProject/My Service Connection 。

   • 名稱：輸入認證的名稱。

   

6. 選取 [新增]。

在 Azure Resource Manager (ARM) 服務連線中使用聯邦身份驗證憑證或受管理的身分識別

1. 在您的 DevOps 實例中，移至 專案設定>服務連線>新增服務連線>Azure 資源管理器。

   

2. 在 「驗證方法」下、選取「 工作負載身分識別聯合（自動） 」以繼續。 您也可以使用手動 工作負載身分識別同盟 （手動） 選項來指定工作負載身分識別同盟詳細資料或 受控識別 選項。 深入瞭解如何在 Azure Resource Manager （ARM） 服務連線中使用 Azure 資源管理來設定受控識別。

   

3. 填寫必要的詳細數據，選取 [驗證]，然後選取 [ 儲存]。

YAML 管線配置

您可以使用 管線架構內的 Azure DevOps Web UI 或 YAML 程式碼來設定工作。

擴充提供三個管線任務，皆可透過 YAML 存取：

• Azure Data Explorer Command （ADXAdminCommand@5） — 對 ADX 叢集執行 admin/control 命令
• Azure Data Explorer Query — 對 ADX 叢集執行查詢並解析結果
• Azure Data Explorer Query Server Gate — 根據查詢結果進行無代理的任務來管控釋出

提示

為了增強安全性，建議透過 Azure Resource Manager 服務連線使用 工作負載身份聯盟（Workload Identity Federation ）或 管理身份驗證（Managed Identity Authentication ），而不是直接將憑證儲存在管線中。 這些無金鑰認證方法是推薦的最佳實務。

管理命令範例 — 內嵌命令

以下範例使用支援工作負載身份聯盟（WIF）及受管理身份驗證的 Azure 資源管理器（ARM）服務連線執行內嵌管理指令：

steps:
- task: Azure-Kusto.ADXAdminCommands.PublishToADX.ADXAdminCommand@5
  displayName: 'Run inline ADX admin command'
  inputs:
    clusterUri: 'https://<ClusterName>.<Region>.kusto.windows.net'
    databaseName: '<DatabaseName>'
    commandsSource: 'inline'
    inlineCommands: |
      .create-merge table MyTable (Id:int, Name:string, Timestamp:datetime)
      .create-or-alter function MyFunction() { MyTable | take 10 }
    azureSubscription: '<ARM Service Connection Name>'
  continueOnError: true

管理員指令範例 — 基於檔案的指令

以下範例是從符合 glob 模式的檔案中執行管理指令，使用 AAD 應用註冊驗證。

steps:
- task: Azure-Kusto.ADXAdminCommands.PublishToADX.ADXAdminCommand@5
  displayName: 'Deploy schema from files'
  inputs:
    clusterUri: 'https://<ClusterName>.<Region>.kusto.windows.net'
    databaseName: '<DatabaseName>'
    commandsSource: 'files'
    commandFilesPattern: '**/*.csl'
    aadAppId: '$(AAD_APP_ID)'
    aadAppKey: '$(AAD_APP_KEY)'
    aadTenantId: '$(AAD_TENANT_ID)'
  continueOnError: true

你也可以根據檔案命名規則使用 **/*.kql 作為 glob 模式。

管理命令範例 — Azure 資源管理員服務連接

以下範例使用 Azure Resource Manager 服務連線，支援 工作負載身份聯盟（Workload Identity Federation， WIF） 及 管理身份（Managed Identity ）以實現無金鑰認證：

steps:
- task: Azure-Kusto.ADXAdminCommands.PublishToADX.ADXAdminCommand@5
  displayName: 'Deploy schema via ARM service connection'
  inputs:
    clusterUri: 'https://<ClusterName>.<Region>.kusto.windows.net'
    databaseName: '<DatabaseName>'
    commandsSource: 'files'
    commandFilesPattern: '**/*.csl'
    azureSubscription: '<ARM Service Connection Name>'
  continueOnError: true
  condition: ne(variables['ProductVersion'], '')

任務輸入參數

下表說明了該 ADXAdminCommand@5 任務的關鍵輸入參數：

參數	說明
clusterUri	Kusto 叢集的基礎 URI（例如， https://<ClusterName>.<Region>.kusto.windows.net）
databaseName	目標資料庫的名稱
commandsSource	指令來源： inline 用於內嵌 KQL 指令，或 files 基於檔案的指令
inlineCommands	內嵌 KQL 指令來執行（當 commandsSource 是 inline時使用 ）
commandFilesPattern	腳本檔案的全域模式（commandsSource 為 files 時使用），例如 **/*.csl 或 **/*.kql
aadAppId	Microsoft Entra 應用程式（服務主體）ID 用於 Azure Active Directory 應用程式認證
aadAppKey	Microsoft Entra 應用程式金鑰/秘密用於 AAD 應用程式認證
aadTenantId	Microsoft Entra 租戶 ID 用於 AAD 應用程式認證
azureSubscription	Azure Resource Manager 服務連線名稱，用於基於 ARM 的認證（支援 WIF 與管理身份）

驗證方法

擴充套件支援以下認證方法：

• Azure Active Directory （AAD） 應用程式註冊 — 使用 aadAppId、aadAppKey 和 aadTenantId，以服務主體進行認證。 將憑證儲存為安全管線變數。
• 憑證式認證 — 使用憑證取代應用程式金鑰進行服務主體認證。 將憑證細節儲存為安全管線變數。
• 管理身份 — 使用設定為管理身份的 Azure Resource Manager 服務連線。 請將 azureSubscription 輸入設定為服務連線名稱。
• 工作負載身份聯盟（WIF） — 使用與工作負載身份聯盟（Workload Identity Federation，自動或手動）的 Azure Resource Manager 服務連線。 這是推薦的無鑰匙方式。 將 azureSubscription 設為服務連線名稱。

注意

工作負載身份聯盟（Workload Identity Federation，WIF）是擴充功能中較新的新增功能。 它能實現無秘密認證，並成為新管線的推薦方法。 關於設定說明，請參閱在 Azure 資源管理器（ARM）服務連線中使用聯邦身份憑證或管理身份。

查詢範例

steps:
- task: Azure-Kusto.PublishToADX.ADXQuery.ADXQuery@5
  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=<DatabaseName>'
    authType: 'kustoserviceconn'
    connectedServiceName: '<connection service name>'
    minThreshold: '0'
    maxThreshold: '10'
  continueOnError: true