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

發行項
10/18/2022

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

Syntax

# Azure file copy v4
# Copy files to Azure Blob Storage or virtual machines.
- task: AzureFileCopy@4
  inputs:
    SourcePath: # string. Required. Source. 
    azureSubscription: # string. Required. Azure Subscription. 
    Destination: # 'AzureBlob' | 'AzureVMs'. Required. Destination Type. 
    storage: # string. Required. RM Storage Account. 
    #ContainerName: # string. Required when Destination = AzureBlob. Container Name. 
    #BlobPrefix: # string. Optional. Use when Destination = AzureBlob. Blob Prefix. 
    #resourceGroup: # string. 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) 。

選取目的地，可以是 Azure Blob 或 Azure VM。

storage - RM 儲存體帳戶
輸入別名： StorageAccountRM 。 string. 必要。

指定預先存在的 ARM 儲存體帳戶。它也可用來作為將檔案複製到 Azure VM 的媒介。

ContainerName - 容器名稱
string. 需要。 Destination = AzureBlob

用於上傳檔案的容器名稱。如果具有指定名稱的容器不存在於指定的儲存體帳戶中，則會自動建立該容器。
如果您需要在容器內建立虛擬目錄，請使用下方的 Blob 前置詞輸入。
範例：如果您的目標位置是 https://myaccount.blob.core.windows.net/mycontainer/vd1/vd2/ ，請將 mycontainer 指定為容器名稱，並將 vd1/vd2 指定為 Blob 前置詞。

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 。

電腦名稱稱或標記名稱的清單，可識別工作的目的機器。篩選準則可以是：

Azure 資源群組的名稱。
上一個工作的輸出變數。
以逗號分隔的標籤名稱或電腦名稱稱清單。使用電腦名稱稱時的格式是電腦 FQDN 或 IP 位址的逗號分隔清單。將篩選的標籤名稱指定為 {TagName}：{Value} 範例： Role:DB;OS:Win8.1

vmsAdminUserName - 管理員登入
string. 需要。 Destination = AzureVMs

具有所有目標 VM 之系統管理許可權的帳戶使用者名稱。

支援使用者名稱、domain\username、machine-name\username 和 .\username等格式。
不支援 UPN 格式， username@domain.com 例如和內建的系統帳戶，例如 NT Authority\System 。

vmsAdminPassword - 密碼
string. 需要。 Destination = AzureVMs

指定為管理員 Login參數之帳戶的密碼。針對 [ 變數 ] 索引標籤中定義的變數使用掛鎖圖示來保護值，並在這裡插入變數名稱。

TargetPath - 目的地資料夾
string. 需要。 Destination = AzureVMs

將複製檔案的 Azure VM 中的資料夾。支援和 $env:systemroot 之類的 $env:windir 環境變數。範例：$env:windir\FabrikamFiber\Web 和 c:\FabrikamFiber

AdditionalArgumentsForBlobCopy - 將檔案上傳至 Blob) 的選擇性引數 (
string.

您想要傳遞至 AzCopy.exe 程式的任何引數，以供上傳至 Blob 並下載至 VM 時使用。如需詳細資料，請參閱使用 AzCopy 命令列公用程式傳輸資料。如果您使用僅支援 Azure 分頁 Blob 的進階儲存體帳戶，則傳遞 '--blob-type=PageBlob' 作為其他引數。預設引數為 --log-level=INFO (預設) 和 --recursive (，只有在容器名稱未$root) 時。

AdditionalArgumentsForVMCopy - 將檔案下載至 VM) 的選擇性引數 (
string. 選擇性。使用時 Destination = AzureVMs 。

選擇性AzCopy.exe引數，這些引數將在下載至 VM 時套用，例如 --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 虛擬機器上執行複製作業。

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

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

將它設定為 true 會將檔案平行複製到目的電腦。

CleanTargetBeforeCopy - 清除目標
boolean. 選擇性。使用時機 Destination = AzureVMs 。預設值：false。

將它設定為 true 會在複製檔案之前清除目的地資料夾。

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

將檔案從中繼儲存體 Blob 複製到 Azure VM 時，WinRM 需要 HTTPS 傳輸的憑證。如果您設定使用自我簽署憑證，請設定此選項，以防止程式向受信任的憑證授權單位單位驗證憑證， (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 資源群組，請使用 Azure 資源群組部署工作。此工作具有範例範本，可執行必要的作業，在虛擬機器上設定 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 埠，請遵循下列步驟：

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

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

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

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

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

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

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

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

記錄檔和計畫檔案會在複製之後清除嗎？

工作不會刪除記錄檔和計畫檔案。若要確實清除檔案，您可以使用此命令在工作流程中新增 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，並在 Azure 儲存體帳戶的網路規則中新增 IP 位址。
執行 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
Capabilities	此工作不符合作業中後續工作的任何需求。
命令限制	任意
Settable 變數	任意
代理程式版本	1.103.0 或更新版本
工作類別	部署