Web API

WebUI とは何ですか?

これは µTorrent に組み込まれている機能で、ローカルとリモートの両方のアプリケーションからほぼ完全に µTorrent を制御および設定するとともに、利用可能な大部分のデータを表示します。通常、この機能は、弊社が提供する WebUI とともに Web ブラウザで使用されますが、どのアプリケーションでも Web API を使用して直接 µTorrent とやり取りすることができます。

Web API とは何ですか?

µTorrent に組み込まれている WebUI 機能へのアクセスは、この API によって行われます。これは µTorrent が提供している標準 WebUI から独立しており、クライアント側では、このオプションを有効にする以外、何も設定する必要がありません。

この API は安定しており、ほぼ完成しています。不足している機能はやがて追加され、既存のアプリケーションとの互換性もほぼ維持されます。そのため、µTorrent の今後のバージョンでは、アプリケーションを µTorrent に連携させるための作業はほとんど不要になります。

Github では、現行の WebUI 以外にも、API を利用している選り抜きのプロジェクトを利用できます。API の重要なアップデートは、さまざまな個所で言及されます。

フォーラムの WebUI セクションでも、その他の多数のプロジェクトを利用できます。自身のプロジェクトを投稿することもできます。

API アクセスに関する一般的注意

µTorrent の設定 ([設定] - [WebUI]) で有効にすると、API にアクセスするベース URI は次のようになります。 http://[IP]:[PORT]/gui/. コールにより返されるデータは JSON 形式になります。

認証は基本的な HTTP 認証により行われます。ゲストアカウント (有効な場合) ではコールのサブセットに限定されます。トレントの状態と getsettings を修正するアクションコールは却下されます。

特に断りがない限り、各コールは HTTP GET を使用して実行されます。パラメータは、通常どおりベース URI に追加されます。先頭のパラメータは常にコマンドです (?list、?action など)。

大部分のアクションコマンドは受け渡すハッシュを必要とします。これは、すべてのトレントのリストから取得した、トレントの情報ハッシュです。各ハッシュの長さは 40 文字 (ASCII 文字列) までです。ただし、一部のコマンドには、次のように、複数の情報ハッシュを連結して含めることができます。 http://[IP]:[PORT]/gui/?action=[アクション]&hash=[TORRENT HASH 1]&hash=[TORRENT HASH 2]&... これによって、必要なリクエスト数を減らすことができます。

?action=setsetting または ?action=setprops によってブーリアン値を設定すると、その値パラメータは、真または偽を示す文字列ではなく、「真」の場合は 0、「偽」の場合は 1 として送信されます。

トークン認証システム (重要)

CSRF (クロスサイトリクエストフォージェリ) を回避するために、µTorrent にはトークン認証システムが実装されています。WebUI バックエンドを使用するアプリケーションを開発している開発者はすべて、このシステムに対するサポートを実装する必要があります。これを実装しないと、ユーザーが webui.token_auth を有効にしている場合、アプリケーションが正常に動作しません。

1.8.3 以前のバージョンでは、トークン認証はデフォルトで無効になります (ユーザーは手動で有効にすることができます)。しかし、今後のバージョンにおいて、このオプションはデフォルトで有効になる予定ですので、将来の互換性のために、現在このサポートを実装する必要があるのです。

設定の変更

設定の基本パラメータは ?action=getsettings です。このパラメータを単独で使用すると、以下の形式で設定のリストが返されます。

{
	"build": BUILD NUMBER (整数値),
	"settings": [
	[
	OPTION NAME (文字列),
	TYPE* (整数値),
	VALUE (文字列)	],
	...
	]
	}

OPTION NAME は設定の名前です。ここでは各設定の名前を示しません。バージョンに応じて設定の一部 (特に高度な設定) が異なりますし、その大部分は一目で役割がわかるからです。ただし、参考のために、1.8.2 のほぼ完全なリストがここに示されています。

* TYPE: TYPE は、VALUE 文字列に含まれているデータのタイプを示す整数値です。以下は、TYPE の一覧とそれに対応する VALUE タイプを示しています。

0 = 整数
1 = ブーリアン
2 = 文字列

設定を変更するには、次の URI を使用します: http://[IP]:[PORT]/gui/?action=setsetting&s=[SETTING]&v=[VALUE]

URI の s= と v= を連結することにより、1 つのリクエストで複数の設定を変更できます。s= は設定を定義し、v= はその直前の s= の値を示します。

たとえば、グローバルアップロードキャップを 10KiB/s に設定し、グローバルダウンロードキャップを 40KiB/s に設定するには、次のような URI をリクエストします。 http://[IP]:[PORT]/gui/?action=setsetting&s=max_ul_rate&v=10&s=max_dl_rate&v=40

