Introdução ao AzCopyGet started with AzCopy

AzCopy é um utilitário de linha de comando que você pode usar para copiar BLOBs ou arquivos de ou para uma conta de armazenamento.AzCopy is a command-line utility that you can use to copy blobs or files to or from a storage account. Este artigo ajuda você a baixar o AzCopy, conectar-se à sua conta de armazenamento e, em seguida, transferir arquivos.This article helps you download AzCopy, connect to your storage account, and then transfer files.

Observação

AzCopy V10 é a versão com suporte no momento do AzCopy.AzCopy V10 is the currently supported version of AzCopy.

Se você precisar usar o AzCopy v 8.1, consulte a seção usar a versão anterior do AzCopy deste artigo.If you need to use AzCopy v8.1, see the Use the previous version of AzCopy section of this article.

Baixar o AzCopyDownload AzCopy

Primeiro, baixe o arquivo executável AzCopy V10 em qualquer diretório em seu computador.First, download the AzCopy V10 executable file to any directory on your computer. AzCopy V10 é apenas um arquivo executável, portanto, não há nada a ser instalado.AzCopy V10 is just an executable file, so there's nothing to install.

Esses arquivos são compactados como um arquivo zip (Windows e Mac) ou um arquivo tar (Linux).These files are compressed as a zip file (Windows and Mac) or a tar file (Linux). Para baixar e descompactar o arquivo tar no Linux, consulte a documentação para sua distribuição do Linux.To download and decompress the tar file on Linux, see the documentation for your Linux distribution.

Observação

Se você quiser copiar dados de e para o serviço de armazenamento de tabelas do Azure , instale o AzCopy versão 7,3.If you want to copy data to and from your Azure Table storage service, then install AzCopy version 7.3.

Executar AzCopyRun AzCopy

Para sua conveniência, considere adicionar o local do diretório do executável AzCopy ao caminho do sistema para facilitar o uso.For convenience, consider adding the directory location of the AzCopy executable to your system path for ease of use. Dessa forma, você pode digitar azcopy de qualquer diretório em seu sistema.That way you can type azcopy from any directory on your system.

Se optar por não adicionar o diretório AzCopy ao seu caminho, você precisará alterar os diretórios para o local do executável do AzCopy e digitar azcopy ou .\azcopy nos prompts de comando do 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.

Para ver uma lista de comandos, digite azcopy -h e pressione a tecla ENTER.To see a list of commands, type azcopy -h and then press the ENTER key.

Para saber mais sobre um comando específico, apenas inclua o nome do comando (por exemplo: azcopy list -h).To learn about a specific command, just include the name of the command (For example: azcopy list -h).

Ajuda embutida

Para encontrar a documentação de referência detalhada para cada comando e parâmetro de comando, consulte azcopyTo find detailed reference documentation for each command and command parameter, see azcopy

Observação

Como proprietário de sua conta de armazenamento do Azure, você não recebe automaticamente permissões para acessar dados.As an owner of your Azure Storage account, you aren't automatically assigned permissions to access data. Antes de poder fazer qualquer coisa significativa com o AzCopy, você precisa decidir como fornecerá credenciais de autorização para o serviço de armazenamento.Before you can do anything meaningful with AzCopy, you need to decide how you'll provide authorization credentials to the storage service.

Escolha como você fornecerá credenciais de autorizaçãoChoose how you'll provide authorization credentials

Você pode fornecer credenciais de autorização usando o Azure Active Directory (AD) ou usando um token SAS (assinatura de acesso compartilhado).You can provide authorization credentials by using Azure Active Directory (AD), or by using a Shared Access Signature (SAS) token.

Use esta tabela como um guia:Use this table as a guide:

Tipo de armazenamentoStorage type Método de autorização atualmente com suporteCurrently supported method of authorization
Armazenamento de BlobsBlob storage SAS do Azure AD &Azure AD & SAS
Armazenamento de BLOBs (namespace hierárquico)Blob storage (hierarchical namespace) SAS do Azure AD &Azure AD & SAS
Armazenamento de arquivosFile storage Somente SASSAS only

Opção 1: usar Azure Active DirectoryOption 1: Use Azure Active Directory

