[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
名前 種類
制御の有効状態 EnableBITSMaxBandwidth REG_DWORD 0 or 1
特定時間内のバックグラウンド転送レート MaxTransferRateOnSchedule REG_DWORD 1~4294967200
特定時間の開始時刻 MaxBandwidthValidFrom REG_DWORD 0~23
特定時間の終了時刻 MaxBandwidthValidTo REG_DWORD 0~23
未使用で利用可能な帯域幅利用有無 UseSystemMaximum REG_DWORD 0 or 1
特定時間外のバックグラウンド転送レート MaxTransferRateOffSchedule REG_DWORD 1~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
オプション タイプ 説明
-Asynchronous Switch 非同期で処理する場合に指定します。
-Authentication String データ転送時の認証方法を指定します。
「Basic, Digest, Ntlm, Negotiate, Passport」が指定可能です。
-Confirm Switch 転送実行前に確認を求めるプロンプトを表示します。
-Credential PSCredential ユーザ認証するための資格情報を指定します。
-Description String 転送ジョブに説明を追加します。文字制限は1024文字となります。
-Destination String[] 転送先の場所と転送するファイルの名前を含む配列を指定します。
-DisplayName String BITSジョブ名を指定します。
-Priority Strubg BITSジョブの優先度を設定します。
「Foreground, High, Normal, Low」が指定可能です。
-ProxyAuthentication String Webプロキシを利用する場合の認証方法を指定します。
「Basic, Digest, Ntlm, Negotiate, Passport」がして可能です。
-ProxyBypass String[] 直接接続するホスト名のリストを指定します。
-ProxyCredential PSCredential プロキシ認証するための資格情報を指定します。
-ProxyList Uri[] 使用するプロキシのリストをい指定します。
-ProxyUsage String プロキシの利用方法を指定します。
「SystemDefault, NoProxy, AutoDetect, Override」が指定可能です。
-RetryInterval Int32 BITSにて一時的にエラーが発生した場合の施行までの待機時間を指定する(Default:10分)
-RetryTimeout Int32 BITSにて一時的にエラーが発生した場合の施行する時間の長さを指定します(Default:14日)
-Source String[] 転送するファイルのソースの場所と名前を指定します。
-Suspended Switch BITS転送ジョブを一時停止します。
-TransferPolicy CostStates 転送スケジュールを許可するネットワークコストの状態を指定します。
-TransferType String 転送方法を指定します。(DefaultはDownload)
「Download, Upload, UploadReply」が指定可能です。
-UseStoredCredential AuthenticationTargetValue 指定した対象サーバに対してWindows資格情報マネージャーに保存されている資格情報を使用するかどうか指定します。
-WhatIf Switch 実行するとどうなるかを表示します。

〜参考〜

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
オプション タイプ 説明
-AllUsers Switch 全てのユーザが所有するBITS転送ジョブを取得することが可能となります。
-JobId Guid[] 指定したジョブIDのジョブステータスを取得することができます。
-Name String[] 指定したジョブ名のジョブステータスを取得することができます。

〜参考〜
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
オプション タイプ 説明
-BitsJob BitsJob[] Get-BitsTransfer1で取得したBitsJobオブジェクトを指定します。
-Confirm Switch 転送実行前に確認を求めるプロンプトを表示します。
-WhatIf Switch 実行するとどうなるかを表示します。

〜参考〜

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
オプション タイプ 説明
-BitsJob BitsJob[] Get-BitsTransfer1で取得したBitsJobオブジェクトを指定します。
-Asynchronous Switch 非同期で処理する場合に指定します。
-Confirm Switch 転送実行前に確認を求めるプロンプトを表示します。
-WhatIf Switch 実行するとどうなるかを表示します。

〜参考〜

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
オプション タイプ 説明
-BitsJob BitsJob[] Get-BitsTransfer1で取得したBitsJobオブジェクトを指定します。
-Confirm Switch 転送実行前に確認を求めるプロンプトを表示します。
-Credential PSCredential ユーザ認証するための資格情報を指定します。
-Description String 転送ジョブに説明を追加します。文字制限は1024文字となります。
-DisplayName String BITSジョブ名を指定します。
-Priority Strubg BITSジョブの優先度を設定します。
「Foreground, High, Normal, Low」が指定可能です。
-ProxyAuthentication String Webプロキシを利用する場合の認証方法を指定します。
「Basic, Digest, Ntlm, Negotiate, Passport」がして可能です。
-ProxyBypass String[] 直接接続するホスト名のリストを指定します。
-ProxyCredential PSCredential プロキシ認証するための資格情報を指定します。
-ProxyList Uri[] 使用するプロキシのリストをい指定します。
-ProxyUsage String プロキシの利用方法を指定します。
「SystemDefault, NoProxy, AutoDetect, Override」が指定可能です。
-RetryInterval Int32 BITSにて一時的にエラーが発生した場合の施行までの待機時間を指定する(Default:10分)
-RetryTimeout Int32 BITSにて一時的にエラーが発生した場合の施行する時間の長さを指定します(Default:14日)
-TransferPolicy CostStates 転送スケジュールを許可するネットワークコストの状態を指定します。
-UseStoredCredential AuthenticationTargetValue 指定した対象サーバに対してWindows資格情報マネージャーに保存されている資格情報を使用するかどうか指定します。
-WhatIf Switch 実行するとどうなるかを表示します。

〜参考〜

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
オプション タイプ 説明
-BitsJob BitsJob[] Get-BitsTransfer1で取得したBitsJobオブジェクトを指定します。
-Confirm Switch 転送実行前に確認を求めるプロンプトを表示します。
-WhatIf Switch 実行するとどうなるかを表示します。

〜参考〜

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 

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