如何在Bicep Deployment Script中使用外部文件部署Synapse工作区包

问题概述 #

目标是将Synapse Workspace Packages添加到指定Synapse工作区，用于后续绑定Spark Pool。由于无法直接通过Bicep实现，采用Deployment Script调用PowerShell脚本的方案：先将zip包上传至存储账户，再同步到Synapse工作区。但遇到两个核心问题：

1. 部署脚本运行时，相对路径的WorkspacePackages.zip无法被识别，但手动在Azure CLI中测试PS1脚本却正常工作；
2. 无法获取Deployment Script自动生成的随机文件共享名称。

当前使用的Bicep模板：

metadata description = 'Deploys a deployment script to upload Synapse workspace packages to a storage account.'

@description('The subscription ID to connect to the Azure subscription.')
param subscriptionId string

@description('The resource group to add the role assignments to.')
param resourceGroupName string

@description('The name of deployment script resource.')
param resourceName string

@description('The name of deployment script container resource.')
param containerName string

@description('The name of deployment script storage account resource.')
param storageAccountDeploymentName string

@description('The identity name to connect to the Azure subscription.')
param identityName string

@description('The Synapse workspace name to add the role assignments to.')
param synapseWorkspaceName string

@description('The timestamp to be used in deployment script name.')
param timestamp string = utcNow()

resource userAssignedIdentity 'Microsoft.ManagedIdentity/userAssignedIdentities@2023-07-31-preview' existing = {
  name: identityName
  scope: resourceGroup(subscriptionId, resourceGroupName)
}

resource storageAccount 'Microsoft.Storage/storageAccounts@2023-01-01' existing = {
  name: storageAccountDeploymentName
  scope: resourceGroup(subscriptionId, resourceGroupName)
}

resource synapseWorkspaceAddPackages 'Microsoft.Resources/deploymentScripts@2023-08-01' = {
  name: resourceName
  location: resourceGroup().location
  kind: 'AzurePowerShell'
  identity: {
    type: 'UserAssigned'
    userAssignedIdentities: {
      '${userAssignedIdentity.id}': {}
    }
  }
  properties: {
    azPowerShellVersion: '13.2'
    environmentVariables: [
      {
        name: 'PackageZipFile'
        value: ('../WorkspacePackages.zip')
      }
    ]
    scriptContent: loadTextContent('../../../.scripts/synapse/UploadSynapsePackages.ps1')
    arguments: '-ResourceGroup ${resourceGroupName} -WorkspaceName ${synapseWorkspaceName} -PackageZipPath $env:PackageZipFile -StorageAccountName ${storageAccountDeploymentName} -ContainerName "filesystem"'
    cleanupPreference: 'OnExpiration'
    retentionInterval: 'P1D'
    // Deployment scripts are idempotent, so we can use utcnow on Tag to force an update
    forceUpdateTag: 'Run-${timestamp}'
    containerSettings: { containerGroupName: containerName }
    storageAccountSettings: {
      storageAccountName: storageAccountDeploymentName
      #disable-next-line use-secure-value-for-secure-inputs
      storageAccountKey: storageAccount.listKeys().keys[0].value
    }
  }
}

output synapseWorkspaceAddPackagesId string = synapseWorkspaceAddPackages.id
output successCount int = synapseWorkspaceAddPackages.properties.outputs.success ?? 0
output failsCount int = synapseWorkspaceAddPackages.properties.outputs.fails ?? 0
output totalCount int = synapseWorkspaceAddPackages.properties.outputs.total ?? 0

解决方案 #

问题1：相对路径文件无法识别 #

Deployment Script运行在Azure托管的容器环境中，本地相对路径在容器内不存在。解决思路是将zip文件编码为Base64嵌入到部署模板中，在脚本运行时解码为临时文件使用：

步骤1：修改Bicep模板的环境变量

替换原有的PackageZipFile环境变量，新增Base64编码的文件内容，并将参数移至环境变量中：

environmentVariables: [
  {
    name: 'PackageZipBase64'
    value: loadFileAsBase64('../WorkspacePackages.zip')
  }
  {
    name: 'ResourceGroup'
    value: resourceGroupName
  }
  {
    name: 'WorkspaceName'
    value: synapseWorkspaceName
  }
  {
    name: 'StorageAccountName'
    value: storageAccountDeploymentName
  }
  {
    name: 'ContainerName'
    value: 'filesystem'
  }
]

清空arguments字段，改为从环境变量读取参数：

arguments: ''

步骤2：修改PowerShell脚本解码文件

在UploadSynapsePackages.ps1中添加解码逻辑，替换原有路径引用：

# 解码Base64内容为临时zip文件
$zipContent = [Convert]::FromBase64String($env:PackageZipBase64)
$tempZipPath = Join-Path $env:TEMP 'WorkspacePackages.zip'
[IO.File]::WriteAllBytes($tempZipPath, $zipContent)

# 后续上传逻辑使用$tempZipPath作为包路径，示例：
# $storageContext = New-AzStorageContext -StorageAccountName $env:StorageAccountName -StorageAccountKey (Get-AzStorageAccountKey -ResourceGroupName $env:ResourceGroup -Name $env:StorageAccountName)[0].Value
# Set-AzStorageBlobContent -File $tempZipPath -Container $env:ContainerName -Context $storageContext

问题2：获取随机文件共享名称 #

Deployment Script会自动在指定存储账户中创建随机名称的文件共享，用于存储脚本资产。可通过两种方式获取：

方式1：在PowerShell脚本中直接读取环境变量

Deployment Script运行时会自动设置AZ_SCRIPTS_SHARE_NAME环境变量，直接读取即可：

$shareName = $env:AZ_SCRIPTS_SHARE_NAME
Write-Host "随机文件共享名称：$shareName"

方式2：在Bicep中获取输出值

如果需要在Bicep模板中获取该名称，可在PS1脚本末尾添加输出逻辑：

# 输出结果包含共享名称
$output = @{
  success = 1 # 根据实际执行结果调整
  fails = 0
  total = 1
  ShareName = $env:AZ_SCRIPTS_SHARE_NAME
}

Write-Output ($output | ConvertTo-Json)

然后在Bicep模板中新增输出项：

output fileShareName string = synapseWorkspaceAddPackages.properties.outputs.ShareName ?? ''

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