開始使用 AzCopyGet started with AzCopy

AzCopy 是命令列公用程式,可讓您在儲存體帳戶之間複製 Blob 或檔案。AzCopy is a command-line utility that you can use to copy blobs or files to or from a storage account. 本文可協助您下載 AzCopy、連線到您的儲存體帳戶,然後傳輸檔案。This article helps you download AzCopy, connect to your storage account, and then transfer files.

注意

AzCopy V10是目前支援的 AzCopy 版本。AzCopy V10 is the currently supported version of AzCopy.

如果您需要使用舊版的 AzCopy,請參閱本文的使用舊版 AzCopy一節。If you need to use a previous version of AzCopy, see the Use the previous version of AzCopy section of this article.

下載 AzCopyDownload AzCopy

首先,將 AzCopy V10 可執行檔下載到您電腦上的任何目錄。First, download the AzCopy V10 executable file to any directory on your computer. AzCopy V10 只是一個可執行檔,因此沒有要安裝的東西。AzCopy V10 is just an executable file, so there's nothing to install.

這些檔案會壓縮成 zip 檔案, (Windows 和 Mac) 或 (Linux) 的 tar 檔案。These files are compressed as a zip file (Windows and Mac) or a tar file (Linux). 若要在 Linux 上下載並解壓縮 tar 檔案,請參閱 Linux 散發套件的檔。To download and decompress the tar file on Linux, see the documentation for your Linux distribution.

注意

如果您想要將資料複製到您的Azure 資料表儲存體服務,請安裝AzCopy 7.3 版If you want to copy data to and from your Azure Table storage service, then install AzCopy version 7.3.

執行 AzCopyRun AzCopy

為了方便起見,請考慮將 AzCopy 可執行檔的目錄位置新增至您的系統路徑,以方便使用。For convenience, consider adding the directory location of the AzCopy executable to your system path for ease of use. 如此一來,您就可以 azcopy 從系統上的任何目錄進行輸入。That way you can type azcopy from any directory on your system.

如果您選擇不要將 AzCopy 目錄新增至您的路徑,則必須將目錄變更為 AzCopy 可執行檔的位置,並 azcopy .\azcopy 在 Windows PowerShell 命令提示字元中輸入或。If you choose not to add the AzCopy directory to your path, you'll have to change directories to the location of your AzCopy executable and type azcopy or .\azcopy in Windows PowerShell command prompts.

若要查看命令清單,請輸入, azcopy -h 然後按 enter 鍵。To see a list of commands, type azcopy -h and then press the ENTER key.

若要瞭解特定命令,只要包含命令的名稱 (例如: azcopy list -h) 。To learn about a specific command, just include the name of the command (For example: azcopy list -h).

內嵌說明

若要尋找每個命令和命令參數的詳細參考檔,請參閱azcopyTo find detailed reference documentation for each command and command parameter, see azcopy

注意

身為 Azure 儲存體帳戶的擁有者,您不會自動獲指派存取資料的許可權。As an owner of your Azure Storage account, you aren't automatically assigned permissions to access data. 您必須先決定要如何將授權認證提供給儲存體服務,才可以執行任何有意義的 AzCopy。Before you can do anything meaningful with AzCopy, you need to decide how you'll provide authorization credentials to the storage service.

選擇您要如何提供授權認證Choose how you'll provide authorization credentials

您可以使用 Azure Active Directory (AD) ,或使用共用存取簽章 (SAS) token 來提供授權認證。You can provide authorization credentials by using Azure Active Directory (AD), or by using a Shared Access Signature (SAS) token.

使用此表格作為指南:Use this table as a guide:

儲存體類型Storage type 目前支援的授權方法Currently supported method of authorization
Blob 儲存體Blob storage Azure AD & SASAzure AD & SAS
**Blob 儲存體 (階層式命名空間) **Blob storage (hierarchical namespace) Azure AD & SASAzure AD & SAS
檔案儲存體File storage 僅限 SASSAS only

