AzureFileCopy@4 - Azure 文件复制 v4 任务

项目
03/24/2025

将文件复制到 Azure Blob 存储或虚拟机。

注释

此任务不支持使用工作流标识联合身份验证 Azure 资源管理器身份验证。

语法

# Azure file copy v4
# Copy files to Azure Blob Storage or virtual machines.
- task: AzureFileCopy@4
  inputs:
    SourcePath: # string. Required. Source. 
    azureSubscription: # string. Alias: ConnectedServiceNameARM. Required. Azure Subscription. 
    Destination: # 'AzureBlob' | 'AzureVMs'. Required. Destination Type. 
    storage: # string. Alias: StorageAccountRM. Required. RM Storage Account. 
    #ContainerName: # string. Required when Destination = AzureBlob. Container Name. 
    #BlobPrefix: # string. Optional. Use when Destination = AzureBlob. Blob Prefix. 
    #resourceGroup: # string. Alias: EnvironmentNameRM. Required when Destination = AzureVMs. Resource Group. 
    #ResourceFilteringMethod: 'machineNames' # 'machineNames' | 'tags'. Optional. Use when Destination = AzureVMs. Select Machines By. Default: machineNames.
    #MachineNames: # string. Optional. Use when Destination = AzureVMs. Filter Criteria. 
    #vmsAdminUserName: # string. Required when Destination = AzureVMs. Admin Login. 
    #vmsAdminPassword: # string. Required when Destination = AzureVMs. Password. 
    #TargetPath: # string. Required when Destination = AzureVMs. Destination Folder. 
    #AdditionalArgumentsForBlobCopy: # string. Optional Arguments (for uploading files to blob). 
    #AdditionalArgumentsForVMCopy: # string. Optional. Use when Destination = AzureVMs. Optional Arguments (for downloading files to VM). 
    #sasTokenTimeOutInMinutes: '240' # string. Optional. Use when Destination = AzureBlob. SAS Token Expiration Period In Minutes. Default: 240.
    #enableCopyPrerequisites: false # boolean. Optional. Use when Destination = AzureVMs. Enable Copy Prerequisites. Default: false.
    #CopyFilesInParallel: true # boolean. Optional. Use when Destination = AzureVMs. Copy in Parallel. Default: true.
    #CleanTargetBeforeCopy: false # boolean. Optional. Use when Destination = AzureVMs. Clean Target. Default: false.
    #skipCACheck: true # boolean. Optional. Use when Destination = AzureVMs. Test Certificate. Default: true.

输入

SourcePath - 源
string。必填。

源文件的位置。支持的值包括 YAML 管道和经典发布支持，预定义的系统变量，如 Build.Repository.LocalPath。

发布变量仅在经典版本中受支持。文件路径或文件名中的任意位置都支持通配符 \ 。

azureSubscription - Azure 订阅
输入别名：ConnectedServiceNameARM。 string。必填。

指定为目标 Azure 服务、虚拟机或存储帐户所在的订阅配置的 Azure 资源管理器服务连接的名称。有关更多详细信息，请参阅 Azure 资源管理器概述。

Destination - 目标类型
string。必填。允许的值：AzureBlob（Azure Blob）、AzureVMs（Azure VM）。

指定目标类型。

storage - RM 存储帐户
输入别名：StorageAccountRM。 string。必填。

指定预先存在的 ARM 存储帐户。这是用作将文件复制到 Azure VM 的中介的存储帐户。

ContainerName - 容器名称
string。 Destination = AzureBlob时是必需的。

要将文件复制到的容器的名称。如果存储帐户中不存在指定的容器，则会创建它。

若要在容器中创建虚拟目录，请使用 Blob 前缀输入。例如，对于目标位置 https://myaccount.blob.core.windows.net/mycontainer/vd1/vd2/，请指定容器名称 mycontainer 和 blob 前缀：vd1/vd2。

BlobPrefix - Blob 前缀
string。可选。当 Destination = AzureBlob时使用。

指定可用于筛选文件的前缀。

示例：可以追加生成号以筛选具有相同内部版本号的所有 Blob 中的文件。

示例：如果指定 blob 前缀 myvd1，则会在容器中创建虚拟目录。文件从源复制到 https://myaccount.blob.core.windows.net/mycontainer/myvd1/。

resourceGroup - 资源组
输入别名：EnvironmentNameRM。 string。 Destination = AzureVMs时是必需的。

指定要将文件复制到的目标资源组的名称。

ResourceFilteringMethod - 按选择计算机
string。可选。当 Destination = AzureVMs时使用。允许的值：machineNames（计算机名称），tags。默认值：machineNames。

指定标识资源组中 VM 子集的 VM 主机名或标记。仅 Azure 资源管理器创建的资源支持标记。

MachineNames - 筛选条件
string。可选。当 Destination = AzureVMs时使用。

提供 VM 名称或标记名称的列表，用于标识任务将面向的 VM。有效的筛选器条件包括：

