适用于 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 Data Explorer 群集和数据库。 创建群集和数据库。
• 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. 重复以下步骤创建命令任务，从“Tables”、“Functions”和“Policies”文件夹部署文件：

   

   1. 在“任务”选项卡中，选择“代理作业”旁的 ，然后搜索“Azure 数据资源管理器”+。

   2. 在 运行 Azure 数据资源管理器命令 下，选择 添加。

   3. 选择“Kusto 命令”，然后利用以下信息更新任务：

      • 显示名称：任务的名称。 例如，Deploy <FOLDER>，其中 <FOLDER> 是要创建的部署任务的文件夹的名称。

      • 文件路径：对于每个文件夹，请将路径指定为 */<FOLDER>/*.csl，其中 <FOLDER> 是任务的相关文件夹。

      • 终结点 URL：指定上一步中创建的 EndPoint URL 变量。

      • 使用服务终结点：选择此选项。

      • 服务终结点：选择现有的服务终结点或创建一个新的终结点（+ 新建），并在“添加 Azure 数据资源管理器服务连接”窗口中提供以下信息：

        设置	建议值
        身份验证方法	设置联合标识凭据 (FIC)（建议），或选择服务主体身份验证 (SPA)。
        连接名称	输入名称以标识此服务终结点
        群集 URL	可在 Azure 门户中 Azure 数据资源管理器群集的概述部分查找值
        服务主体 ID	输入 Microsoft Entra 应用 ID（作为先决条件创建）
        服务主体应用密钥	输入 Microsoft Entra 应用密钥（作为先决条件创建）
        Microsoft Entra 租户 ID	输入 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 Query Server Gate”，然后选择“Server Gate Test”。

   

4. 配置任务并提供以下信息：

   • 显示名称：入口的名称。
   • 服务终结点：选择服务终结点。
   • 数据库名称：指定数据库名称。
   • 类型：选择“内联查询”。
   • 查询：输入要运行的查询。
   • 最大阈值：指定查询成功条件的最大行数。

   

运行发布版本

1. 选择 “+ 发布>创建” 以启动发布。

   

2. 在“日志”选项卡中，检查部署状态是否为“成功”。

   

现在，用于部署到预生产环境的发布管道已经创建完成。

对 Azure 数据资源管理器 DevOps 任务的无密钥身份验证支持

该扩展支持 Azure 数据资源管理器群集的无密钥身份验证。 无密钥身份验证允许在不使用密钥的情况下向 Azure 数据资源管理器群集进行身份验证。 更安全、更易于管理。

在 Azure 数据资源管理器服务连接中使用联合标识凭据 (FIC) 身份验证

1. 在 DevOps 实例中，转到“项目设置”“服务连接”>“新建服务连接”“Azure 数据资源管理器”>>。

2. 选择“联合标识凭据”，然后输入群集 URL、服务主体 ID、租户 ID、服务连接名称，然后选择“保存”。

3. 在 Azure 门户中，为指定服务主体打开 Microsoft Entra 应用。

4. 在“证书和机密”下，选择“联合凭据”。

   

5. 选择“添加凭据”，然后在“联合凭据方案”中选择“其他颁发者”，并使用以下信息填写设置：

   • 颁发者：<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} 是之前创建的服务连接名称。

     注意

     如果服务连接名称中有空间，则可以将其与字段中的空间一起使用。 例如：sc://MyOrg/MyProject/My Service Connection。

   • 名称：输入凭据的名称。

   

6. 选择 添加 。

在 Azure 资源管理器 (ARM) 服务连接中使用联合身份凭证或托管身份

1. 在 DevOps 实例中，转到“项目设置”“服务连接”>“新建服务连接”“Azure 资源管理器”>>。

   

2. 在 “身份验证”方法下，选择 “工作负荷联合身份验证”（自动） 以继续。 还可以使用手动 工作负荷联合身份验证（手动） 选项来指定工作负荷联合身份验证详细信息或 托管标识 选项。 详细了解如何在 Azure 资源管理器（ARM） 服务连接中使用 Azure 资源管理设置托管标识。

   

3. 填写所需的详细信息，选择“验证”，然后选择“保存”。

YAML 管道配置

可以使用 管道架构中的 Azure DevOps Web UI 或 YAML 代码配置任务。

该扩展提供三个管道任务，所有任务都可通过 YAML 进行访问：

• Azure 数据资源管理器命令 （ADXAdminCommand@5） - 针对 ADX 群集运行管理员/控制命令
• Azure 数据资源管理器查询 - 针对 ADX 群集运行查询并分析结果
• Azure 数据资源管理器查询服务器门 - 根据查询结果对发布的无代理任务进行门控

管理员命令示例 – 内联命令

以下示例使用支持工作负荷联合身份验证（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

管理员命令示例 - 基于文件的命令

以下示例使用 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 资源管理器服务连接，该连接支持 工作负荷标识联合身份验证（WIF） 和 托管标识 进行无密钥身份验证：

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 ：

身份验证方法

该扩展支持以下身份验证方法：

• Azure Active Directory （AAD）应用注册 - 使用aadAppId、aadAppKey和aadTenantId进行服务主体身份验证。 将凭据存储为安全管道变量。
• 基于证书的身份验证 - 使用证书而不是应用密钥进行服务主体身份验证。 将证书详细信息存储为安全管道变量。
• 托管标识 - 使用配置了托管标识的 Azure 资源管理器服务连接。 将 azureSubscription 输入设置为服务连接名称。
• 工作负荷联合身份验证 （WIF） - 将 Azure 资源管理器服务连接与工作负荷联合身份验证（自动或手动）配合使用。 这是推荐的无键方法。 将 azureSubscription 输入设置为服务连接名称。

查询示例

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