Share via

Usar o Windows PowerShell para criar trabalhos de transferência do BITS

  • Artigo

Você pode usar cmdlets do PowerShell para criar trabalhos de transferência síncronos e assíncronos do BITS (Serviço de Transferência Inteligente em Segundo Plano).

Todos os exemplos neste tópico usam o cmdlet Start-BitsTransfer . Para usar o cmdlet, importe o módulo primeiro. Para instalar o módulo, execute o seguinte comando: Import-Module BitsTransfer. Para obter mais informações, digite Get-Help Start-BitsTransfer no prompt do PowerShell.

Importante

Quando você usa cmdlets *-BitsTransfer de dentro de um processo que é executado em um contexto não interativo, como um serviço do Windows, talvez não seja possível adicionar arquivos a trabalhos do BITS, o que pode resultar em um estado suspenso. Para que o trabalho continue, a identidade que foi usada para criar um trabalho de transferência deve estar conectada. Por exemplo, ao criar um trabalho do BITS em um script do PowerShell que foi executado como um trabalho do Agendador de Tarefas, a transferência do BITS nunca será concluída, a menos que a configuração de tarefa do Agendador de Tarefas "Executar somente quando o usuário estiver conectado" esteja habilitada.

 

Para criar um trabalho de transferência síncrono do BITS

Start-BitsTransfer -Source https://Server01/serverdir/testfile1.txt `
-Destination C:\clientdir\testfile1.txt

Observação

