PowerShell: Download di file con BITS

BITS (Background Intelligent Transfer System) è un componente di Windows utilizzato dal sistema operativo per il download degli aggiornamenti. Tale componente è utilizzabile anche da programmatori e amministratori di sistema per il download/upload di file di grandi dimensioni su server web HTTP o REST e su file server SMB. BITS sfrutta la banda non utilizzata per trasferire dati preservando la reattività di altre applicazioni di rete inoltre, gestisce eventuali interruzioni di rete mettendo in pausa e riprendendo automaticamente i trasferimenti anche dopo un riavvio ed è in grado di operare anche quando la macchina non è loggata. BITS non funziona con tutti i download ma è necessario che anche il server supporti tale tecnologia.

Per sfruttare le potenzialità di BITS attraverso PowerShell, si utilizza il cmdlet Start-BitsTransfer.

Sintassi

Start-BitsTransfer

     [-Asynchronous]

     [-Dynamic]

     [-CustomHeadersWriteOnly]

     [-Authentication <String>]

     [-Credential <PSCredential>]

     [-Description <String>]

     [-HttpMethod <String>]

     [[-Destination] <String[]>]

     [-DisplayName <String>]

     [-Priority <String>]

     [-TransferPolicy <CostStates>]

     [-ACLFlags <ACLFlagValue>]

     [-SecurityFlags <SecurityFlagValue>]

     [-UseStoredCredential <AuthenticationTargetValue>]

     [-ProxyAuthentication <String>]

     [-ProxyBypass <String[]>]

     [-ProxyCredential <PSCredential>]

     [-ProxyList <Uri[]>]

     [-ProxyUsage <String>]

     [-RetryInterval <Int32>]

     [-RetryTimeout <Int32>]

     [-MaxDownloadTime <Int32>]

     [-Source] <String[]>

     [-Suspended]

     [-TransferType <String>]

     [-CustomHeaders <String[]>]

     [-NotifyFlags <NotifyFlagValue>]

     [-NotifyCmdLine <String[]>]

     [-CertStoreLocation <CertStoreLocationValue>]

     [-CertStoreName <String>]

     [-CertHash <Byte[]>]

     [-WhatIf]

     [-Confirm]

     [<CommonParameters>]

Descrizione

Il cmdlet Start-BitsTransfer crea un job Background Intelligent Transfer Service (BITS) per trasferire uno o più file tra un computer client e un server. Il parametro TransferType specifica la direzione del trasferimento. Per impostazione predefinita, dopo che il cmdlet inizia il trasferimento, il prompt dei comandi non è disponibile fino a quando il trasferimento non sarà completo o si verifica un errore. Se lo stato dell'oggetto BitsJob restituito è Error, il codice di errore e la descrizione sono contenuti nell'oggetto e possono essere utilizzati per l'analisi.

Parametri

-ACLFlags

Specifica il proprietario e le informazioni dell'elenco di controllo degli accessi (ACL) da mantenere per il job di trasferimento. É possibile specificare uno o più dei seguenti valori:

• o: Copia le informazioni sul proprietario con il file.
• g: Copia le informazioni sul gruppo con il file.
• d: Copia le informazioni sulla lista di controllo degli accessi discrezionali (DACL) con il file.
• s: Copia le informazioni dell'elenco di controllo dell'accesso al sistema (SACL) con il file.

-Asynchronous

Indica che il cmdlet crea ed elabora il job di trasferimento BITS in background. Il prompt dei comandi riappare immediatamente dopo la creazione del lavoro di trasferimento BITS. L'oggetto BitsJob restituito può essere utilizzato per monitorare lo stato e il progresso del trasferimento.

-Authentication

Specifica il meccanismo di autenticazione da utilizzare sul server. I valori accettati per questo parametro sono:

