Azure DevOps集成Synapse：YAML+PowerShell触发管道及服务连接配置

一、配置Azure DevOps服务连接（核心前提） #

服务连接是Azure DevOps与Synapse通信的身份验证桥梁，步骤如下：

• 进入Azure DevOps项目的项目设置 > 服务连接 > 新建服务连接
• 选择Azure Resource Manager类型，点击下一步
• 选择服务主体（自动），关联目标Azure订阅，可选指定Synapse所在资源组，给服务连接命名（如Synapse-Service-Conn），勾选允许所有管道使用此连接后完成创建
• 确保该服务连接对应的服务主体拥有Synapse工作区的Synapse Contributor或更高权限，否则无法触发管道操作

二、YAML结合Azure PowerShell触发Synapse管道 #

直接在Azure DevOps YAML管道中使用AzurePowerShell任务调用Az模块命令触发Synapse管道：

示例YAML代码 #

trigger:
- main

pool:
  vmImage: 'ubuntu-latest' # 也可选用windows-latest，视PowerShell环境需求而定

steps:
- task: AzurePowerShell@5
  displayName: '触发Synapse分析管道'
  inputs:
    azureSubscription: 'Synapse-Service-Conn' # 填写你创建的服务连接名称
    ScriptType: 'InlineScript'
    Inline: |
      # 安装/更新Az.Synapse模块（首次运行或版本不足时执行）
      Install-Module -Name Az.Synapse -Force -AllowClobber -Scope CurrentUser
      
      # 定义Synapse工作区和目标管道名称
      $workspaceName = "your-synapse-workspace"
      $pipelineName = "your-target-pipeline"
      
      # 触发管道，如需传递参数可添加-Parameter参数
      $runResult = Invoke-AzSynapsePipeline -WorkspaceName $workspaceName -PipelineName $pipelineName
      
      # 输出运行ID，便于后续查询执行状态
      Write-Host "Synapse管道已触发，运行ID: $($runResult.RunId)"
    azurePowerShellVersion: 'LatestVersion'

关键说明 #

• AzurePowerShell@5任务会自动通过服务连接完成身份验证，无需手动执行Connect-AzAccount
• 若需传递管道参数，可在Invoke-AzSynapsePipeline中添加-Parameter @{ParamName1 = "Value1"; ParamName2 = "Value2"}，参数名需与Synapse管道定义完全匹配

三、使用独立PowerShell脚本触发Synapse管道（非内联方式） #

若希望脚本与YAML分离，可将触发逻辑写入独立.ps1文件并存入Azure DevOps仓库，再通过YAML调用：

1. 创建独立PowerShell脚本（示例命名：TriggerSynapsePipeline.ps1） #

param(
    [Parameter(Mandatory=$true)]
    [string]$WorkspaceName,
    [Parameter(Mandatory=$true)]
    [string]$PipelineName,
    [hashtable]$PipelineParams
)

# 检查并安装Az.Synapse模块
if (-not (Get-Module -ListAvailable -Name Az.Synapse)) {
    Install-Module -Name Az.Synapse -Force -AllowClobber -Scope CurrentUser
}

# 根据是否传递参数触发管道
if ($PipelineParams) {
    $runResponse = Invoke-AzSynapsePipeline -WorkspaceName $WorkspaceName -PipelineName $PipelineName -Parameter $PipelineParams
} else {
    $runResponse = Invoke-AzSynapsePipeline -WorkspaceName $WorkspaceName -PipelineName $PipelineName
}

Write-Host "Synapse管道触发成功，运行ID: $($runResponse.RunId)"

2. 在YAML中调用该脚本 #

trigger:
- main

pool:
  vmImage: 'windows-latest' # Windows环境对PowerShell模块兼容性更好，Ubuntu需额外配置PowerShell环境

steps:
- task: AzurePowerShell@5
  displayName: '调用独立脚本触发Synapse管道'
  inputs:
    azureSubscription: 'Synapse-Service-Conn'
    ScriptType: 'FilePath'
    ScriptPath: '$(System.DefaultWorkingDirectory)/TriggerSynapsePipeline.ps1' # 脚本在仓库中的路径
    ScriptArguments: '-WorkspaceName "your-synapse-workspace" -PipelineName "your-target-pipeline" -PipelineParams @{SourcePath="abfss://container@storage.dfs.core.windows.net/input"}'
    azurePowerShellVersion: 'LatestVersion'

四、常见问题排查 #

• 权限报错：检查服务连接的服务主体是否在Synapse工作区拥有Synapse Contributor角色，可在Azure Portal的Synapse工作区**访问控制（IAM）**中配置
• 模块安装失败：Ubuntu环境需先安装PowerShell，再执行模块安装命令；也可提前在自定义虚拟机镜像中预装所需模块
• 参数不生效：确保脚本中传递的参数名与Synapse管道定义的参数名完全一致，大小写敏感

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