選項1:使用 Azure Active DirectoryOption 1: Use Azure Active Directory

藉由使用 Azure Active Directory,您可以只提供認證一次,而不需要將 SAS 權杖附加至每個命令。By using Azure Active Directory, you can provide credentials once instead of having to append a SAS token to each command.

注意

在目前版本中,如果您打算在儲存體帳戶之間複製 blob,則必須將 SAS 權杖附加至每個來源 URL。In the current release, if you plan to copy blobs between storage accounts, you'll have to append a SAS token to each source URL. 您只能從目的地 URL 省略 SAS 權杖。You can omit the SAS token only from the destination URL. 如需範例,請參閱在儲存體帳戶之間複製 blobFor examples, see Copy blobs between storage accounts.

您所需的授權層級取決於您是否計畫上傳檔案,或只是下載檔案。The level of authorization that you need is based on whether you plan to upload files or just download them.

如果您只想要下載檔案,請確認儲存體 Blob 資料讀取器已指派給您的使用者身分識別、受控識別或服務主體。If you just want to download files, then verify that the Storage Blob Data Reader has been assigned to your user identity, managed identity, or service principal.

使用者身分識別、受控識別和服務主體都是一種安全性主體類型,因此我們將在本文的其餘部分使用「安全性主體」一詞。User identities, managed identities, and service principals are each a type of security principal, so we'll use the term security principal for the remainder of this article.

如果您想要上傳檔案,請確認其中一個角色已指派給您的安全性主體:If you want to upload files, then verify that one of these roles has been assigned to your security principal:

這些角色可以指派給任何範圍內的安全性主體:These roles can be assigned to your security principal in any of these scopes:

  • 容器 (檔案系統) Container (file system)
  • 儲存體帳戶Storage account
  • 資源群組Resource group
  • 訂用帳戶Subscription

若要瞭解如何驗證和指派角色,請參閱在 Azure 入口網站中使用 RBAC 授與 Azure blob 和佇列資料的存取權To learn how to verify and assign roles, see Grant access to Azure blob and queue data with RBAC in the Azure portal.

注意

請記住,RBAC 角色指派最多可能需要五分鐘的時間來傳播。Keep in mind that RBAC role assignments can take up to five minutes to propagate.

如果您的安全性主體已新增至目標容器或目錄 (ACL) 的存取控制清單,則您不需要將這些角色指派給您的安全性主體。You don't need to have one of these roles assigned to your security principal if your security principal is added to the access control list (ACL) of the target container or directory. 在 ACL 中,您的安全性主體需要目標目錄的寫入權限,以及容器和每個父目錄的執行許可權。In the ACL, your security principal needs write permission on the target directory, and execute permission on container and each parent directory.

若要深入瞭解,請參閱Azure Data Lake Storage Gen2 中的存取控制To learn more, see Access control in Azure Data Lake Storage Gen2.

驗證使用者身分識別Authenticate a user identity

在確認您的使用者身分識別已獲得必要的授權層級之後,請開啟命令提示字元,輸入下列命令,然後按 ENTER 鍵。After you've verified that your user identity has been given the necessary authorization level, open a command prompt, type the following command, and then press the ENTER key.

azcopy login

如果您隸屬于多個組織,請包括儲存體帳戶所屬組織的租使用者識別碼。If you belong to more than one organization, include the tenant ID of the organization to which the storage account belongs.

azcopy login --tenant-id=<tenant-id>

將預留位置取代為 <tenant-id> 儲存體帳戶所屬組織的租使用者識別碼。Replace the <tenant-id> placeholder with the tenant ID of the organization to which the storage account belongs. 若要尋找租使用者識別碼,請在 Azure 入口網站中選取 [ Azure Active Directory > 屬性] > [目錄識別碼]。To find the tenant ID, select Azure Active Directory > Properties > Directory ID in the Azure portal.