Usando Azure Active Directory, você pode fornecer credenciais uma vez, em vez de ter que acrescentar um token SAS a cada comando.By using Azure Active Directory, you can provide credentials once instead of having to append a SAS token to each command.

Observação

Na versão atual, se você planeja copiar BLOBs entre contas de armazenamento, precisará acrescentar um token SAS a cada URL de origem.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. Você pode omitir o token SAS somente da URL de destino.You can omit the SAS token only from the destination URL. Para obter exemplos, consulte copiar BLOBs entre contas de armazenamento.For examples, see Copy blobs between storage accounts.

O nível de autorização de que você precisa se baseia se você planeja carregar arquivos ou apenas baixá-los.The level of authorization that you need is based on whether you plan to upload files or just download them.

Se você apenas deseja baixar arquivos, verifique se o leitor de dados de blob de armazenamento foi atribuído à sua identidade de usuário, identidade gerenciada ou entidade de serviço.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.

Identidades de usuário, identidades gerenciadas e entidades de serviço são cada um tipo de entidade de segurança, portanto, usaremos a entidade de segurança do termo para o restante deste artigo.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.

Se você quiser carregar arquivos, verifique se uma dessas funções foi atribuída à sua entidade de segurança:If you want to upload files, then verify that one of these roles has been assigned to your security principal:

Essas funções podem ser atribuídas à entidade de segurança em qualquer um desses escopos:These roles can be assigned to your security principal in any of these scopes:

  • Contêiner (sistema de arquivos)Container (file system)
  • Conta de armazenamentoStorage account
  • Grupo de recursosResource group
  • SubscriptionSubscription

Para saber como verificar e atribuir funções, consulte conceder acesso ao blob do Azure e dados de fila com RBAC no portal do Azure.To learn how to verify and assign roles, see Grant access to Azure blob and queue data with RBAC in the Azure portal.

Observação

Tenha em mente que as atribuições de função do RBAC podem levar até cinco minutos para serem propagadas.Keep in mind that RBAC role assignments can take up to five minutes to propagate.

Você não precisará ter uma dessas funções atribuídas à entidade de segurança se sua entidade de segurança for adicionada à lista de controle de acesso (ACL) do contêiner ou diretório de destino.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. Na ACL, sua entidade de segurança precisa de permissão de gravação no diretório de destino e permissão de execução no contêiner e em cada diretório pai.In the ACL, your security principal needs write permission on the target directory, and execute permission on container and each parent directory.

Para saber mais, consulte controle de acesso em Azure data Lake Storage Gen2.To learn more, see Access control in Azure Data Lake Storage Gen2.

Autenticar uma identidade de usuárioAuthenticate a user identity

Depois de verificar se a identidade do usuário recebeu o nível de autorização necessário, abra um prompt de comando, digite o comando a seguir e pressione a tecla 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

Se você pertencer a mais de uma organização, inclua a ID de locatário da organização à qual a conta de armazenamento pertence.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>

Substitua o espaço reservado <tenant-id> pela ID de locatário da organização à qual a conta de armazenamento pertence.Replace the <tenant-id> placeholder with the tenant ID of the organization to which the storage account belongs. Para localizar a ID de locatário, selecione Azure Active Directory Propriedades de > > ID de diretório no portal do Azure.To find the tenant ID, select Azure Active Directory > Properties > Directory ID in the Azure portal.

Esse comando retorna um código de autenticação e a URL de um site.This command returns an authentication code and the URL of a website. Abra o site, forneça o código e, em seguida, escolha o botão Avançar.Open the website, provide the code, and then choose the Next button.

Criar um contêiner

Uma janela de entrada será exibida.A sign-in window will appear. Nessa janela, entre em sua conta do Azure usando suas credenciais de conta do Azure.In that window, sign into your Azure account by using your Azure account credentials. Depois de entrar com êxito, feche a janela do navegador e comece a usar o AzCopy.After you've successfully signed in, you can close the browser window and begin using AzCopy.

Autenticar uma entidade de serviçoAuthenticate a service principal

