你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

适用于 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 文档

先决条件

准备发布内容

可以使用以下方法对任务中的群集执行管理员命令:

屏幕截图显示命令源代码管理选项。

  • 使用搜索模式从本地代理文件夹(生成源或发布项目)获取多个命令文件

    屏幕截图显示本地文件夹选项。

  • 编写内联命令

    屏幕截图显示内联命令选项。

  • 指定文件路径,以直接从 git 源代码管理获取命令文件(推荐)

    屏幕截图显示 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

    屏幕截图显示如何为 Azure 数据资源管理器群集 URI 添加值。

创建部署文件夹的任务

  1. 在“管道”选项卡中,选择“1 个作业,0 个任务”以添加任务

    屏幕截图显示向管道添加任务。

  2. 重复以下步骤创建命令任务,从“Tables”、“Functions”和“Policies”文件夹部署文件

    屏幕截图显示如何添加 Azure 数据资源管理器管理员命令。

    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)

      选择“允许所有管道使用此连接”复选框,然后选择“确定”

      屏幕截图显示如何添加服务连接。

  3. 选择“保存”,然后在“任务”选项卡中,验证是否有以下三个任务:“部署表”、“部署函数”和“部署策略”

    屏幕截图显示如何部署所有文件夹。

创建查询任务

如有必要,请创建一个任务,对群集运行查询。 可使用“生成”或“发布”管道中的“运行查询”来验证数据集,并根据查询结果判断步骤是否成功。 任务成功条件可以基于行计数阈值或单个值,具体取决于查询返回的结果。

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

  2. 在“运行 Azure 数据资源管理器查询”下,选择“添加”

  3. 选择“Kusto 查询”,然后使用以下信息更新任务

    • 显示名称:任务的名称。 例如“查询群集”
    • 类型:选择“内联”
    • 查询:输入要运行的查询。
    • 终结点 URL:指定之前创建的 EndPoint URL 变量。
    • 使用服务终结点:选择此选项。
    • 服务终结点:选择服务终结点。

    屏幕截图显示如何创建查询任务。

  4. 在任务结果下,根据查询的结果选择任务的成功条件,如下所示:

    • 如果查询返回行,请选择“行计数”并提供所需条件

      屏幕截图显示查询返回行数并设置行计数阈值。

    • 如果查询返回一个值,请选择“单个值”并提供预期结果

      屏幕截图显示查询返回单个值并设置预期值。

创建查询服务器入口任务

如有必要,请创建一个任务来对群集运行查询,并对等待查询结果行计数的发布进度进行限制。 服务器查询入口任务是一个无代理作业,这意味着查询会直接在 Azure DevOps Server 上运行。

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

  2. 在“运行 Azure 数据资源管理器查询服务器入口”下,选择“添加”

  3. 选择“Kusto 查询服务器入口”,然后选择“服务器入口测试”

    屏幕截图显示如何选择服务器入口任务。

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

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

    屏幕截图显示如何配置服务器入口任务。

备注

运行发布时,应会看到如下所示的结果。

屏幕截图显示查询入口任务结果示例。

运行发布

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

    屏幕截图显示如何创建发布。

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

    屏幕截图显示部署成功。

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

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

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

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

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

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

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

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

    屏幕截图显示 Microsoft Entra 应用的“联合凭据”选项卡。

  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 资源管理器”

    屏幕截图显示如何添加 Azure 资源监视器服务连接。

  2. 在“身份验证方法”下,选择“工作负载联合身份验证(自动)”。 或者,也可以使用手动“工作负载联合身份验证(手动)”选项来指定工作负载联合身份验证详细信息,或使用“托管标识”选项。 有关使用 Azure 资源管理设置托管标识的详细信息,请参阅 Azure 资源管理器 (ARM) 服务连接

    屏幕截图显示 Azure 资源监视器服务连接的身份验证选项

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

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