トレント/ラベルリスト

すべてのトレントのリストを取得するには、次のようにリクエストします: http://[IP]:[PORT]/gui/?list=1 . 以下の形式でトレントが返されます。

{
	"build": BUILD NUMBER (整数値),
	"label": [
	[
	LABEL (文字列),
	TORRENTS IN LABEL (整数値)	],
	...
	],
	"torrents": [
	[
	HASH (文字列),
	STATUS* (整数値),
	NAME (文字列),
	SIZE (整数値、バイト単位),
	PERCENT PROGRESS (整数値、パーミル),
	DOWNLOADED (整数値、バイト単位),
	UPLOADED (整数値、バイト単位),
	RATIO (整数値、パーミル),
	UPLOAD SPEED (整数値、1 秒当たりのバイト数),
	DOWNLOAD SPEED (整数値、1 秒当たりのバイト数),
	ETA (整数値、秒単位),
	LABEL (文字列),
	PEERS CONNECTED (整数値),
	PEERS IN SWARM (整数値),
	SEEDS CONNECTED (整数値),
	SEEDS IN SWARM (整数値),
	AVAILABILITY (整数値、1/65535 単位),
	TORRENT QUEUE ORDER (整数値),
	REMAINING (整数値、バイト単位)	],
	...
	],
	"torrentc": CACHE ID** (整数文字列)	}

* STATUS: STATUS は整数値で示されるビットフィールドで、対応するステータスの値を合計することにより取得されます。

1 = 開始
2 = チェック中
4 = チェック後に開始
8 = チェック
16 = エラー
32 = 一時停止
64 = 待機
128 = 読込み

たとえば、トレントジョブのステータスが 201 = 128 + 64 + 8 + 1 の場合、ジョブは読み込まれ、待機し、チェックされ、そして開始されます。STATUS に特定のステータスが含まれているかどうか調べるには、ビット単位の論理 AND 演算子を使用する必要があります。

** CACHE ID: CACHE ID は、データに対して µTorrent がランダムに生成する番号です。次のようにトレントリストを要求した場合: http://[IP]:[PORT]/gui/?list=1&cid=[CACHE ID], CACHE ID と一致したリストの送信後に変更された項目だけが返されます。これを使用すると、µTorrent から送信されるデータ量が減少するため、帯域幅使用量を最少化し、構文解析を単純化することができます。この場合、2 つの新しいディクショナリーキーが「トレント」に置き換わり、返される JSON は以下のようになります。

{
	"build": BUILD NUMBER (整数値),
	"label": [
	[
	LABEL (文字列),
	TORRENTS IN LABEL (整数値)	],
	...
	],
	"torrentp": [
	[
	HASH (文字列),
	STATUS (整数値),
	NAME (文字列),
	SIZE (整数値、バイト単位),
	PERCENT PROGRESS (整数値、パーミル),
	DOWNLOADED (整数値、バイト単位),
	UPLOADED (整数値、バイト単位),
	RATIO (整数値、パーミル),
	UPLOAD SPEED (整数値、1 秒当たりのバイト数),
	DOWNLOAD SPEED (整数値、1 秒当たりのバイト数),
	ETA (整数値、秒単位),
	LABEL (文字列),
	PEERS CONNECTED (整数値),
	PEERS IN SWARM (整数値),
	SEEDS CONNECTED (整数値),
	SEEDS IN SWARM (整数値),
	AVAILABILITY (整数値、1/65535 単位),
	TORRENT QUEUE ORDER (整数値),
	REMAINING (整数値、バイト単位)        ],
	...
	],
	"torrentm": [
	HASH (文字列),
	...
	]
	"torrentc": CACHE ID (整数文字列)	}

「torrentp」配列は、CACHE ID との照合以降に変更されたトレントジョブのリストを含んでおり、形式は「torrents」配列と同じです。「torrentm」配列には、CACHE ID との照合以降に削除されたトレントジョブのハッシュのリストが含まれています。新しい CACHE ID が torrentc に割り当てられ、これを次回のリストのリクエストで使用できます。

ファイルリスト

トレントジョブのファイルリストを取得するには、次の URI をリクエストします: http://[IP]:[PORT]/gui/?action=getfiles&hash=[TORRENT HASH] . 以下の値を返します。

{
	"build": BUILD NUMBER (整数値),
	"files": [
	HASH (文字列),
	[
	[
	FILE NAME (文字列),
	FILE SIZE (整数値、バイト単位),
	DOWNLOADED (整数値、バイト単位),
	PRIORITY* (整数値)	],
	...
	]
	]
}

* PRIORITY: ファイルの優先順位を示す整数値です。以下は、PRIORITY の値の一覧とそれらの意味を示しています。