此命令傳回驗證碼和網站的 URL。This command returns an authentication code and the URL of a website. 開啟網站,提供程式碼,然後選擇 [下一步]**** 按鈕。Open the website, provide the code, and then choose the Next button.

建立容器

隨即會出現登入視窗。A sign-in window will appear. 在該視窗中,使用您的 Azure 帳戶認證登入 Azure 帳戶。In that window, sign into your Azure account by using your Azure account credentials. 順利登入之後,您可以關閉瀏覽器視窗,然後開始使用 AzCopy。After you've successfully signed in, you can close the browser window and begin using AzCopy.

驗證服務主體Authenticate a service principal

如果您打算在不需使用者互動的腳本內使用 AzCopy,特別是在內部部署執行時,這是很好的選擇。This is a great option if you plan to use AzCopy inside of a script that runs without user interaction, particularly when running on-premises. 如果您打算在 Azure 中執行的 Vm 上執行 AzCopy,受控服務識別會比較容易管理。If you plan to run AzCopy on VMs that run in Azure, a managed service identity is easier to administer. 若要深入瞭解,請參閱本文的驗證受控識別一節。To learn more, see the Authenticate a managed identity section of this article.

執行腳本之前,您必須以互動方式至少一次登入,讓您可以使用服務主體的認證來提供 AzCopy。Before you run a script, you have to sign-in interactively at least one time so that you can provide AzCopy with the credentials of your service principal. 這些認證會儲存在安全的加密檔案中,讓您的腳本不需要提供敏感性資訊。Those credentials are stored in a secured and encrypted file so that your script doesn't have to provide that sensitive information.

您可以使用用戶端密碼或與服務主體的應用程式註冊相關聯之憑證的密碼,來登入您的帳戶。You can sign into your account by using a client secret or by using the password of a certificate that is associated with your service principal's app registration.

若要深入瞭解如何建立服務主體,請參閱如何:使用入口網站建立可存取資源的 Azure AD 應用程式和服務主體To learn more about creating service principal, see How to: Use the portal to create an Azure AD application and service principal that can access resources.

若要深入瞭解服務主體的一般資訊,請參閱Azure Active Directory 中的應用程式和服務主體物件To learn more about service principals in general, see Application and service principal objects in Azure Active Directory

使用用戶端密碼Using a client secret

首先,將 AZCOPY_SPA_CLIENT_SECRET 環境變數設定為服務主體之應用程式註冊的用戶端密碼。Start by setting the AZCOPY_SPA_CLIENT_SECRET environment variable to the client secret of your service principal's app registration.

注意

請務必從您的命令提示字元設定此值,而不是作業系統的環境變數設定。Make sure to set this value from your command prompt, and not in the environment variable settings of your operating system. 如此一來,此值僅適用于目前的會話。That way, the value is available only to the current session.

這個範例示範如何在 PowerShell 中執行這項操作。This example shows how you could do this in PowerShell.

$env:AZCOPY_SPA_CLIENT_SECRET="$(Read-Host -prompt "Enter key")"

注意

請考慮使用如下列範例所示的提示。Consider using a prompt as shown in this example. 如此一來,您的密碼就不會出現在主控台的命令歷程記錄中。That way, your password won't appear in your console's command history.

接下來,輸入下列命令,然後按 ENTER 鍵。Next, type the following command, and then press the ENTER key.

azcopy login --service-principal --certificate-path path-to-certificate-file --application-id application-id --tenant-id=tenant-id

<application-id>以服務主體之應用程式註冊的應用程式識別碼取代預留位置。Replace the <application-id> placeholder with the application ID of your service principal's app registration. 將預留位置取代為 <tenant-id> 儲存體帳戶所屬組織的租使用者識別碼。Replace the <tenant-id> placeholder with the tenant ID of the organization to which the storage account belongs. 若要尋找租使用者識別碼,請在 Azure 入口網站中選取 [ Azure Active Directory > 屬性] > [目錄識別碼]。To find the tenant ID, select Azure Active Directory > Properties > Directory ID in the Azure portal.