Essa é uma ótima opção se você planeja usar o AzCopy dentro de um script que é executado sem interação do usuário, especialmente quando executado no local.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. Se você planeja executar o AzCopy em VMs que são executadas no Azure, uma identidade de serviço gerenciada é mais fácil de administrar.If you plan to run AzCopy on VMs that run in Azure, a managed service identity is easier to administer. Para saber mais, consulte a seção autenticar uma identidade gerenciada deste artigo.To learn more, see the Authenticate a managed identity section of this article.

Antes de executar um script, você precisa entrar interativamente pelo menos uma vez para que possa fornecer AzCopy com as credenciais de sua entidade de serviço.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. Essas credenciais são armazenadas em um arquivo seguro e criptografado para que o script não precise fornecer essas informações confidenciais.Those credentials are stored in a secured and encrypted file so that your script doesn't have to provide that sensitive information.

Você pode entrar em sua conta usando um segredo do cliente ou usando a senha de um certificado associado ao registro do aplicativo da sua entidade de serviço.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.

Para saber mais sobre como criar a entidade de serviço, consulte como: usar o portal para criar um aplicativo do Azure AD e uma entidade de serviço que possa acessar recursos.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.

Para saber mais sobre as entidades de serviço em geral, consulte objetos de aplicativo e entidade de serviço no Azure Active DirectoryTo learn more about service principals in general, see Application and service principal objects in Azure Active Directory

Usando um segredo do clienteUsing a client secret

Comece definindo a variável de ambiente AZCOPY_SPA_CLIENT_SECRET como o segredo do cliente do registro do aplicativo da sua entidade de serviço.Start by setting the AZCOPY_SPA_CLIENT_SECRET environment variable to the client secret of your service principal's app registration.

Observação

Certifique-se de definir esse valor no prompt de comando e não nas configurações de variável de ambiente do seu sistema operacional.Make sure to set this value from your command prompt, and not in the environment variable settings of your operating system. Dessa forma, o valor estará disponível somente para a sessão atual.That way, the value is available only to the current session.

Este exemplo mostra como você pode fazer isso no PowerShell.This example shows how you could do this in PowerShell.

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

Observação

Considere usar um prompt, conforme mostrado neste exemplo.Consider using a prompt as shown in this example. Dessa forma, sua senha não aparecerá no histórico de comandos do console.That way, your password won't appear in your console's command history.

Em seguida, digite o comando a seguir e pressione a tecla ENTER.Next, type the following command, and then press the ENTER key.

azcopy login --service-principal --application-id <application-id> --tenant-id=<tenant-id>

Substitua o espaço reservado <application-id> pela ID do aplicativo do registro do aplicativo da sua entidade de serviço.Replace the <application-id> placeholder with the application ID of your service principal's app registration. Substitua o espaço reservado <tenant-id> pela ID de locatário da organização à qual a conta de armazenamento pertence.Replace the <tenant-id> placeholder with the tenant ID of the organization to which the storage account belongs. Para localizar a ID de locatário, selecione Azure Active Directory Propriedades de > > ID de diretório no portal do Azure.To find the tenant ID, select Azure Active Directory > Properties > Directory ID in the Azure portal.

Usando um certificadoUsing a certificate

Se preferir usar suas próprias credenciais para autorização, você poderá carregar um certificado para o registro do aplicativo e, em seguida, usar esse certificado para fazer logon.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.

Além de carregar seu certificado para o registro do aplicativo, você também precisará ter uma cópia do certificado salvo no computador ou na VM em que o AzCopy será executado.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. Esta cópia do certificado deve estar no. PFX ou. O formato PEM e deve incluir a chave privada.This copy of the certificate should be in .PFX or .PEM format, and must include the private key. A chave privada deve ser protegida por senha.The private key should be password-protected. Se você estiver usando o Windows e seu certificado existir somente em um repositório de certificados, certifique-se de exportar esse certificado para um arquivo PFX (incluindo a chave privada).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). Para obter diretrizes, consulte Export-PfxCertificateFor guidance, see Export-PfxCertificate

Em seguida, defina a variável de ambiente AZCOPY_SPA_CERT_PASSWORD como a senha do certificado.Next, set the AZCOPY_SPA_CERT_PASSWORD environment variable to the certificate password.

Observação

Certifique-se de definir esse valor no prompt de comando e não nas configurações de variável de ambiente do seu sistema operacional.Make sure to set this value from your command prompt, and not in the environment variable settings of your operating system. Dessa forma, o valor estará disponível somente para a sessão atual.That way, the value is available only to the current session.