0 = ダウンロード不可
1 = 低い順位
2 = 通常の順位
3 = 高い順位

このコマンドでは複数のハッシュを指定できます。複数の「ファイル」のキー/値のペアが返されます。

トレントジョブのプロパティ

トレントジョブの各種プロパティのリストを取得するには、次のようにリクエストします: http://[IP]:[PORT]/gui/?action=getprops&hash=[TORRENT HASH] . 以下の値を返します。

{
	"build": BUILD NUMBER (整数値),
	"props": [
	{
	"hash": HASH (文字列),
	"trackers": TRACKERS* (文字列),
	"ulrate": UPLOAD LIMIT (整数値、1 秒当たりのバイト数),
	"dlrate": DOWNLOAD LIMIT (整数値、1 秒当たりのバイト数),
	"superseed": INITIAL SEEDING** (整数値),
	"dht": USE DHT** (整数値),
	"pex": USE PEX** (整数値),
	"seed_override": OVERRIDE QUEUEING** (整数値),
	"seed_ratio": SEED RATIO (整数値、パーミル),
	"seed_time": SEEDING TIME*** (整数値、秒単位),
	"ulslots": UPLOAD SLOTS (整数値)	}
	]
}

* TRACKER: トレントジョブで使用されるトラッカーのリストです。各行は改行され、後に改行文字 (\r\n) が続きます。

** INITIAL SEEDING/USE DHT/USE PEX/OVERRIDE QUEUEING: これらのオプションはすべて、状態を示す整数値です。以下は、可能な値の一覧とそれらの意味を示しています。

-1 = 不可
0 = 無効
1 = 有効

*** SEEDING TIME: µTorrent がトレントのダウンロードを完了した後に、シードを続ける最少時間数 (秒単位) を示す整数値です。値 0 (ゼロ) は、最少シード時間がないことを示します。

トレントのプロパティを変更するには、次の URI を使用します: http://[IP]:[PORT]/gui/?action=setprops&hash=[TORRENT HASH]&s=[PROPERTY]&v=[VALUE]

s= と v= のペアを付け加えることによって、一度に複数のプロパティを変更できます。また、別の hash= value に s= と v= のペアを付け加えると、1 つのリクエストで複数のトレントジョブを変更できます。後に続く s= と v= のペアは、指定された最後のハッシュのプロパティを変更します。

たとえば、[TORRENT HASH 1] のアップロード制限速度を 10 KiB/s、ダウンロード制限速度を 20 KiB/s に設定すると同時に、[TORRENT HASH 2] に対して 4 つのアップロードスロットを設定するには、次のように URI をリクエストします: http://[IP]:[PORT]/gui/?action=setprops&hash=[TORRENT HASH 1]&s=ulrate&v=10240&s=dlrate&v=20480&hash=[TORRENT HASH 2]&s=ulslots&v=4

アクション

このセクションでは、API がサポートしているその他の可能なアクションをすべてを示します。

http://[IP]:[PORT]/gui/?action=start&hash=[TORRENT HASH]

µTorrent は指定されたトレントジョブを開始します。複数のハッシュを指定して、複数のトレントジョブを処理することができます。

http://[IP]:[PORT]/gui/?action=stop&hash=[TORRENT HASH]

µTorrent は指定されたトレントジョブを停止します。複数のハッシュを指定して、複数のトレントジョブを処理することができます。

http://[IP]:[PORT]/gui/?action=pause&hash=[TORRENT HASH]

µTorrent は指定されたトレントジョブを一次停止します。複数のハッシュを指定して、複数のトレントジョブを処理することができます。

http://[IP]:[PORT]/gui/?action=forcestart&hash=[TORRENT HASH]

µTorrent は指定されたトレントジョブを強制的に開始します。複数のハッシュを指定して、複数のトレントジョブを処理することができます。

http://[IP]:[PORT]/gui/?action=unpause&hash=[TORRENT HASH]

µTorrent は指定されたトレントジョブの一次停止を解除します。複数のハッシュを指定して、複数のトレントジョブを処理することができます。

http://[IP]:[PORT]/gui/?action=recheck&hash=[TORRENT HASH]

µTorrent は指定されたトレントジョブのトレントコンテンツを再チェックします。複数のハッシュを指定して、複数のトレントジョブを処理することができます。

http://[IP]:[PORT]/gui/?action=remove&hash=[TORRENT HASH]

指定されたトレントジョブをトレントジョブリストからを削除します。複数のハッシュを指定して、複数のトレントジョブを処理することができます。このアクションは、オプション [可能ならごみ箱に捨てる] の設定に従います。

http://[IP]:[PORT]/gui/?action=removedata&hash=[TORRENT HASH]

