如何通过ADF提取Azure DevOps数据并导入SQL Server

前置准备 #

• 可用的Azure Data Factory实例，确保ADF网络可同时访问目标Azure DevOps组织、自托管SQL Server所属网络
• 生成Azure DevOps个人访问令牌（PAT），授予Work Items - Read权限，记录令牌值（生成后仅展示一次）
• 自托管SQL Server提前创建目标同步库，放通ADF对应访问IP的权限，同步使用的SQL账号需具备目标表的读写、建表权限
• 若SQL Server部署在内网无公网暴露，提前在ADF中配置并启动自托管集成运行时（SHIR），不要使用默认Azure公网集成运行时

步骤1：创建Azure DevOps链接服务 #

• 进入ADF Studio，左侧导航栏选择「管理」-「链接服务」，点击「新建」
• 连接器搜索选择Azure DevOps，按页面提示填写配置：
  • 组织名称：填写目标Azure DevOps组织名，无需填写完整URL
  • 项目名称：选择需要同步工作项的目标项目
  • 身份验证类型选择「个人访问令牌」，填入提前生成的PAT值
• 点击「测试连接」，验证通过后保存链接服务

步骤2：创建SQL Server链接服务 #

• 同链接服务新建页，搜索选择SQL Server连接器
• 集成运行时按需选择：公网可访问的SQL Server选默认Azure IR，内网部署的选提前配置好的SHIR
• 填写SQL Server实例地址、目标库名、身份验证信息（支持SQL认证、AAD认证）
• 测试连接通过后保存链接服务

步骤3：配置源端Azure DevOps数据集 #

• 左侧导航栏选择「作者」-「数据集」，新建数据集选择Azure DevOps连接器
• 关联上一步创建的Azure DevOps链接服务，数据集实体选择WorkItems
• 注意：Epics、Features、PBI、下级子工作项/BUG全部存储在同一个WorkItems实体中，通过WorkItemType字段区分类型，通过Parent字段存储上级工作项ID，无需为不同层级工作项单独创建数据集
• 若需要同步工作项关联关系、附件链接等信息，在数据集查询参数中添加$expand=relations，单次请求即可拉取关联字段，减少重复调用

步骤4：配置接收端SQL Server数据集 #

• 新建数据集选择SQL Server连接器，关联已创建的SQL Server链接服务
• 推荐提前在SQL库中建好目标表，核心字段参考：
  WorkItemId int（主键）、WorkItemType varchar(50)、Title nvarchar(500)、ParentId int、AreaPath nvarchar(500)、IterationPath nvarchar(500)、State varchar(50)、CreatedDate datetime、ChangedDate datetime、AssignedTo nvarchar(100)、CustomFields nvarchar(max)（存储自定义字段JSON内容）
• 若需要ADF自动建表，无需提前指定表名，后续在复制活动中开启自动建表选项即可

步骤5：搭建同步管道 #

• 左侧导航栏选择「作者」-「管道」，新建空白管道
• 拖拽「复制数据」活动到管道画布
• 切换到「源」配置页，选择之前创建的Azure DevOps工作项数据集：
  • 增量同步场景下添加过滤规则：[System.ChangedDate] >= @pipeline().parameters.LastSyncTime，LastSyncTime参数可配置为管道变量，每次同步完成后将最新的工作项变更时间写入SQL配置表，下次同步自动读取上次同步时间点，避免每次全量拉取
  • 源设置中务必开启「分页」选项，Azure DevOps API单页最多返回200条记录，不开分页会出现数据遗漏
• 切换到「接收器」配置页，选择SQL Server数据集：
  • 写入行为选择Upsert，主键字段设置为WorkItemId，同步时已存在的工作项自动更新、新增工作项自动插入，不会产生重复数据
  • 首次同步若未提前建表，勾选「自动创建表」选项，ADF会根据源端字段结构自动生成目标表
• 切换到「映射」配置页，将源端字段和SQL表字段一一对应，零散自定义字段可统一映射到CustomFields字段，通过@json()函数转换为JSON字符串存储
• 若需要直接输出打平后的层级关系（例如每条PBI直接关联所属Feature、Epic的ID和名称），可在复制活动后追加「数据流」活动，通过WorkItemId和ParentId做自关联递归查询，直接拼好全层级字段，省去后续在SQL中写递归CTE的步骤

步骤6：调试与调度配置 #

• 点击管道顶部「调试」按钮，先拉取最近7天变更的小范围数据测试，验证SQL库中数据完整性：确认Epics、Features、PBI、子工作项无遗漏，层级关联关系正确，字段无缺失
• 调试通过后为管道配置触发器，按业务需求设置同步频率（例如每日凌晨全量校验+每小时增量同步）
• 可按需配置失败告警规则，同步任务异常时推送通知给运维人员

常见问题排查 #

• 子工作项遗漏：检查源端分页是否开启，检查PAT权限是否覆盖所有区域路径，不要给PAT加项目、区域路径的访问限制
• 自托管SQL连接失败：检查SHIR运行状态是否正常，检查SQL Server防火墙是否放通SHIR所在机器IP，检查SQL账号权限是否符合要求
• 增量同步漏数：不要使用CreatedDate作为增量判断字段，必须使用ChangedDate——工作项状态更新、字段修改、指派人变更都会更新ChangedDate，CreatedDate仅在工作项创建时生成，无法捕获后续变更

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