Azure 资源组的名称。
上一个任务的输出变量。
以逗号分隔的标记名称或 VM 名称列表。
使用逗号分隔的 FQDN 或 IP 地址列表设置 VM 名称的格式。
将筛选器的标记名称格式化为 {TagName}:{Value} 示例：Role:DB;OS:Win8.1

vmsAdminUserName - 管理员登录
string。 Destination = AzureVMs时是必需的。

为所有目标 VM 提供具有管理权限的帐户的用户名。

支持的格式包括：username、domain\username、machine-name\username和 .\username。
不支持包括 username@domain.com 和内置系统帐户（如 NT Authority\System）的 UPN 格式。

vmsAdminPassword - 密码
string。 Destination = AzureVMs时是必需的。

提供 Admin Login 参数的密码。

若要查找变量，请找到 Admin Login 参数。选择 Variables 选项卡中定义的变量的挂锁图标，以保护值并在此处插入变量名称。

TargetPath - 目标文件夹
string。 Destination = AzureVMs时是必需的。

指定将文件复制到的 Azure VM 中的文件夹的路径。

支持 $env:windir 和 $env:systemroot 等环境变量。示例：$env:windir\FabrikamFiber\Web 和 c:\FabrikamFiber

AdditionalArgumentsForBlobCopy - 可选参数（用于将文件上传到 blob）
string。

为 AzCopy.exe 提供其他参数，以便在上传到 Blob 并下载到 VM 时使用。有关详细信息，请参阅使用 AzCopy Command-Line 实用工具传输数据。

对于仅支持 Azure 页 Blob 的高级存储帐户，请使用 --blob-type=PageBlob 作为附加参数。

默认参数包括 --log-level=INFO（默认值）和 --recursive（如果容器名称未 $root）。

AdditionalArgumentsForVMCopy - 可选参数（用于将文件下载到 VM）
string。可选。当 Destination = AzureVMs时使用。

为下载到 VM（例如，--check-length=true）时将应用的 AzCopy.exe 提供其他参数。

如果未指定可选参数，则默认添加以下内容：

--log-level=INFO
--log-level=DEBUG（如果管道在调试模式集中运行）
--recursive

sasTokenTimeOutInMinutes - SAS 令牌过期期限（以分钟为单位）
string。可选。当 Destination = AzureBlob时使用。默认值：240。

指定容器的 SAS 令牌过期的时间（以分钟为单位）。默认情况下，此令牌会在 4 小时后过期。

enableCopyPrerequisites - 启用复制先决条件
boolean。可选。当 Destination = AzureVMs时使用。默认值：false。

启用后，此选项使用自签名证书通过端口 5986 上的 HTTPS 协议配置 Windows 远程管理（WinRM）侦听器。在 Azure VM 上执行复制作需要此配置。

如果通过负载均衡器访问目标 VM，请配置入站 NAT 规则以允许在端口 5986 上访问。
如果目标 VM 与网络安全组（NSG）相关联，请配置入站安全规则以允许在端口 5986 上访问。

并行复制 CopyFilesInParallel -
boolean。可选。当 Destination = AzureVMs时使用。默认值：true。

指定 true 将文件并行复制到目标 VM。

CleanTargetBeforeCopy - 清理目标
boolean。可选。当 Destination = AzureVMs时使用。默认值：false。

指定 true 以在复制文件之前清理目标文件夹。

skipCACheck - 测试证书
boolean。可选。当 Destination = AzureVMs时使用。默认值：true。

将文件从中间存储 Blob 复制到 Azure VM 时，WinRM 需要 HTTPS 传输证书。

如果使用自签名证书，请指定 true 以防止进程使用受信任的 CA 验证证书。

任务控制选项

除任务输入之外，所有任务都具有控制选项。有关详细信息，请参阅控件选项和常见任务属性。

输出变量

此任务定义以下输出变量，可以在下游步骤、作业和阶段中使用。

StorageContainerUri
文件复制到的容器的 URI。仅当所选目标为 Azure Blob 时有效。

StorageContainerSasToken
为文件复制到的容器 SasToken。仅当所选目标为 Azure Blob 时有效。

注解

AzureFileCopy@4支持版本 10.8.0 AzCopy.exe。

注释

此任务以 PowerShell 编写，仅在 Windows 代理上运行时。如果管道需要 Linux 代理，并且需要将文件复制到 Azure 存储帐户，请考虑 Azure CLI 任务中运行 az storage blob 命令作为替代方法。

该任务用于复制应用程序文件和安装应用所需的其他项目;例如 PowerShell 脚本、PowerShell-DSC 模块等。

当目标为 Azure VM 时，文件首先复制到自动生成的 Azure Blob 容器，然后将其下载到 VM 中。成功将文件复制到 VM 后，将删除容器。

该任务使用 AzCopy，这是用于快速从 Azure 存储帐户复制数据的命令行实用工具。 Azure 文件复制任务版本 4 使用 AzCopy V10。

