[PowerShell] BITSTransferの利用まとめ

はじめに

Webサーバ上にあるファイルのダウンロードやアップロードをする方法として、Invoke-WebRequestなどいくつか方法がありますが、今回はWindowsの機能として用意されているBITSTransferによるダウンロード/アップロードについて、設定から利用方法までを本記事にてご紹介したいと思います。

BITSとは

BITSとは、Background Intelligent Transfer Serviceの略であり、ネットワークの未使用の帯域を利用してファイル転送を行う仕組みである。

BITSは通常、バックグラウンドでファイルを転送し、別アプリケーション等でネットワーク帯域を利用する場合は、使用ネットワーク帯域を調整して処理されます。

ファイル転送は「HTTP」または「HTTPS」によるデータ転送をサポートしています。

Windows Updateの自動更新は「BITS」が使用されています。

〜参考〜
BitsTransfer Module | Microsoft Docs

ポリシーによるBITS制御

BITSによるファイル転送はグループポリシーにて制御することができます。

BITS制御ポリシーを無効または構成しない場合は、BITSによってすべての未使用帯域幅が使用されます。

  • 特定時間内のバックグラウンド転送レート(Kbps)の制御
  • 特定時間の開始時刻(0~23)
  • 特定時間の終了時刻(0~23)
  • 特定時間外のバックグラウンド転送レートの制御

上記項目はそれぞれ、下記のポリシーにて設定可能です。

[グループポリシー]
管理用テンプレート(コンピュータ)
 ┗ ネットワーク
   ┗ バックグラウンド インテリジェント転送サービス(BITS)
     ┗ BITSバックグラウンド転送最大ネットワーク帯域幅を制限する

[レジストリ]

キー
HKEY_LOCAL_MACHINE¥Software¥Policies¥Microsoft¥Windows¥BITS
名前種類
制御の有効状態EnableBITSMaxBandwidthREG_DWORD0 or 1
特定時間内のバックグラウンド転送レートMaxTransferRateOnScheduleREG_DWORD1~4294967200
特定時間の開始時刻MaxBandwidthValidFromREG_DWORD0~23
特定時間の終了時刻MaxBandwidthValidToREG_DWORD0~23
未使用で利用可能な帯域幅利用有無UseSystemMaximumREG_DWORD0 or 1
特定時間外のバックグラウンド転送レートMaxTransferRateOffScheduleREG_DWORD1~4294967200

※ 未使用で利用可能な帯域利用有無と特定時間外のバックグラウンド転送レートは「OR条件」です。

Bits-Transferモジュールのインポート

PowerShellにて実際にBITS転送を行うためのモジュールをインポートします。

PS D:¥> Import-Module BitsTransfer
PS D:¥> Help BitsTransfer
Name                              Category  Module                    Synopsis
----                              --------  ------                    --------
Complete-BitsTransfer             Cmdlet    BitsTransfer              ...
Get-BitsTransfer                  Cmdlet    BitsTransfer              ...
Remove-BitsTransfer               Cmdlet    BitsTransfer              ...
Resume-BitsTransfer               Cmdlet    BitsTransfer              ...
Set-BitsTransfer                  Cmdlet    BitsTransfer              ...
Start-BitsTransfer                Cmdlet    BitsTransfer              ...
Suspend-BitsTransfer              Cmdlet    BitsTransfer              ...

PS D:¥> 

インポートが正常に完了した場合に、「Help」コマンドを実行すると、利用可能なCmdlet一覧が表示されます。

ファイルダウンロード

BITSのファイル転送では優先度を設定します。(デフォルトはForeground)

優先度説明
Foreground同期ダウンロードを実施します。
High非同期にてダウンロードまたはアップロードを実施します。非同期処理では最も高い優先度となります。
Normal非同期にてダウンロードまたはアップロードを実施します。Highの次に優先度が高い設定となります。
Low非同期にてダウンロードまたはアップロードを実施します。最も優先度が低い設定となります。

ファイルのダウンロードは、下記Cmdletを利用します。

Start-BitsTransfer
オプションタイプ説明
-AsynchronousSwitch非同期で処理する場合に指定します。
-AuthenticationStringデータ転送時の認証方法を指定します。
「Basic, Digest, Ntlm, Negotiate, Passport」が指定可能です。
-ConfirmSwitch転送実行前に確認を求めるプロンプトを表示します。
-CredentialPSCredentialユーザ認証するための資格情報を指定します。
-DescriptionString転送ジョブに説明を追加します。文字制限は1024文字となります。
-DestinationString[]転送先の場所と転送するファイルの名前を含む配列を指定します。
-DisplayNameStringBITSジョブ名を指定します。
-PriorityStrubgBITSジョブの優先度を設定します。
「Foreground, High, Normal, Low」が指定可能です。
-ProxyAuthenticationStringWebプロキシを利用する場合の認証方法を指定します。
「Basic, Digest, Ntlm, Negotiate, Passport」がして可能です。
-ProxyBypassString[]直接接続するホスト名のリストを指定します。
-ProxyCredentialPSCredentialプロキシ認証するための資格情報を指定します。
-ProxyListUri[]使用するプロキシのリストをい指定します。
-ProxyUsageStringプロキシの利用方法を指定します。
「SystemDefault, NoProxy, AutoDetect, Override」が指定可能です。
-RetryIntervalInt32BITSにて一時的にエラーが発生した場合の施行までの待機時間を指定する(Default:10分)
-RetryTimeoutInt32BITSにて一時的にエラーが発生した場合の施行する時間の長さを指定します(Default:14日)
-SourceString[]転送するファイルのソースの場所と名前を指定します。
-SuspendedSwitchBITS転送ジョブを一時停止します。
-TransferPolicyCostStates転送スケジュールを許可するネットワークコストの状態を指定します。
-TransferTypeString転送方法を指定します。(DefaultはDownload)
「Download, Upload, UploadReply」が指定可能です。
-UseStoredCredentialAuthenticationTargetValue指定した対象サーバに対してWindows資格情報マネージャーに保存されている資格情報を使用するかどうか指定します。
-WhatIfSwitch実行するとどうなるかを表示します。