このアクションは、トレントジョブリストから指定されたトレントジョブを削除し、対応するトレントコンテンツをディスクから削除します。複数のハッシュを指定して、複数のトレントジョブを処理することができます。このアクションは、オプション [可能ならごみ箱に捨てる] の設定に従います。

http://[IP]:[PORT]/gui/?action=setprio&hash=[TORRENT HASH]&p=[PRIORITY]&f=[FILE INDEX]

トレントジョブの特定ファイルの優先順位を設定します。可能な優先順位は、「getfiles」により返される値で示されます。ファイルは、「getfiles」により返されるリスト内のファイルのゼロベースインデックスを使用して指定されます。このアクションに対するコールでは 1 つの優先順位のみ指定できますが、複数のファイルを指定することが可能です。

http://[IP]:[PORT]/gui/?action=add-url&s=[TORRENT URL]

特定の URL からトレントジョブを追加します。クッキーを要求するサーバーに対して、COOKIE: メソッド (ここを参照) をいっしょに送信できます。文字列は URL エンコードする必要があります。

http://[IP]:[PORT]/gui/?action=add-file

他のアクションとは異なり、このアクションは HTTP GET の代わりに HTTP POST を使用して、µTorrent にデータを提供します。HTTP の形式に対して、enctype 属性「multipart/form-data」と、µTorrent にアップロードするファイルのローカルパスを保存する入力フィールド (名前「torrent_file」、タイプ「file」) を指定する必要があります。

制限事項

トレントのデータを保存するパスを指定することはできません。getsettings によってデフォルトのダウンロードフォルダーを設定することができますが、個々のトレントに対して設定することはできません。これは今後のリリースで修正される予定です。

トレントジョブの個々のファイルをリネームしたり、再配置したりすることはできません。

API には RSS は実装されていません。

謝辞

フォーラムで膨大な数の API について文書化してくださった Ultima 氏に感謝いたします。本ページの大部分の情報は、同氏による文書化から得たものです。

Web API

目次

WebUI とは何ですか?

Web API とは何ですか?

API アクセスに関する一般的注意

トークン認証システム (重要)

設定の変更

トレント/ラベルリスト

ファイルリスト

トレントジョブのプロパティ

アクション

http://[IP]:[PORT]/gui/?action=start&hash=[TORRENT HASH]

http://[IP]:[PORT]/gui/?action=stop&hash=[TORRENT HASH]

http://[IP]:[PORT]/gui/?action=pause&hash=[TORRENT HASH]

http://[IP]:[PORT]/gui/?action=forcestart&hash=[TORRENT HASH]

http://[IP]:[PORT]/gui/?action=unpause&hash=[TORRENT HASH]

http://[IP]:[PORT]/gui/?action=recheck&hash=[TORRENT HASH]

http://[IP]:[PORT]/gui/?action=remove&hash=[TORRENT HASH]

http://[IP]:[PORT]/gui/?action=removedata&hash=[TORRENT HASH]

http://[IP]:[PORT]/gui/?action=setprio&hash=[TORRENT HASH]&p=[PRIORITY]&f=[FILE INDEX]

http://[IP]:[PORT]/gui/?action=add-url&s=[TORRENT URL]

http://[IP]:[PORT]/gui/?action=add-file

制限事項

謝辞

@uTorrent

µTorrent Blog

コミュニティフォーラム

Web API

目次

WebUI とは何ですか?

Web API とは何ですか?

API アクセスに関する一般的注意

トークン認証システム (重要)

設定の変更

トレント/ラベル リスト

ファイル リスト

トレント ジョブのプロパティ

アクション

http://[IP]:[PORT]/gui/?action=start&hash=[TORRENT HASH]

http://[IP]:[PORT]/gui/?action=stop&hash=[TORRENT HASH]

http://[IP]:[PORT]/gui/?action=pause&hash=[TORRENT HASH]

http://[IP]:[PORT]/gui/?action=forcestart&hash=[TORRENT HASH]

http://[IP]:[PORT]/gui/?action=unpause&hash=[TORRENT HASH]

http://[IP]:[PORT]/gui/?action=recheck&hash=[TORRENT HASH]

http://[IP]:[PORT]/gui/?action=remove&hash=[TORRENT HASH]

http://[IP]:[PORT]/gui/?action=removedata&hash=[TORRENT HASH]

http://[IP]:[PORT]/gui/?action=setprio&hash=[TORRENT HASH]&p=[PRIORITY]&f=[FILE INDEX]

http://[IP]:[PORT]/gui/?action=add-url&s=[TORRENT URL]

http://[IP]:[PORT]/gui/?action=add-file

制限事項

謝辞

@uTorrent

µTorrent Blog

コミュニティ フォーラム

トレント/ラベルリスト

ファイルリスト

トレントジョブのプロパティ

コミュニティフォーラム