Azure 文件复制版本 3 及更低版本将检索 Azure 存储密钥以提供访问权限。 Azure 文件复制版本 4 及更高版本要求通过 Microsoft Entra ID 或 SAS 令牌授权 Azure 存储。可以使用服务主体和托管标识进行身份验证。对于托管标识，仅支持系统范围的托管标识。所需的授权级别显示在选项 1 ：使用 Microsoft Entra ID。

若要动态部署包含虚拟机的 Azure 资源组，请使用 Azure 资源组部署任务。此任务有一个示例模板，可以执行所需的作，在 VM 上设置 WinRM HTTPS 协议，在防火墙中打开端口 5986，然后安装测试证书。

注释

如果要将 Azure 静态网站部署为 Blob 存储中的容器，请使用 版本 2 或更高版本的任务来保留 $web 容器名称。

该任务支持基于 Azure Active Directory 的身份验证。可以使用服务主体和托管标识进行身份验证。对于托管标识，仅支持系统范围的托管标识。

使用此任务的 Azure PowerShell 先决条件是什么？

该任务要求在运行自动化代理的计算机上安装 Azure PowerShell。建议的版本为 1.0.2，但该任务适用于版本 0.9.8 及更高版本。可以使用 Azure PowerShell Installer v1.0.2 来获取此信息。

此任务的 WinRM 先决条件是什么？

该任务使用 Windows 远程管理（WinRM） HTTPS 协议将文件从存储 Blob 容器复制到 Azure VM。这要求在 VM 上配置 WinRM HTTPS 服务，并安装合适的证书。

创建虚拟机后配置 WinRM

如果在未打开 WinRM HTTPS 端口的情况下创建 VM，请执行以下步骤：

配置入站访问规则，以允许每个 VM 的端口 5986 上的 HTTPS。
禁用 UAC 远程限制。
使用简单形式的管理员级登录 用户名 指定任务访问 VM 的凭据，而无需任何域部分。
在运行自动化代理的计算机上安装证书。
如果使用自签名证书，请设置任务的 测试证书 参数。

应选择哪种类型的服务连接？

对于 Azure 资源管理器存储帐户和 Azure 资源管理器 VM，请使用 Azure 资源管理器 服务连接类型。请参阅使用服务主体自动执行 Azure 资源组部署。
使用 Azure 资源管理器 服务连接类型时，任务会自动筛选适当的较新的 Azure 资源管理器存储帐户和其他字段。例如，资源组或云服务和 VM。

如何创建用于此任务的学校或工作帐户？

可以创建合适的帐户，以便在服务连接中使用：

使用 Azure 门户在 Azure Active Directory 中创建新的用户帐户。
将 Azure Active Directory 用户帐户添加到 Azure 订阅中的共同管理员组。
使用此用户帐户登录到 Azure 门户并更改密码。
在服务连接中使用此帐户的凭据。然后，使用此帐户处理部署。

如果任务失败，复制是否会恢复？

由于 AzCopy V10 不支持日志文件，因此该任务无法恢复副本。必须再次运行该任务才能复制所有文件。

是否在复制后清除日志文件和计划文件？

任务不删除日志和计划文件。若要显式清理文件，请使用 azcopy jobs clean在工作流中添加 CLI 步骤。

如何使用 Azure 文件复制任务将文件复制到没有公共 IP 地址的 Azure 虚拟机？

确保使用的是 Azure 文件复制任务版本 4。如果任务失败，可以添加生成步骤以运行命令 azcopy cp "source-file-path" "destination-file-path" 替换源值和目标值。

禁止错误：在使用 Azure 文件复制任务时，“AzCopy.exe 使用非零退出代码退出，同时将文件上传到 Blob 存储”

每次触发生成时，都会随机分配托管代理，每次运行时代理 IP 地址将有所不同。如果这些 IP 地址不在允许的 IP 列表中，Azure DevOps 与存储帐户之间的通信将失败。在这种情况下，请遵循概述的步骤：

使用 Azure CLI 添加生成步骤，以在运行时标识Microsoft托管生成代理的 IP 地址。它将将 IP 地址添加到 Azure 存储帐户上的网络规则。
运行 Azure 存储帐户的生成步骤。
使用 Azure CLI 添加另一个生成步骤，以从 Azure 存储帐户网络规则中删除生成代理的 IP 地址。

例子

- task: AzureFileCopy@4
  inputs:
    SourcePath: 'Readme.md'
    azureSubscription: 'Azure'
    Destination: 'AzureBlob'
    storage: 'storageAccount'
    ContainerName: 'containerName'
    BlobPrefix: ''
  name: AzureFileCopy
  
- script: | 
    echo $(AzureFileCopy.StorageContainerUri)
    echo $(AzureFileCopy.StorageContainerSasToken)

要求

要求	说明
管道类型	YAML，经典版本，经典版本
运行时间	代理，DeploymentGroup
需求	自承载代理必须具有功能，满足以下要求，运行使用此任务的作业：
功能	此任务不满足作业中后续任务的任何要求。
命令限制	任何
Settable 变量	任何
代理版本	1.103.0 或更高版本
任务类别	部署

通过