〜参考〜

Start-BitsTransfer (BitsTransfer) | Microsoft Docs

[同期ダウンロード]

PS D:¥> Start-BitsTransfer -Source http://www.test.com/test.txt -Destination D:¥test1¥test.txt

[非同期ダウンロード]

PS D:¥> Start-BitsTransfer -Source http://www.test.com/test.txt -Destination D:¥test1¥test.txt -Asynchronous -Priority High

その他オプションについては、本記事では割愛します。

BITS転送によるファイルアップロード

BITSによるアップロードを行う場合はIISの機能として「BITSサーバ拡張」をインストールし、ファイルのアップロード許可をする必要があります。

アップロードする場合は「Start-BitsTransfer -TransferType Upload」を指定します。

PS D:¥> Start-BitsTransfer -Source D:¥test1¥test.txt -Destination http://www.test.com/test.txt -Asynchronous -Priority High -TransferType Upload

BITSジョブの確認

BITSジョブの状況は下記コマンドにて確認することができます。

Get-BitsTransfer
オプションタイプ説明
-AllUsersSwitch全てのユーザが所有するBITS転送ジョブを取得することが可能となります。
-JobIdGuid[]指定したジョブIDのジョブステータスを取得することができます。
-NameString[]指定したジョブ名のジョブステータスを取得することができます。

〜参考〜
Get-BitsTransfer (BitsTransfer) | Microsoft Docs

[自身のBITSジョブを取得する]

PS D:\> Get-BitsTransfer

JobId                   DisplayName             TransferType            JobState                OwnerAccount
-----                   -----------             ------------            --------                ------------
1ef8c549-7a92-4173-b... BitsJobTransfer         Download                Transferred             DOMAIN01\user01
2c8302d5-3f44-4981-8... BitsJobTransfer         Download                Transferred             DOMAIN01\user01

[すべてのユーザのジョブを取得する]

PS D:\> Get-BitsTransfer -AllUsers

JobId                   DisplayName             TransferType            JobState                OwnerAccount
-----                   -----------             ------------            --------                ------------
07acbe90-7d25-4d05-a... BitsJobTransfer           Download                Suspended               DOMAIN01\user01
c0dd3d8c-c3a2-4562-8... BitsJobTransfer           Download                Transferred             DOMAIN01\user02

BITSジョブステータスが「Transferred」になっている場合は転送が完了している状態です。

しかし、ジョブ自体は終了していない状態のため、ジョブを終了させる必要があります。

BITSジョブを終了させる場合は、下記Cmdletを実行します。

Complete-BitsTransfer

上記Cmdlet実行後に再度Get-Transferをしてみると、BITSジョブが表示されないことが確認できます。

BITSジョブの再開および中断

実行しているBITSジョブを中断したい場合は下記Cmdletを実行します。

Suspend-BitsTransfer
オプションタイプ説明
-BitsJobBitsJob[]Get-BitsTransfer1で取得したBitsJobオブジェクトを指定します。
-ConfirmSwitch転送実行前に確認を求めるプロンプトを表示します。
-WhatIfSwitch実行するとどうなるかを表示します。

〜参考〜

Suspend-BitsTransfer (BitsTransfer) | Microsoft Docs

[BITSジョブの中断]

PS D:\> Get-BitsTransfer

JobId                   DisplayName             TransferType            JobState                OwnerAccount
-----                   -----------             ------------            --------                ------------
1ef8c549-7a92-4173-b... BitsJobTransfer         Download                Transferring             DOMAIN01\user01
2c8302d5-3f44-4981-8... BitsJobTransfer         Download                Transferring             DOMAIN01\user01

PS D:¥> $job = Get-BItsTransfer
PS D:¥> Suspend-BitsTransfer -BitsJob $job
PS D:\> Get-BitsTransfer

JobId                   DisplayName             TransferType            JobState                OwnerAccount
-----                   -----------             ------------            --------                ------------
1ef8c549-7a92-4173-b... BitsJobTransfer         Download                Suspended             DOMAIN01\user01
2c8302d5-3f44-4981-8... BitsJobTransfer         Download                Suspended             DOMAIN01\user01

