AzureFileCopy@5 - Azure 檔案複製 v5 工作

發行項
04/29/2024

將檔案複製到 Azure Blob 儲存體或虛擬機。

注意

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

Syntax

# Azure file copy v5
# Copy files to Azure Blob Storage or virtual machines.
- task: AzureFileCopy@5
  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. 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 Resource Manager 服務連線名稱。如需詳細資訊，請參閱 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。

指定 Azure Blob 容器內目的地虛擬目錄的前置詞。這 SourcePath 適用於包含可能符合多個專案的通配符時。

範例：您可以附加組建編號，以將所有 Blob 中的檔案加上相同的組建編號。

範例：如果您指定 Blob 前置詞 myvd1，則會在容器內建立虛擬目錄。檔案會從來源 https://myaccount.blob.core.windows.net/mycontainer/myvd1/複製到。

如果 SourcePath 是沒有通配符的單一專案，此 Blob 前置詞會作為目的地 Blob 名稱。

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。
不支援包含和內建系統帳戶等 NT Authority\System UPN格式username@domain.com。

vmsAdminPassword - 密碼
string. 當 Destination = AzureVMs 時為必要。

提供參數的密碼 Admin Login 。

若要尋找變數，請找出 Admin Login 參數。選取索引標籤中 Variables 定義之變數的掛鎖圖示，以保護值，並在此處插入變數名稱。

TargetPath - 目的地資料夾
string. 當 Destination = AzureVMs 時為必要。

指定將複製檔案之 Azure VM 中資料夾的路徑。

支援和 $env:systemroot 之類的$env:windir環境變數。範例：$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 上執行複製作業需要此設定。僅適用於 ARM VM。

如果目標 VM 是透過負載平衡器存取，請設定輸入 NAT 規則以允許在埠 5986 上存取。
如果目標 VM 與網路安全組 (NSG) 相關聯，請設定輸入安全性規則以允許在埠 5986 上存取。

CopyFilesInParallel - 平行複製
boolean. 選擇性。使用時機 Destination = AzureVMs。預設值：true。

指定 true 以平行方式將檔案複製到目標 VM。

CleanTargetBeforeCopy - 清除目標
boolean. 預設值：false。

指定 true 複製檔案之前清除目的地資料夾。

skipCACheck - 測試憑證
boolean. 選擇性。使用時機 Destination = AzureVMs。預設值：true。

將檔案從中繼記憶體 Blob 複製到 Azure VM 時，WinRM 需要 HTTPS 傳輸的憑證。

如果您使用自我簽署憑證，請指定 true 來防止程式使用受信任的 CA 驗證憑證。

工作控制選項

除了工作輸入之外，所有工作都有控制選項。如需詳細資訊，請參閱控件選項和一般工作屬性。

輸出變數

此工作會定義下列輸出變數，您可以在下游步驟、作業和階段中取用這些變數。

StorageContainerUri
檔案複製到其中的容器 URI。只有在選取的目的地是 Azure Blob 時才有效。

StorageContainerSasToken
檔案複製到其中的容器 SasToken。只有在選取的目的地是 Azure Blob 時才有效。

備註

AzureFileCopy@5支援 10.12.2 版 AzCopy.exe。

注意

您可以封鎖在記憶體帳戶上使用記憶體帳戶金鑰和 SAS 令牌。在這些情況下，無法使用依賴 SAS 令牌的AzureFileCopy@5 工作。

AzureFileCopy@6工作會改用 Azure RBAC 來存取 Blob 記憶體。這需要用來具有適當 RBAC 角色的服務聯機身分識別，例如記憶體 Blob 數據參與者。請參閱指派 Azure 角色以存取 blob 資料。

AzureFileCopy@6工作也支援使用工作負載身分識別同盟的服務連線。

注意

此工作是以 PowerShell 撰寫， 只有在 Windows 代理程式上執行時才有效。如果您的管線需要 Linux 代理程式，而且需要將檔案複製到 Azure 記憶體帳戶，請考慮在 Azure CLI 工作中執行az storage blob命令作為替代方案。

工作是用來複製應用程式檔和其他必要成品，以便安裝應用程式;例如 PowerShell 腳本、PowerShell-DSC 模組等等。

當目標為 Azure VM 時，檔案會先複製到自動產生的 Azure Blob 容器，然後下載到 VM。成功將檔案複製到 VM 之後，就會刪除容器。

此工作會使用 AzCopy，這是專為快速將數據從 Azure 記憶體帳戶複製到 Azure 記憶體帳戶而建置的命令行公用程式。 Azure 檔案複製工作的第 5 版會使用 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 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

如果已建立 VM 而不開啟 WinRM HTTPS 連接埠，請執行下列動作：

設定輸入存取規則，以允許每個 VM 連接埠 5986 上的 HTTPS。
停用 UAC遠端限制。
以 簡單形式的使用者 名稱指定工作認證，以不使用任何網域部分的系統管理員層級登入來存取 VM。
在執行自動化代理程式的電腦上安裝憑證。
如果您使用自我簽署憑證，請設定工作的 [測試憑證 ] 參數。

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

針對 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 虛擬機？

請確定您使用的是第 5 版的 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 位址。

範例

trigger:
- main

pool:
  vmImage: windows-latest

steps:
- task: AzureFileCopy@5
  inputs:
    SourcePath: 'Readme.md'
    azureSubscription: 'MyAzureSubscription'
    Destination: 'AzureBlob'
    storage: 'MyStorage'
    ContainerName: 'MyContainerName'
  name: AzureFileCopy
  
- script: | 
    echo $(AzureFileCopy.StorageContainerUri)
    echo $(AzureFileCopy.StorageContainerSasToken)

規格需求

需求	描述
管線類型	YAML、傳統組建、傳統版本
在上執行	Agent、DeploymentGroup
要求	自我裝載代理程式必須具備符合下列需求的功能，才能執行使用此工作的作業：azureps
Capabilities	此工作不符合作業中後續工作的任何需求。
命令限制	任何
可設定變數	任何
代理程式版本	1.103.0 或更新版本
工作類別	部署