使用憑證Using a certificate

如果您想要使用自己的認證來進行授權,您可以將憑證上傳至您的應用程式註冊,然後使用該憑證登入。If you prefer to use your own credentials for authorization, you can upload a certificate to your app registration, and then use that certificate to login.

除了將憑證上傳至您的應用程式註冊之外,您還需要將憑證的複本儲存到 AzCopy 執行所在的電腦或 VM。In addition to uploading your certificate to your app registration, you'll also need to have a copy of the certificate saved to the machine or VM where AzCopy will be running. 這個憑證複本應該在中。PFX 或。PEM 格式,而且必須包含私密金鑰。This copy of the certificate should be in .PFX or .PEM format, and must include the private key. 私密金鑰應受密碼保護。The private key should be password-protected. 如果您使用的是 Windows,而且您的憑證只存在於憑證存放區中,請務必將該憑證匯出到 PFX 檔案, (包括私密金鑰) 。If you're using Windows, and your certificate exists only in a certificate store, make sure to export that certificate to a PFX file (including the private key). 如需指引,請參閱Export-get-pfxcertificateFor guidance, see Export-PfxCertificate

接下來,將 AZCOPY_SPA_CERT_PASSWORD 環境變數設定為憑證密碼。Next, set the AZCOPY_SPA_CERT_PASSWORD environment variable to the certificate password.

注意

請務必從您的命令提示字元設定此值,而不是作業系統的環境變數設定。Make sure to set this value from your command prompt, and not in the environment variable settings of your operating system. 如此一來,此值僅適用于目前的會話。That way, the value is available only to the current session.

這個範例示範如何在 PowerShell 中執行這項工作。This example shows how you could do this task in PowerShell.

$env:AZCOPY_SPA_CERT_PASSWORD="$(Read-Host -prompt "Enter key")"

接下來,輸入下列命令,然後按 ENTER 鍵。Next, type the following command, and then press the ENTER key.

azcopy login --service-principal --certificate-path <path-to-certificate-file> --tenant-id=<tenant-id>

<path-to-certificate-file> 預留位置取代為憑證檔案的相對或完整路徑。Replace the <path-to-certificate-file> placeholder with the relative or fully-qualified path to the certificate file. AzCopy 會儲存此憑證的路徑,但不會儲存憑證的複本,因此請務必將該憑證保留在原處。AzCopy saves the path to this certificate but it doesn't save a copy of the certificate, so make sure to keep that certificate in place. 將預留位置取代為 <tenant-id> 儲存體帳戶所屬組織的租使用者識別碼。Replace the <tenant-id> placeholder with the tenant ID of the organization to which the storage account belongs. 若要尋找租使用者識別碼,請在 Azure 入口網站中選取 [ Azure Active Directory > 屬性] > [目錄識別碼]。To find the tenant ID, select Azure Active Directory > Properties > Directory ID in the Azure portal.

注意

請考慮使用如下列範例所示的提示。Consider using a prompt as shown in this example. 如此一來,您的密碼就不會出現在主控台的命令歷程記錄中。That way, your password won't appear in your console's command history.

驗證受控識別Authenticate a managed identity

如果您打算在不需使用者互動的情況下執行的腳本內使用 AzCopy,而且腳本是從 Azure 虛擬機器 (VM) 執行,這就是絕佳的選項。This is a great option if you plan to use AzCopy inside of a script that runs without user interaction, and the script runs from an Azure Virtual Machine (VM). 使用此選項時,您不需要在 VM 上儲存任何認證。When using this option, you won't have to store any credentials on the VM.