ジョブの再開については、下記のCmdletを利用します。

Resume-BitsTransfer
オプションタイプ説明
-BitsJobBitsJob[]Get-BitsTransfer1で取得したBitsJobオブジェクトを指定します。
-AsynchronousSwitch非同期で処理する場合に指定します。
-ConfirmSwitch転送実行前に確認を求めるプロンプトを表示します。
-WhatIfSwitch実行するとどうなるかを表示します。

〜参考〜

Resume-BitsTransfer (BitsTransfer) | Microsoft Docs

[BITSジョブの再開]

PS D:\> Get-BitsTransfer

JobId                   DisplayName             TransferType            JobState                OwnerAccount
-----                   -----------             ------------            --------                ------------
1ef8c549-7a92-4173-b... BitsJobTransfer         Download                Suspended             DOMAIN01\user01
2c8302d5-3f44-4981-8... BitsJobTransfer         Download                Suspended             DOMAIN01\user01


PS D:¥> $job = Get-BItsTransfer
PS D:¥> Resume-BitsTransfer -BitsJob $job
PS D:\> Get-BitsTransfer

JobId                   DisplayName             TransferType            JobState                OwnerAccount
-----                   -----------             ------------            --------                ------------
1ef8c549-7a92-4173-b... BitsJobTransfer         Download                Transferring             DOMAIN01\user01
2c8302d5-3f44-4981-8... BitsJobTransfer         Download                Transferring             DOMAIN01\user01

途中でBITS設定を変更する

BITSジョブの設定で途中から設定を変更したい場合は、下記Cmdletを利用する

Set-BitsTransfer
オプションタイプ説明
-BitsJobBitsJob[]Get-BitsTransfer1で取得したBitsJobオブジェクトを指定します。
-ConfirmSwitch転送実行前に確認を求めるプロンプトを表示します。
-CredentialPSCredentialユーザ認証するための資格情報を指定します。
-DescriptionString転送ジョブに説明を追加します。文字制限は1024文字となります。
-DisplayNameStringBITSジョブ名を指定します。
-PriorityStrubgBITSジョブの優先度を設定します。
「Foreground, High, Normal, Low」が指定可能です。
-ProxyAuthenticationStringWebプロキシを利用する場合の認証方法を指定します。
「Basic, Digest, Ntlm, Negotiate, Passport」がして可能です。
-ProxyBypassString[]直接接続するホスト名のリストを指定します。
-ProxyCredentialPSCredentialプロキシ認証するための資格情報を指定します。
-ProxyListUri[]使用するプロキシのリストをい指定します。
-ProxyUsageStringプロキシの利用方法を指定します。
「SystemDefault, NoProxy, AutoDetect, Override」が指定可能です。
-RetryIntervalInt32BITSにて一時的にエラーが発生した場合の施行までの待機時間を指定する(Default:10分)
-RetryTimeoutInt32BITSにて一時的にエラーが発生した場合の施行する時間の長さを指定します(Default:14日)
-TransferPolicyCostStates転送スケジュールを許可するネットワークコストの状態を指定します。
-UseStoredCredentialAuthenticationTargetValue指定した対象サーバに対してWindows資格情報マネージャーに保存されている資格情報を使用するかどうか指定します。
-WhatIfSwitch実行するとどうなるかを表示します。

〜参考〜

Set-BitsTransfer (BitsTransfer) | Microsoft Docs

[優先度を変更]

PS D:\> $jobs = Get-BitsTransfer -JobId 10778CFA-C1D7-4A82-8A9D-80B19224879C
PS D:\> Set-BitsTransfer -BitsJob $jobs -Priority High

BITSジョブを削除する

BITSジョブを削除する場合は、下記Cmdletを利用する

Remove-BitsTransfer
オプションタイプ説明
-BitsJobBitsJob[]Get-BitsTransfer1で取得したBitsJobオブジェクトを指定します。
-ConfirmSwitch転送実行前に確認を求めるプロンプトを表示します。
-WhatIfSwitch実行するとどうなるかを表示します。

〜参考〜

Remove-BitsTransfer (BitsTransfer) | Microsoft Docs

[すべてのBITSジョブの削除]

PS D:\> $jobs = Get-BitsTransfer -AllUsers
PS D:\> Remove-BitsTransfer -BitsJob $jobs

さいごに

BITSTransferを利用したファイル転送で注意が必要なのが、Complete-BitsTransferをし忘れないことです。

また、複数のSource/DestinationをCSVに記載しておき、シーケンシャルに転送を行うこともできます。

Source,Destination
http://test1.com/test1.txt,D:
¥test1¥test1.txt
http://test1.com/test2.txt,D:
¥test1¥test2.txt
http://test1.com/test3.txt,D:
¥test1¥test3.txt
http://test1.com/test4.txt,D:
¥test1¥test4.txt
PS D:\> Import-Csv test.csv | Start-BitsTransfer 

以上、是非参考にしてみてください。

タイトルとURLをコピーしました