• Basic: è uno schema in cui il nome utente e la password sono inviati in chiaro al server o al proxy.
• Digest: è uno schema  challenge-response  che usa una stringa di dati specificata dal server per la challenge.
• Ntlm: NT LAN Manager (NTLM) è uno schema challenge-response che usa le credenziali dell'utente per l'autenticazione in un ambiente di rete basato su Windows.
• Negotiate (l'impostazione predefinita): è uno schema challenge-response che negozia con il server o il proxy per determinare quale schema usare per l'autenticazione. Per esempio, questo valore di parametro permette la negoziazione per determinare se viene usato il protocollo Kerberos o NTLM.
• Passport: Passport è un servizio di autenticazione centralizzato fornito da Microsoft che offre un unico accesso per i siti membri.

-CertHash

Specifica un hash SHA1 che identifica il certificato.

-CertStoreLocation

Specifica la location da usare per cercare il certificato. I valori validi sono:

• CURRENT_USER
• LOCAL_MACHINE
• CURRENT_SERVICE
• SERVICES
• USERS
• CURRENT_USER_GROUP_POLICY
• LOCAL_MACHINE_GROUP_POLICY
• LOCAL_MACHINE_ENTERPRISE

-CertStoreName

Specifica il nome dello store di certificati. I valori validi sono:

• CA: Certification Authority certificates
• MY: Personal certificates
• ROOT: Root certificates
• SPC: Software Publisher Certificate

-Confirm

Chiede conferma prima di eseguire il cmdlet.

-Credential

Specifica le credenziali da usare per autenticare l'utente al server indicato nel valore del parametro Source. L'impostazione predefinita è l'utente corrente.

-CustomHeaders

Specifica una o più intestazioni HTTP personalizzate da includere nella richiesta al server. Specifica un array di stringhe.

-CustomHeadersWriteOnly

Indica che le intestazioni personalizzate HTTP per questo job sono in sola scrittura.

Questo parametro viene utilizzato quando le intestazioni personalizzate includono informazioni di sicurezza. Altri programmi sullo stesso computer non possono leggere l'intestazione. Il processo BITS può leggere le intestazioni e inviarle attraverso la connessione HTTP. 

Dopo aver impostato le intestazioni in solo scrittura per un job non sarà possibile modificarle.

-Description

Permette di specificare una descrizione del job di trasferimento BITS. La descrizione è limitata a 1.024 caratteri.

-Destination

Specifica un array che contiene la posizione di destinazione e i nomi dei file che si intende trasferire. I nomi di destinazione sono accoppiati con i corrispondenti nomi di file sorgente. Per esempio, il primo nome di file specificato nel parametro Source corrisponde al primo nome di file nel parametro Destination, e il secondo nome di file nel parametro Source corrisponde al secondo nome di file nel parametro Destination. I parametri Source e Destination devono avere lo stesso numero di elementi, altrimenti il comando produce un errore.

-DisplayName

Specifica un nome di visualizzazione per il job di trasferimento BITS. Il nome visualizzato fornisce un modo semplice per differenziare i trasferimenti BITS.

-Dynamic

Indica che il trasferimento utilizza l'impostazione dinamica.

-HttpMethod

Specifica un metodo per il trasferimento diverso dal metodo predefinito GET. Se si specifica GET, il parametro non ha effetto.

Se si specifica un metodo, il job prende la priorità in primo piano, che non può essere cambiata.

-MaxDownloadTime

Specifica il tempo massimo, in secondi, per il trasferimento dei file in un lavoro. Il valore predefinito è 7.776.000 secondi o 90 giorni.

-NotifyCmdLine

Specifica un programma da eseguire dopo che il job termina o fallisce con un errore. Il programma viene eseguito nel contesto dell'utente che esegue questa cmdlet.

Specifica il nome del programma ed eventuali parametri come un array di stringhe.

-NotifyFlags

Specifica il tipo di notifica dell'evento che vuoi ricevere, come gli eventi di trasferimento del lavoro. I valori validi sono:

1: Genera un evento quando tutti i file del job sono stati trasferiti.

2: Genera un evento quando si verifica un errore.

4: Disabilita le notifiche.

-Priority

Imposta la priorità del job di trasferimento BITS, che influenza l'uso della larghezza di banda. I valori accettati per questo parametro sono:

• Foreground (predefinito): Il trasferimento viene gestito in primo piano. I trasferimenti in primo piano competono per la larghezza di banda della rete con altre applicazioni, il che può ostacolare l'esperienza complessiva della rete dell'utente. Tuttavia, se il cmdlet Start-BitsTransfer viene utilizzato in modo interattivo, questa è probabilmente l'opzione migliore. Questo è il livello di priorità più alto.
• High: Il trasferimento avviene in background con un'alta priorità. I trasferimenti in background utilizzano la larghezza di banda di rete inattiva del computer client per trasferire i file.
• Normal: Il trasferimento avviene in background con una priorità normale. I trasferimenti in background utilizzano la larghezza di banda di rete inattiva del computer client per trasferire i file.
• Low: Il trasferimento avviene in background con una priorità bassa. I trasferimenti in background usano la larghezza di banda di rete inattiva del client per trasferire i file. Questo è il livello di priorità in background più basso.

-ProxyAuthentication

Specifica il meccanismo di autenticazione da usare al proxy web. I valori accettati per questo parametro sono:

• Basic: Basic è uno schema in cui il nome utente e la password sono inviati in chiaro al server o al proxy.
• Digest: Digest è uno schema challenge che usa una stringa di dati specificata dal server per la challenge.
• Ntlm: NTLM è uno schema challenge-response che usa le credenziali dell'utente per l'autenticazione in un ambiente di rete basato su Windows.
• Negotiate (l'impostazione predefinita): Negotiate è uno schema challenge-response che negozia con il server o il proxy per determinare quale schema usare per l'autenticazione. Per esempio, questo valore di parametro permette la negoziazione per determinare se viene usato il protocollo Kerberos o NTLM.
• Passport: Passport è un servizio di autenticazione centralizzato fornito da Microsoft che offre un unico accesso per i siti membri.

-ProxyBypass

Specifica una lista di nomi di host da usare per una connessione diretta. Gli host nell'elenco vengono provati in ordine fino a quando non si ottiene una connessione di successo. Se si specifica questo parametro il cmdlet bypassa il proxy. Se questo parametro viene utilizzato, il parametro ProxyUsage deve essere impostato su Override, altrimenti si verificherà un errore.

-ProxyCredential

Specifica le credenziali da utilizzare per autenticare l'utente al proxy. Con il cmdlet Get-Credential è possibile creare un valore per questo parametro.

-ProxyList

Specifica una lista di proxy da utilizzare. I proxy nell'elenco vengono provati in ordine fino a quando non si ottiene una connessione di successo. Se questo parametro è specificato e ProxyUsage è impostato su un valore diverso da Override, la cmdlet genera un errore.

-ProxyUsage

Specifica le impostazioni di utilizzo del proxy. I valori accettati per questo parametro sono:

• SystemDefault (il valore predefinito): Usa le impostazioni proxy predefinite del sistema.
• NoProxy: Non usare un proxy per trasferire i file. Utilizzare questa opzione quando si trasferiscono file all'interno di una rete locale (LAN).
• AutoDetect: Rileva automaticamente le impostazioni proxy. Il BITS rileva le impostazioni proxy per ogni file nel lavoro.
• Sovrascrivi: Specifica i proxy o i server da usare. Se viene specificato anche il parametro ProxyList, vengono utilizzati i proxy di quella lista. Se viene specificato anche il parametro ProxyBypass, vengono utilizzati i server di quella lista. In entrambi i casi, viene utilizzato il primo membro della lista. Se il primo membro non è raggiungibile, vengono provati i membri successivi fino a quando un membro viene contattato con successo.

-RetryInterval

Specifica la lunghezza minima di tempo, in secondi, che il BITS attende prima di un ulteriore tentativo di trasferimento dopo un errore. Il valore minimo consentito è 60 secondi. Se questo valore supera il valore RetryTimeout dell'oggetto BitsJob, il BITS non ritenta il trasferimento ma imposta lo stato Error.

Il valore predefinito è 600 secondi (10 minuti).

-RetryTimeout

Specifica il tempo, in secondi, in cui il BITS prova a trasferire il file dopo il primo errore. Impostando 0 si evitano i tentativi e si forza il job nello stato BG_JOB_STATE_ERROR quando si verifica un errore. Se il valore del periodo di ripetizione supera l'impostazione del criterio di gruppo JobInactivityTimeout (90 giorni di default), quest'ultimo ha la precedenza e il trasferimento viene cancellato.

Il valore predefinito è 1.209.600 secondi (14 giorni).

-SecurityFlags

Specifica i flag di sicurezza per la richiesta HTTP.

I flag che si possono impostare, a partire dal bit meno significativo, sono i seguenti:

1: Abilita il controllo CRL.

2: Ignora i nomi comuni errati nel certificato del server.

3: Ignora le date errate nel certificato del server.

4: Ignora le autorità di certificazione errate nel certificato del server.

5: Ignora l'uso scorretto del certificato del server.

12: Permette il reindirizzamento da HTTPS a HTTP.

Usa i bit da 9 a 11 per implementare la policy di reindirizzamento:

0,0,0: I reindirizzamenti sono automaticamente permessi.

0,0,1: Il nome remoto è aggiornato se si verifica un reindirizzamento. 

0,1,0: Il BITS fallisce se si verifica un reindirizzamento.

-Source

Specifica la posizione di origine e i nomi dei file da trasferire. I nomi dei file di origine sono abbinati ai corrispondenti nomi dei file di destinazione. Per esempio, il primo nome del file specificato nel parametro Source corrisponde al primo nome del file nel parametro Destination, e il secondo nome del file nel parametro Source corrisponde al secondo nome del file nel parametro Destination. I parametri Source e Destination devono avere lo stesso numero di elementi, altrimenti il comando produce un errore. Il parametro accetta i caratteri jolly standard come l'asterisco (*) e il punto interrogativo (?) e anche un'operatore di intervallo come "[a-r]".

-Suspended

Indica che il cmdlet sospende il trasferimento BITS. Se il parametro Suspended non è specificato, il trasferimento viene avviato automaticamente, in caso contrario il prompt dei comandi ritorna immediatamente dopo la creazione del job di trasferimento BITS. Per avviare un trasferimento sospeso si può utilizzare il cmdlet Resume-BitsTransfer.

-TransferPolicy

Specifica, tramite l'utilizzo di una maschera di bit, gli stati di una connessione a consumo in cui il trasferimento può essere pianificato. 

I valori accettati per questo parametro sono

• Unrestricted (o unknown): 0x00000001, lo stato dei costi per questa rete a consumo non è noto.
• Capped: 0x00000002, si tratta di una rete a consumo con un piano che ha un limite di utilizzo dei dati.
• BelowCap: 0x00000004,  il consumo dati della rete a consumo è al di sotto del limite del piano dati.
• NearCap: 0x00000008, il consumo dati è vicino al limite del piano dati.
• OverCapCharged: 0x00000010, il consumo dati è superiore al limite del piano dati, e l'uso è addebitato.
• OverCapThrottled: 0x00000020, il consumo dati è al di sopra del limite del piano dati, e l'uso è limitato.
• UsageBased: 0x00000040, il consumo dati per questa rete è addebitato in base all'uso.
• Roaming: 0x00000080, il consumo dati per questa rete incorre in costi di roaming. Lo stato dei costi include anche un'opzione (IgnoreCongestion) e un insieme di politiche standard (Uncosted, Standard, NoSurcharge, NotRoaming, e Always) che sono combinazioni di valori di bit discreti.
• IgnoreCongestion: 0x80000000, il trasferimento può essere programmato anche se il fornitore di rete segnala che la rete è congestionata.
• PolicyUnrestricted: 0x80000021, l'insieme degli stati di costo che non consumano la quota di un piano limitato, o incorrono in spese extra.
• Standard: 0x80000067,  un insieme di stati di costo adatti a trasferimenti a priorità moderata.
• NoSurcharge: 0x8000006f, l'insieme degli stati di costo che non comportano supplementi per l'uso.
• NotRoaming: 0x8000007f, l'insieme degli stati di costo che escludono lo stato di roaming.
• Always: 0x800000ff, l'insieme di tutti gli stati di costo.

-TransferType

Specifica il tipo di trasferimento dati. I valori accettati per questo parametro sono:

• Download (il valore predefinito): Scarica i file sul computer client.
• Upload: Carica un file sul server.
• UploadReply: Carica un file sul server e riceve un file di risposta dal server.

-UseStoredCredential

Specifica che le credenziali memorizzate nel Windows Credential Manager dovrebbero essere usate per l'autenticazione quando richiesto per il tipo di server di destinazione specificato. Se questo parametro non è specificato e un server richiede l'autenticazione, allora le credenziali esplicite devono essere incluse utilizzando i parametri Credential o ProxyCredential. Questo parametro è un parametro flag i cui valori possono essere sommati per creare il comportamento desiderato.

I valori accettati per questo parametro sono:

• None: Usa solo le credenziali fornite dai parametri Credential o ProxyCredential. Questo è il comportamento predefinito se il parametro non è specificato.
• Proxy: Le credenziali memorizzate nel Windows Credential Manager sono utilizzate per l'autenticazione per qualsiasi server proxy che richiede l'autenticazione. Se nessuna credenziale nel Windows Credential Manager corrisponde al server proxy che necessita di autenticazione, allora è necessario specificare le credenziali utilizzando il parametro ProxyCredential.
• Server: Questo valore non è supportato e genera un errore se specificato.

-WhatIf

Mostra cosa accadrebbe se il cmdlet venisse eseguito. Il cmdlet non viene eseguito.

Esempi

Esempio 1

Start-BitsTransfer -Source "http://server01/servertestdir/testfile1.txt" -Destination "c:\clienttestdir\testfile1.txt"

Crea un job di trasferimento BITS dal server al client.

Poiché il cmdlet Start-BitsTransfer assume che il primo parametro sia l'origine e che il secondo sia la destinazione il comando può essere semplificato in

Start-BitsTransfer "http://server01/servertestdir/testfile1.txt" "c:\clienttestdir\testfile1.txt"

Esempio 2

Import-CSV ElencoFile.txt | Start-BitsTransfer

Questo comando crea job di trasferimento BITS che scaricano più file da un server. Il comando importa le posizioni dei file di origine e di destinazione dal file .txt e poi invia le informazioni al comando Start-BitsTransfer. Il comando Start-BitsTransfer crea un nuovo job di trasferimento BITS per ciascuno dei file in ElencoFile.txt e poi li trasferisce simultaneamente al client.

Il contenuto del file ElencoFile.txt sarà simile a

Source, Destination
http://server01/servertestdir/testfile1.txt, c:\clienttestdir\testfile1.txt

Esempio 3

Start-BitsTransfer -Source "c:\clienttestdir\testfile1.txt" -Destination "http://server01/servertestdir/testfile1.txt" -TransferType Upload

Questo comando crea un job di trasferimento BITS che carica un file su un server. I nomi locali e remoti del file sono specificati nei parametri Source e Destination. Poiché il tipo di trasferimento predefinito è Download, il parametro TransferType deve essere impostato su Upload.

Esempio 4

Start-BitsTransfer -Source .\Patch0416.msu -Destination $env:temp\Patch0416.msu -ProxyUsage Override -ProxyList BitsProxy:8080 -ProxyCredential Server01\Admin01

Questo comando usa il cmdlet Start-BitsTransfer per copiare un file patch da un server su una rete a un client su una rete diversa quando le reti sono collegate solo da un server proxy.

Esempio 5

 #Percorso e nome del file da scaricare  
 $url = 'https://images-assets.nasa.gov/video/Seventeen Seconds of Fuel Remained/Seventeen Seconds of Fuel Remained~orig.mp4'  
 #Path di destinazione  
 $targetfolder = $env:temp  
 #Il file verrĂ  salvato con lo stesso nome nel percorso di destinazione  
 $filename = Split-Path -Path $url -Leaf  
 $targetFile = Join-Path -Path $targetfolder -ChildPath $filename  
   
 #avvio trasferimento BITS  
 Start-BitsTransfer -Source $url -Destination $targetfolder -Description 'Download in corso...' -Priority Low   
   
 #Il file video viene visualizzato dal player predefinito  
 Start-Process -FilePath $targetFile  

Lo script sopra riportato provvede a scaricare un video dal sito della NASA e, al termine del download, provvede a visualizzarlo con il player predefinito. Come visibile nello script con il comando Start-BitsTransfer è stata impostata una priorità bassa per il download in modo da poter scaricare il file senza monopolizzare la banda di rete.

FIG 1 - Start-BitsTransfer

Esempio 6

 $url = 'https://images-assets.nasa.gov/video/Seventeen Seconds of Fuel Remained/Seventeen Seconds of Fuel Remained~orig.mp4'  
 $targetfolder = $env:temp  
 Start-BitsTransfer -Source $url -Destination $targetfolder -Asynchronous -Priority Low  
   
 Get-BitsTransfer | ForEach-Object {  
   Write-Warning $_.FileList.RemoteName  
   $_  
  } |  Where-Object { $_.jobstate -eq 'Transferred' } | ForEach-Object {  
   #$_ | Select-Object -Property *  
   $file = $_.FileList.LocalName  
   Write-Warning "Copia file $file..."  
   $_ | Complete-BitsTransfer  
  }  

Lo script sopra riportato scarica in bakcground un video dal sito della NASA con bassa priorità e in modalità asincrona. Lo svantaggio dei trasferimenti asincroni del BITS è che i dati vengono scaricati in una cache nascosta e bisogna completare manualmente il trasferimento del file. Tramite Get-BitsTransfer si verificano i job completati quindi il trasferimento del file viene finalizzato utilizzando il cmdlet Complete-BitsTransfer.

Eseguendo PowerShell come amministratore è possibile controllare i trasferimenti BITS iniziati da altri utenti, compreso il sistema operativo utilizzando il cmdlet Get-BitsTransfer.

Get-BitsTransfer -AllUsers

per visualizzare i BITS avviati da altri utenti

Get-BitsTransfer -AllUsers | Select-Object OwnerAccount, Priority, FileList

Per visualizzare maggiori dettagli sui BITS avviati da altri utenti, tra cui priorità e il nome dei file.

FIG 2 - Get-BitsTransfer