如何在Azure DevOps Board扩展中检测工作项核心事件

我刚好有过开发Azure DevOps Boards扩展处理这类工作项事件的经验，和Jira的事件监听器模式不太一样，Azure这边主要有两种核心方案，下面给你详细说说具体实现、示例和关键提示：

一、前端扩展：用Extension SDK监听工作项事件 #

如果你的扩展是嵌入在工作项表单页面的前端UI组件（比如自定义侧边栏、表单增强功能），可以用Azure DevOps的JavaScript SDK来直接监听页面内的工作项变更事件。

步骤1：初始化SDK #

首先在你的扩展HTML文件中引入并配置SDK：

<script src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js"></script>
<script>
    window.require.config({
        paths: {
            'azure-devops-extension-sdk': 'https://unpkg.com/azure-devops-extension-sdk@latest/dist/azure-devops-extension-sdk'
        }
    });
</script>

步骤2：订阅工作项事件 #

通过SDK提供的WorkItemFormService，你可以订阅字段变更、保存等核心事件，针对性处理你关心的场景：

require(['azure-devops-extension-sdk'], function (SDK) {
    SDK.init().then(async () => {
        // 获取工作项表单服务实例
        const workItemFormService = await SDK.getService('ms.vss-work-web.work-item-form-service');
        
        // 监听所有字段变更（覆盖分配人、状态、迭代路径等场景）
        workItemFormService.subscribeToFieldChanged((args) => {
            console.log(`字段 ${args.fieldName} 从 ${args.oldValue} 变更为 ${args.newValue}`);
            
            // 针对你关心的字段做专属处理
            switch(args.fieldName) {
                case 'System.AssignedTo':
                    const assignee = args.newValue?.displayName || '已取消分配';
                    console.log(`工作项分配状态变更：${assignee}`);
                    // 这里可以添加你的业务逻辑，比如发送通知、记录日志
                    break;
                case 'System.State':
                    console.log(`工作项状态流转：${args.oldValue} → ${args.newValue}`);
                    break;
                case 'System.IterationPath':
                    console.log(`工作项被添加到迭代：${args.newValue}`);
                    break;
            }
        });
        
        // 监听工作项保存事件（区分新建和更新）
        workItemFormService.subscribeBeforeSave((saveArgs) => {
            const actionType = saveArgs.isNew ? '新建' : '更新';
            console.log(`即将执行工作项${actionType}操作`);
            // 可以在这里做前置校验、数据同步等操作
        });
        
        // 获取当前工作项的初始数据（页面加载时）
        const currentWorkItem = await workItemFormService.getWorkItem();
        console.log('当前加载的工作项：', currentWorkItem);
    });
});

关键提示 #

• 这种方式仅在工作项表单页面生效，适合需要和用户实时交互的场景。
• 要使用Azure DevOps的系统字段名，比如System.AssignedTo（分配人）、System.State（状态）、System.IterationPath（迭代路径），这些字段名可以通过工作项设置中的“字段资源管理器”查看。
• 需要在扩展的vss-extension.json配置文件中声明对应的权限，比如只读访问工作项需要"scopes": ["vso.work"]，如果需要修改工作项则用"vso.work_write"。

二、全局事件监听：使用Web Hooks #

如果你需要监听整个项目/组织内的所有工作项事件（不管用户是否打开表单），比如做后台统计、同步到外部系统，Web Hooks是更合适的方案。

步骤1：创建Web Hook订阅 #

在Azure DevOps的项目设置中，进入服务挂钩 > 创建订阅：

• 选择触发服务：工作项
• 选择触发事件：比如工作项创建、工作项更新（包含分配、状态、迭代变更等所有更新操作）
• 配置通知目标：填写你的后端API地址（接收HTTP POST请求）
• 可选：配置筛选条件，比如只监听特定工作项类型、特定字段变更，或者特定项目的事件。

步骤2：处理Web Hook请求 #

你的后端服务会收到Azure DevOps发送的JSON格式请求体，里面包含完整的事件和工作项变更信息。简化后的示例payload如下：

{
    "eventType": "workitem.updated",
    "resource": {
        "fields": {
            "System.AssignedTo": {
                "oldValue": { "displayName": "张三" },
                "newValue": { "displayName": "李四" }
            },
            "System.State": {
                "oldValue": "To Do",
                "newValue": "In Progress"
            }
        },
        "id": 1234,
        "url": "https://dev.azure.com/your-org/your-project/_apis/wit/workItems/1234"
    }
}

你可以根据eventType判断是创建还是更新事件，然后解析resource.fields中的字段变更来处理对应的业务逻辑。

关键提示 #

• Web Hooks支持的工作项事件包括workitem.created、workitem.updated、workitem.deleted等，基本覆盖你需要的所有场景。
• 确保你的后端API可以被Azure DevOps访问（公网可达，或者在Azure内部网络中），可以用Azure Function、ASP.NET Core Web API等轻量级服务来处理请求。

三、补充方案：REST API轮询 #

如果上述两种方案都不满足需求（比如需要批量处理历史事件、或者无法使用Web Hooks），可以定期调用Azure DevOps REST API查询工作项的变更历史：

• 调用GET _apis/wit/workItems/{id}/history获取单个工作项的所有变更记录
• 调用WIQL查询接口，筛选特定时间范围内变更的工作项，示例查询语句：

SELECT [System.Id], [System.Title], [System.State], [System.ChangedDate] 
FROM WorkItems 
WHERE [System.ChangedDate] >= @today - 7

官方参考资源 #

• Azure DevOps Extension SDK：重点关注WorkItemFormService相关的API说明
• Web Hooks文档：查看工作项事件的完整payload结构和配置细节
• REST API文档：工作项查询、历史记录相关的接口说明

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