Este exemplo mostra como você pode executar essa tarefa no PowerShell.This example shows how you could do this task in PowerShell.

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

Em seguida, digite o comando a seguir e pressione a tecla 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>

Substitua o espaço reservado <path-to-certificate-file> pelo caminho relativo ou totalmente qualificado para o arquivo de certificado.Replace the <path-to-certificate-file> placeholder with the relative or fully-qualified path to the certificate file. AzCopy salva o caminho para esse certificado, mas não salva uma cópia do certificado, portanto, certifique-se de manter esse certificado em vigor.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. Substitua o espaço reservado <tenant-id> pela ID de locatário da organização à qual a conta de armazenamento pertence.Replace the <tenant-id> placeholder with the tenant ID of the organization to which the storage account belongs. Para localizar a ID de locatário, selecione Azure Active Directory Propriedades de > > ID de diretório no portal do Azure.To find the tenant ID, select Azure Active Directory > Properties > Directory ID in the Azure portal.

Observação

Considere usar um prompt, conforme mostrado neste exemplo.Consider using a prompt as shown in this example. Dessa forma, sua senha não aparecerá no histórico de comandos do console.That way, your password won't appear in your console's command history.

Autenticar uma identidade gerenciadaAuthenticate a managed identity

Essa é uma ótima opção se você planeja usar o AzCopy dentro de um script que é executado sem interação do usuário e o script é executado de uma VM (máquina virtual) do Azure.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). Ao usar essa opção, você não precisará armazenar nenhuma credencial na VM.When using this option, you won't have to store any credentials on the VM.

Você pode entrar em sua conta usando a identidade gerenciada de todo o sistema que você habilitou em sua VM ou usando a ID do cliente, a ID de objeto ou a ID de recurso de uma identidade gerenciada atribuída pelo usuário que você atribuiu à sua 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.

Para saber mais sobre como habilitar uma identidade gerenciada em todo o sistema ou criar uma identidade gerenciada atribuída pelo usuário, consulte Configurar identidades gerenciadas para recursos do Azure em uma VM usando o portal do 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.

Usando uma identidade gerenciada em todo o sistemaUsing a system-wide managed identity

Primeiro, verifique se você habilitou uma identidade gerenciada em todo o sistema em sua VM.First, make sure that you've enabled a system-wide managed identity on your VM. Consulte identidade gerenciada atribuída pelo sistema.See System-assigned managed identity.

Em seguida, no console de comando, digite o comando a seguir e pressione a tecla ENTER.Then, in your command console, type the following command, and then press the ENTER key.

azcopy login --identity
Usando uma identidade gerenciada atribuída pelo usuárioUsing a user-assigned managed identity

Primeiro, verifique se você habilitou uma identidade gerenciada atribuída pelo usuário em sua VM.First, make sure that you've enabled a user-assigned managed identity on your VM. Consulte identidade gerenciada atribuída pelo usuário.See User-assigned managed identity.

Em seguida, no console de comando, digite qualquer um dos comandos a seguir e pressione a tecla 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>"

Substitua o espaço reservado <client-id> pela ID do cliente da identidade gerenciada atribuída pelo usuário.Replace the <client-id> placeholder with the client ID of the user-assigned managed identity.

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

Substitua o espaço reservado <object-id> pela ID de objeto da identidade gerenciada atribuída pelo usuário.Replace the <object-id> placeholder with the object ID of the user-assigned managed identity.

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

Substitua o espaço reservado <resource-id> pela ID de recurso da identidade gerenciada atribuída pelo usuário.Replace the <resource-id> placeholder with the resource ID of the user-assigned managed identity.

Opção 2: usar um token SASOption 2: Use a SAS token

Você pode acrescentar um token SAS a cada URL de origem ou de destino que usa em seus comandos AzCopy.You can append a SAS token to each source or destination URL that use in your AzCopy commands.

Esse comando de exemplo copia recursivamente os dados de um diretório local para um contêiner de BLOB.This example command recursively copies data from a local directory to a blob container. Um token SAS fictício é acrescentado ao final do da URL do contêiner.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

