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

  • 發行項

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

注意

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

Syntax

# 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 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 。

指定可用來篩選檔案的前置詞。

範例：您可以附加組建編號，以篩選所有具有相同組建編號之 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 。
  • 不支援包含 username@domain.com 和 內建系統帳戶的 UPN 格式，例如 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支援 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 儲存體帳戶而建置的命令列公用程式。 Azure 檔案複製工作第 4 版使用 AzCopy V10。

Azure 檔案複製第 3 版和更低版本會擷取 Azure 儲存體金鑰以提供存取權。 Azure 檔案複製第 4 版和更新版本需要透過Microsoft Entra識別碼或 SAS 權杖授權 Azure 儲存體。 您可以使用服務主體和受控識別進行驗證。 針對受控識別，僅支援全系統受控識別。 所需的授權層級會顯示在選項 1：使用Microsoft Entra識別碼中。

若要動態部署包含虛擬機器的 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

如果 VM 建立時未開啟 WinRM HTTPS 埠，請執行下列動作：

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

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

  • 針對 Azure Resource Manager儲存體帳戶和 Azure Resource Manager VM，請使用Azure Resource Manager服務連線類型。 請參閱 使用服務主體將 Azure 資源群組部署自動化。

  • 使用Azure Resource Manager服務連線類型時，工作會自動篩選適當的較新 Azure Resource Manager儲存體帳戶和其他欄位。 例如，資源群組或雲端服務，以及 VM。

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

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

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

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

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

在複製之後，是否清除記錄檔和計畫檔案？

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

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

請確定您使用的是第 4 版的 Azure 檔案複製工作。 如果工作失敗，您可以新增建置步驟來執行 命令 azcopy cp "source-file-path" "destination-file-path" ，以取代來源和目的地值。

禁止錯誤：「AzCopy.exe 使用 Azure 檔案複製工作將檔案上傳至 Blob 儲存體時，以非零結束代碼結束」

每次觸發組建時，都會隨機指派裝載的代理程式，每次執行時 代理程式 IP 位址 都會不同。 如果這些 IP 位址不在您允許的 IP 清單中，Azure DevOps 與儲存體帳戶之間的通訊會失敗。 在這類案例中，請遵循所述的步驟：

  1. 使用 Azure CLI 新增建置步驟，以在執行時間識別 Microsoft 託管組建代理程式的 IP 位址。 它會將 IP 位址新增至 Azure 儲存體帳戶上的 [網路] 規則。
  2. 執行 Azure 儲存體帳戶的建置步驟。
  3. 使用 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
Capabilities 此工作不符合作業中後續工作的任何需求。
命令限制 任何
可設定變數 任何
代理程式版本 1.103.0 或更新版本
工作類別 部署