AzureFileCopy@4 - Azure 檔案複製 v4 工作

發行項
03/24/2025

將檔案複製到 Azure Blob 記憶體或虛擬機。

備註

此工作不支援使用工作流程身分識別同盟 Azure Resource Manager 驗證。

語法

# 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 Resource Manager 服務連線的名稱，針對目標 Azure 服務、虛擬機或記憶體帳戶所在的訂用帳戶進行設定。如需詳細資訊，請參閱 Azure Resource Manager 概觀。

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 Resource Manager 建立的資源。

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 - 選擇性自變數
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 版和更新版本要求 Azure 記憶體必須透過 Microsoft Entra ID 或 SAS 令牌獲得授權。您可以使用服務主體和受控識別進行驗證。針對受控識別，僅支援全系統受控識別。所需的授權層級會顯示在選項 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，用戶名稱 沒有任何網域元件。
在執行自動化代理程式的電腦上安裝憑證。
如果您使用自我簽署憑證，請設定工作的 Test Certificate 參數。

我應該選擇哪種類型的服務連線？

針對 Azure Resource Manager 記憶體帳戶和 Azure Resource Manager VM，請使用 Azure Resource Manager 服務連線類型。請參閱使用服務主體將 Azure 資源群組部署自動化。
使用 Azure Resource Manager 服務連線類型時，工作會自動篩選適當的較新 Azure Resource Manager 記憶體帳戶和其他欄位。例如，資源群組或雲端服務，以及 VM。

如何建立學校或公司帳戶以用於這項工作？

您可以建立適當的帳戶，以用於服務連線：

使用 Azure 入口網站在 Azure Active Directory 中建立新的用戶帳戶。
將 Azure Active Directory 使用者帳戶新增至 Azure 訂用帳戶中的共同管理員群組。
使用此用戶帳戶登入 Azure 入口網站，並變更密碼。
在服務連線中使用此帳戶的認證。接著會使用此帳戶來處理部署。

如果工作失敗，複本會繼續嗎？

由於 AzCopy V10 不支援日誌檔案，因此工作無法繼續進行複製作業。您必須再次執行工作，才能複製所有檔案。

複製之後，記錄檔和計劃檔是否已清除？

工作不會刪除記錄檔和計畫檔案。若要明確清除檔案，請使用 azcopy jobs clean 在工作流程中新增 CLI 步驟。

如何使用 Azure 檔案複製工作，將檔案複製到沒有公用 IP 位址的 Azure 虛擬機？

請確定您使用第 4 版的 Azure 檔案複製工作。如果工作失敗，您可以新增建置步驟來執行命令 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、傳統組建、傳統版本
執行於	Agent、DeploymentGroup
需求	自我裝載代理程序必須具有功能，符合下列需求，才能執行使用此工作的工作： azureps
功能	此工作不符合作業中後續工作的任何需求。
命令限制	任意
Settable 變數	任意
代理程式版本	1.103.0 或更新
工作類別	部署

共用方式為