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

项目
04/29/2024

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

注意

语法

# 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 Pipelines 和 Classic Release 支持预定义的系统变量，如 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。
不支持 UPN 格式，包括 username@domain.com 和内置系统帐户（如 NT Authority\System ）。

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 时将应用的其他参数 AzCopy.exe ， --check-length=true例如。

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

--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支持 AzCopy.exe 版本 10.8.0。

注意

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

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

如果目标是 Azure VM，会首先将文件复制到自动生成的 Azure Blob 容器，然后再下载到 VM 中。文件成功复制到 VM 后，将删除容器。

该任务使用 AzCopy，这是一个命令行实用工具，专为将数据从 Azure 存储帐户快速复制和复制到 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 安装程序 v1.0.2 获取此版本。

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

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

在创建虚拟机后配置 WinRM

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

配置入站访问规则，以在每个 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 文件复制任务时，出现“将文件上传到 Blob 存储时，AzCopy.exe 退出并显示非零退出代码”

每次触发生成时，都会随机分配托管代理，每次运行时代理 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、经典版本、经典版本
运行平台	Agent、DeploymentGroup
需求	自承载代理必须具有满足以下要求的功能才能运行使用此任务的作业：azureps
功能	此任务不满足作业中后续任务的任何要求。
命令限制	任意
可设置变量	任意
代理版本	1.103.0 或更高版本
任务类别	部署