您可以登入您的帳戶,方法是使用您在 VM 上啟用的全系統受控識別,或使用您已指派給 VM 的使用者指派受控識別的用戶端識別碼、物件識別碼或資源識別碼。You can sign into your account by using the a system-wide managed identity that you've enabled on your VM, or by using the client ID, Object ID, or Resource ID of a user-assigned managed identity that you've assigned to your VM.

若要深入瞭解如何啟用全系統受控識別或建立使用者指派的受控識別,請參閱使用 Azure 入口網站在 VM 上設定 Azure 資源的受控識別。To learn more about how to enable a system-wide managed identity or create a user-assigned managed identity, see Configure managed identities for Azure resources on a VM using the Azure portal.

使用全系統受控識別Using a system-wide managed identity

首先,請確定您已在 VM 上啟用全系統受控識別。First, make sure that you've enabled a system-wide managed identity on your VM. 請參閱系統指派的受控識別See System-assigned managed identity.

然後,在您的命令主控台中輸入下列命令,然後按 ENTER 鍵。Then, in your command console, type the following command, and then press the ENTER key.

azcopy login --identity
使用使用者指派的受控識別Using a user-assigned managed identity

首先,請確定您已在 VM 上啟用使用者指派的受控識別。First, make sure that you've enabled a user-assigned managed identity on your VM. 請參閱使用者指派的受控識別See User-assigned managed identity.

然後,在您的命令主控台中,輸入下列任何命令,然後按 ENTER 鍵。Then, in your command console, type any of the following commands, and then press the ENTER key.

azcopy login --identity --identity-client-id "<client-id>"

<client-id>以使用者指派的受控識別的用戶端識別碼取代預留位置。Replace the <client-id> placeholder with the client ID of the user-assigned managed identity.

azcopy login --identity --identity-object-id "<object-id>"

<object-id>以使用者指派的受控識別的物件識別碼取代預留位置。Replace the <object-id> placeholder with the object ID of the user-assigned managed identity.

azcopy login --identity --identity-resource-id "<resource-id>"

<resource-id>以使用者指派受控識別的資源識別碼取代預留位置。Replace the <resource-id> placeholder with the resource ID of the user-assigned managed identity.

選項2:使用 SAS 權杖Option 2: Use a SAS token

您可以將 SAS 權杖附加至在 AzCopy 命令中使用的每個來源或目的地 URL。You can append a SAS token to each source or destination URL that use in your AzCopy commands.

此範例命令會以遞迴方式將資料從本機目錄複寫到 blob 容器。This example command recursively copies data from a local directory to a blob container. 將虛構的 SAS 權杖附加至容器 URL 的結尾。A fictitious SAS token is appended to the end of the of the container URL.

azcopy copy "C:\local\path" "https://account.blob.core.windows.net/mycontainer1/?sv=2018-03-28&ss=bjqt&srt=sco&sp=rwddgcup&se=2019-05-01T05:01:17Z&st=2019-04-30T21:01:17Z&spr=https&sig=MGCXiyEzbtttkr3ewJIh2AR8KrghSy1DGM9ovN734bQF4%3D" --recursive=true

若要深入瞭解 SAS 權杖和如何取得它,請參閱使用共用存取簽章 (SAS) To learn more about SAS tokens and how to obtain one, see Using shared access signatures (SAS).

傳輸檔案Transfer files

在驗證您的身分識別或取得 SAS 權杖之後,您就可以開始傳輸檔案。After you've authenticated your identity or obtained a SAS token, you can begin transferring files.

若要尋找範例命令,請參閱任何一篇文章。To find example commands, see any of these articles.

在腳本中使用 AzCopyUse AzCopy in a script

經過一段時間後,AzCopy下載連結會指向新版本的 AzCopy。Over time, the AzCopy download link will point to new versions of AzCopy. 如果您的腳本下載 AzCopy,當較新版本的 AzCopy 修改腳本所相依的功能時,腳本可能會停止運作。If your script downloads AzCopy, the script might stop working if a newer version of AzCopy modifies features that your script depends upon.