Para saber mais sobre tokens SAS e como obter um, consulte usando assinaturas de acesso compartilhado (SAS).To learn more about SAS tokens and how to obtain one, see Using shared access signatures (SAS).

Transferir arquivosTransfer files

Depois de autenticar sua identidade ou obter um token SAS, você pode começar a transferir arquivos.After you've authenticated your identity or obtained a SAS token, you can begin transferring files.

Para encontrar comandos de exemplo, consulte qualquer um desses artigos.To find example commands, see any of these articles.

Usar AzCopy em um scriptUse AzCopy in a script

Ao longo do tempo, o link de download do AzCopy apontará para novas versões do AzCopy.Over time, the AzCopy download link will point to new versions of AzCopy. Se o script baixar AzCopy, o script poderá parar de funcionar se uma versão mais recente do AzCopy modificar os recursos dependentes do seu script.If your script downloads AzCopy, the script might stop working if a newer version of AzCopy modifies features that your script depends upon.

Para evitar esses problemas, obtenha um link estático (sem alteração) para a versão atual do AzCopy.To avoid these issues, obtain a static (un-changing) link to the current version of AzCopy. Dessa forma, o script baixará a mesma versão exata do AzCopy cada vez que for executado.That way, your script downloads the same exact version of AzCopy each time that it runs.

Para obter o link, execute este comando:To obtain the link, run this command:

Sistema operacionalOperating system ComandoCommand
LinuxLinux curl -v https://aka.ms/downloadazcopy-v10-linux
WindowsWindows (curl https://aka.ms/downloadazcopy-v10-windows -MaximumRedirection 0 -ErrorAction silentlycontinue).RawContent

Observação

Para o Linux, --strip-components=1 no comando tar remove a pasta de nível superior que contém o nome da versão e, em vez disso, extrai o binário diretamente na pasta atual.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. Isso permite que o script seja atualizado com uma nova versão do azcopy atualizando apenas a URL wget.This allows the script to be updated with a new version of azcopy by only updating the wget URL.

A URL aparece na saída deste comando.The URL appears in the output of this command. O script pode então baixar o AzCopy usando essa URL.Your script can then download AzCopy by using that URL.

Sistema operacionalOperating system ComandoCommand
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>>

Caracteres especiais de escape em tokens SASEscape special characters in SAS tokens

Em arquivos em lotes que têm a extensão .cmd, você terá que escapar os caracteres de % que aparecem em tokens SAS.In batch files that have the .cmd extension, you'll have to escape the % characters that appear in SAS tokens. Você pode fazer isso adicionando um caractere de % de adição ao lado dos caracteres % existentes na cadeia de caracteres do token SAS.You can do that by adding an addition % character next to existing % characters in the SAS token string.

Executar scripts usando JenkinsRun scripts by using Jenkins

Se você planeja usar o Jenkins para executar scripts, certifique-se de colocar o comando a seguir no início do script.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

Usar AzCopy no Gerenciador de Armazenamento do AzureUse AzCopy in Azure Storage Explorer

Gerenciador de armazenamento usa AzCopy para executar todas as operações de transferência de dados.Storage Explorer uses AzCopy to perform all of it's data transfer operations. Você pode usar Gerenciador de armazenamento se quiser aproveitar as vantagens de desempenho do AzCopy, mas preferir usar uma interface gráfica do usuário em vez da linha de comando para interagir com seus arquivos.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.

Gerenciador de Armazenamento usa sua chave de conta para executar operações, portanto, depois de entrar no Gerenciador de Armazenamento, você não precisará fornecer credenciais de autorização adicionais.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.

Usar a versão anterior do AzCopyUse the previous version of AzCopy

Se você precisar usar a versão anterior do AzCopy (AzCopy v 8.1), consulte um dos links a seguir:If you need to use the previous version of AzCopy (AzCopy v8.1), see either of the following links:

Configurar, otimizar e solucionar problemas do AzCopyConfigure, optimize, and troubleshoot AzCopy

Consulte Configurar, otimizar e solucionar problemas do AzCopySee Configure, optimize, and troubleshoot AzCopy

Próximos passosNext steps

Se você tiver dúvidas, problemas ou comentários gerais, envie-os na página do GitHub .If you have questions, issues, or general feedback, submit them on GitHub page.