O caractere de acento grave (') é usado para indicar uma quebra de linha.

 

No exemplo anterior, os nomes local e remoto do arquivo são especificados nos parâmetros Source e Destination , respectivamente. O prompt de comando volta a aparecer quando a transferência do arquivo é concluída ou quando ela entra em um estado de erro.

O tipo de transferência padrão é Download. Quando você carrega arquivos em um local HTTP, o parâmetro TransferType deve ser definido como Upload.

Como a posição do parâmetro é imposta para o cmdlet Start-BitsTransfer , os nomes dos parâmetros não precisam ser especificados para os parâmetros Source e Destination. Portanto, esse comando pode ser simplificado da seguinte maneira.

Start-BitsTransfer https://Server01/serverdir/testfile1.txt C:\clientdir\testfile1.txt

Para criar um trabalho de transferência síncrono do BITS com vários arquivos

Start-BitsTransfer -Source C:\clientsourcedir\*.txt `
-Destination c:\clientdir\ -TransferType Download

No exemplo anterior, o comando Start-BitsTransfer cria um novo trabalho de transferência do BITS. Todos os arquivos são adicionados a este trabalho e transferidos sequencialmente para o cliente.

Observação

O caminho de destino não pode usar caracteres curinga. O caminho de destino oferece suporte a diretórios relativos, caminhos raiz ou diretórios implícitos (ou seja, o diretório atual). Os arquivos de destino não podem ser renomeados usando um caractere curinga. Além disso, URLs HTTP e HTTPS não funcionam com curingas. Os curingas são válidos apenas para caminhos UNC e diretórios locais.

 

Para criar um trabalho de transferência síncrono do BITS e especificar credenciais para um servidor remoto

Start-BitsTransfer -DisplayName MyJob -Credential Username\Domain `
-Source https://server01/servertestdir/testfile1.txt -Destination c:\clienttestdir\testfile1.txt `
-ProxyUsage Override -ProxyList @(https://proxy1, 123.24.21.23, proxy3)

No exemplo anterior, um usuário cria um trabalho de transferência do BITS para baixar um arquivo de um servidor que requer autenticação. O usuário é solicitado a fornecer credenciais e o parâmetro Credential passa um objeto de credencial para o cmdlet Start-BitsTransfer. O usuário define um proxy explícito e o trabalho de transferência do BITS usa apenas os proxies definidos pelo parâmetro ProxyList . O parâmetro DisplayName dá ao trabalho de transferência do BITS um nome de exibição exclusivo.

Para criar um trabalho de transferência síncrono do BITS a partir de um arquivo CSV

Import-CSV filelist.txt | Start-BitsTransfer -TransferType Upload

Observação

O "|" é o caractere pipe.

 

No exemplo anterior, um usuário cria um trabalho de transferência do BITS que carrega vários arquivos de um cliente. O cmdlet Import-CSV importa os locais dos arquivos de origem e de destino e os canaliza para o comando Start-BitsTransfer . O comando Start-BitsTransfer cria um novo trabalho de transferência do BITS para cada arquivo, adiciona os arquivos ao trabalho e os transfere sequencialmente para o servidor.

O conteúdo do arquivo Filelist.txt deve estar no seguinte formato:

Source, Destination
c:\clienttestdir\testfile1.txt, https://server01/servertestdir/testfile1.txt
c:\clienttestdir\testfile2.txt, https://server01/servertestdir/testfile2.txt
c:\clienttestdir\testfile3.txt, https://server01/servertestdir/testfile3.txt
c:\clienttestdir\testfile4.txt, https://server01/servertestdir/testfile4.txt

Para criar um trabalho de transferência assíncrono do BITS

$Job = Start-BitsTransfer -Source https://Server1.TrustedDomain.com/File1.zip `
       -Destination d:\temp\downloads\ -Asynchronous

while (($Job.JobState -eq "Transferring") -or ($Job.JobState -eq "Connecting")) `
       { sleep 5;} # Poll for status, sleep for 5 seconds, or perform an action.

Switch($Job.JobState)
{
    "Transferred" {Complete-BitsTransfer -BitsJob $Job}
    "Error" {$Job | Format-List } # List the errors.
    default {"Other action"} #  Perform corrective action.
}

No exemplo anterior, o trabalho de transferência do BITS foi atribuído à variável $Job. Os arquivos são baixados sequencialmente. Após a conclusão do trabalho de transferência, os arquivos ficam imediatamente disponíveis. Se $Job.JobState retornar "Transferred", o objeto $Job será enviado para o cmdlet Complete-BitsTransfer .

Se $Job.JobState retornar "Error", o objeto $Job será enviado ao cmdlet Format-List para listar os erros.

Para gerenciar sessões remotas do PowerShell

A partir do Windows 10, versão 1607, você pode executar cmdlets do PowerShell, BITSAdmin ou outros aplicativos que usam as interfaces do BITS a partir de uma linha de comando remota do PowerShell conectada a outra máquina (física ou virtual). Esse recurso não está disponível ao usar uma linha de comando do PowerShell Direct para uma máquina virtual na mesma máquina física e não está disponível ao usar cmdlets WinRM.

Um Trabalho do BITS criado a partir de uma sessão do PowerShell Remoto é executado no contexto da conta de usuário dessa sessão e só progredirá quando houver pelo menos uma sessão de logon local ativa ou uma sessão do PowerShell Remoto associada a essa conta de usuário. Você pode usar o PSSessions persistente do PowerShell para executar comandos remotos sem a necessidade de manter uma janela do PowerShell aberta para que cada trabalho continue progredindo, conforme descrito em Administrar computadores remotos usando o Windows PowerShell.

  • New-PSSession cria uma sessão persistente do PowerShell Remoto. Depois de criados, os objetos PSSession persistem na máquina remota até serem excluídos explicitamente. Qualquer trabalho do BITS iniciado em uma sessão ativa fará progresso transferindo dados, mesmo depois que o cliente tiver se desconectado da sessão.
  • Disconnect-PSSession desconecta a máquina cliente de uma sessão do PowerShell remoto e o estado da sessão continua a ser mantido pela máquina remota. Mais importante ainda, os processos da sessão remota continuarão em execução e os trabalhos do BITS continuarão a progredir. A máquina cliente pode até mesmo reiniciar e/ou desligar depois de chamar Disconnect-PSSession.
  • O Connect-PSSession reconecta a máquina cliente a uma sessão ativa do PowerShell Remoto.
  • Remove-PSSession destrói uma sessão do PowerShell Remoto.

O exemplo abaixo mostra como usar o PowerShell Remote para trabalhar com trabalhos de transferência assíncronos do BITS de uma forma que permita que o trabalho continue a progredir mesmo quando você não estiver ativamente conectado à sessão remota.

# Establish a PowerShell Remote session in Server01 with name 'MyRemoteSession'
New-PSSession -ComputerName Server01 -Name MyRemoteSession -Credential Domain01\User01

# Enter the previously-established session to execute commands
Enter-PSSession -Name MyRemoteSession

# Enumerate active BITS transfers on the remote machine
Get-BitsTransfer

# While running in the context of the PowerShell Remote session, start a new BITS transfer
Start-BitsTransfer -Source https://Server1.TrustedDomain.com/File1.zip -Destination c:\temp\downloads\ -Asynchronous

# Exit the PowerShell Remote session's context
Exit-PSSession

# Disconnect the 'MyRemoteSession' PowerShell Remote session from the current PowerShell window
# After this command, it is safe to close the current PowerShell window and turn off the local machine
Disconnect-PSSession -Name MyRemoteSession


# The commands below can be executed from a different PowerShell window, even after rebooting the local machine
# Connect the 'MyRemoteSession' PowerShell Remote session to the current PowerShell window
Connect-PSSession -ComputerName Server01 -Name MyRemoteSession

# Enter the previously-established session to execute commands
Enter-PSSession -Name MyRemoteSession

# Enumerate active BITS transfers on the remote machine
Get-BitsTransfer

# Manage BITS transfers on the remote machine via Complete-BitsTransfer, Remove-BitsTransfer, etc.

# Exit the PowerShell Remote session's context
Exit-PSSession

# Destroy the 'MyRemoteSession' PowerShell Remote session when no longer needed
Remove-PSSession -Name MyRemoteSession

Start-BitsTransfer

Transferência de bits completa