若要避免這些問題,請取得靜態 (未變更的) 連結到目前版本的 AzCopy。To avoid these issues, obtain a static (un-changing) link to the current version of AzCopy. 如此一來,您的腳本就會在每次執行時下載相同的 AzCopy 版本。That way, your script downloads the same exact version of AzCopy each time that it runs.

若要取得連結,請執行此命令:To obtain the link, run this command:

作業系統Operating system 命令Command
LinuxLinux curl -s -D- https://aka.ms/downloadazcopy-v10-linux | grep ^Location
WindowsWindows (curl https://aka.ms/downloadazcopy-v10-windows -MaximumRedirection 0 -ErrorAction silentlycontinue).headers.location

注意

針對 Linux, --strip-components=1tar 命令上會移除包含版本名稱的最上層資料夾,並改為直接將二進位檔解壓縮至目前的資料夾。For Linux, --strip-components=1 on the tar command removes the top-level folder that contains the version name, and instead extracts the binary directly into the current folder. 如此一來,只要更新 URL,就能以新版本更新腳本 azcopy wgetThis allows the script to be updated with a new version of azcopy by only updating the wget URL.

此 URL 會出現在此命令的輸出中。The URL appears in the output of this command. 接著,您的腳本就可以使用該 URL 來下載 AzCopy。Your script can then download AzCopy by using that URL.

作業系統Operating system 命令Command
LinuxLinux wget -O azcopy_v10.tar.gz https://aka.ms/downloadazcopy-v10-linux && tar -xf azcopy_v10.tar.gz --strip-components=1
WindowsWindows Invoke-WebRequest https://azcopyvnext.azureedge.net/release20190517/azcopy_windows_amd64_10.1.2.zip -OutFile azcopyv10.zip <<Unzip here>>

在 SAS 權杖中換用特殊字元Escape special characters in SAS tokens

在副檔名為的批次檔中 .cmd ,您必須將 % 出現在 SAS 權杖中的字元加以轉義。In batch files that have the .cmd extension, you'll have to escape the % characters that appear in SAS tokens. 若要這麼做,您可以在 % SAS 權杖字串的現有字元旁新增額外的字元 %You can do that by adding an additional % character next to existing % characters in the SAS token string.

使用 Jenkins 執行腳本Run scripts by using Jenkins

如果您打算使用Jenkins來執行腳本,請務必將下列命令放在腳本的開頭。If you plan to use Jenkins to run scripts, make sure to place the following command at the beginning of the script.

/usr/bin/keyctl new_session

在 Azure 儲存體總管中使用 AzCopyUse AzCopy in Azure Storage Explorer

儲存體總管使用 AzCopy 來執行其所有資料傳輸作業。Storage Explorer uses AzCopy to perform all of its data transfer operations. 如果您想要利用 AzCopy 的效能優勢,可以使用儲存體總管,但是您想要使用圖形化使用者介面,而不是命令列來與您的檔案互動。You can use Storage Explorer if you want to leverage the performance advantages of AzCopy, but you prefer to use a graphical user interface rather than the command line to interact with your files.

儲存體總管會使用您的帳戶金鑰來執行作業,因此當您登入儲存體總管之後,就不需要提供額外的授權認證。Storage Explorer uses your account key to perform operations, so after you sign into Storage Explorer, you won't need to provide additional authorization credentials.

使用舊版的 AzCopyUse the previous version of AzCopy

如果您需要使用舊版的 AzCopy,請參閱下列其中一個連結:If you need to use the previous version of AzCopy, see either of the following links:

對 AzCopy 進行設定、最佳化及疑難排解Configure, optimize, and troubleshoot AzCopy

請參閱設定、優化和疑難排解 AzCopySee Configure, optimize, and troubleshoot AzCopy

後續步驟Next steps

如果您有任何問題、問題或一般意見反應,請在 GitHub 頁面上提交。If you have questions, issues, or general feedback, submit them on GitHub page.