如何查询Azure DevOps多阶段YAML管道的指定运行阶段？

背景 #

手动排队多阶段YAML管道时，可通过取消选择「阶段」来指定要包含或排除的阶段。同样，Azure DevOps REST API支持在POST请求体中指定stagesToSkip参数实现该操作，请求地址如下：
POST https://dev.azure.com/{organization}/{project}/_apis/pipelines/{pipelineId}/runs?api-version=7.2-preview.1

请求体示例：

{
  "stagesToSkip": [
     "test",
     "uat",
     "prod"
  ]
}

问题 #

是否存在可查询管道运行时预期执行阶段的API端点？

应用场景 #

• 以编程方式筛选出所有手动排队且排除了特定环境的构建；
• 在管道脚本中判断后续操作，比如若取消选择Performance-Test阶段则调整编译步骤。虽然可以通过管道变量或参数输入实现，但「要运行的阶段」更能直接反映用户意图。

解决方案 #

目前Azure DevOps REST API没有直接返回「预期执行阶段」的端点，但可以通过两种间接方式实现需求：

1. 从管道运行详情中提取stagesToSkip计算预期阶段 #

当通过API或手动排队管道时，stagesToSkip会被记录在管道运行的属性中。你可以调用以下API获取指定运行的详细信息：
GET https://dev.azure.com/{organization}/{project}/_apis/pipelines/runs/{runId}?api-version=7.2-preview.1

返回结果里的stagesToSkip字段会列出被跳过的阶段名称，用管道定义中的全阶段列表减去这个集合，就能得到预期执行的阶段。

2. 查询阶段状态API获取待执行阶段 #

如果是在管道脚本中判断，可以调用阶段状态API获取所有阶段的执行状态：
GET https://dev.azure.com/{organization}/{project}/_apis/pipelines/runs/{runId}/stages?api-version=7.2-preview.1

该API会返回所有阶段的状态（如notStarted、inProgress等），筛选出状态为notStarted且未被标记为跳过的阶段，即可得到预期执行的阶段。

场景优化建议 #

• 对于「定位特定构建」的场景：先批量获取管道运行列表，再逐个查询每个运行的stagesToSkip属性，筛选符合条件的运行即可；
• 对于「管道内脚本判断」的场景：更高效的方式是在排队时将选中的阶段通过自定义参数传递到管道中，结合stagesToSkip做双重验证，脚本直接读取参数值就能调整编译步骤。

内容的提问来源于stack exchange，提问作者bryanbcook