Web API

Inhaltsverzeichnis

Was ist die WebUI?
Was ist eine Web API?
Allgemeine Hinweise zum API-Zugang
Tokenauthentifizierungssystem (wichtig!)
Einstellungen ändern
Torrent-/Bezeichnungsliste
Dateiliste
Torrent-Jobeigenschaften
Aktionen
Beschränkungen
Punkte

Was ist die WebUI?

Dies ist eine in µTorrent integrierte Funktionalität zur fast vollständigen Kontrolle und Konfiguration von µTorrent über sowohl lokale als auch dezentrale Applikationen sowie zur Anzeige der meisten verfügbaren Daten. In der Regel wird diese Funktionalität in einem Webbrowser mit der von uns bereitgestellten WebUI verwendet, mit der Web API kann jedoch jede Applikation direkt mit µTorrent kommunizieren.

Was ist eine Web API?

Hierbei handelt es sich um eine API für den Zugriff auf Funktionen der in µTorrent integrierten WebUI. Diese ist unabhängig von der von µTorrent bereitgestellten Standard-WebUI und erfordert keinerlei Aktivität auf der Client-Seite, abgesehen von der Aktivierung der Option.

Die API ist stabil und weitgehend vollständig. Fehlende Funktionen werden im Laufe der Zeit ergänzt und die Kompatibilität mit vorhandenen Applikationen wird im Allgemeinen eingehalten, sodass wenige oder keine Anpassungen erforderlich sind, damit Ihre Applikation auch mit künftigen Versionen von µTorrent funktioniert.

Die aktuelle WebUI sowie ausgewählte Projekte, von denen die API genutzt wird, sind auf Github verfügbar. Wichtige Updates für die API werden sowohl hier als auch dort erwähnt.

Viele andere Projekte sind im WebUI-Abschnitt der Foren zu finden. Sie können Ihr Projekt auch hier veröffentlichen!

Allgemeine Hinweise zum API-Zugang

Nachdem die Option in den µTorrent-Einstellungen (Einstellungen -> WebUI) aktiviert wurde, wird über folgende Basis-URI darauf zugegriffen http://[IP]:[PORT]/gui/. Die durch Aufrufe zurückgegebenen Daten liegen im JSON-Format vor.

Die Authentifizierung erfolgt durch die grundlegende HTTP-Authentifizierung. Der Gäste-Account, sofern aktiviert, ist auf ausgewählte Aufrufe beschränkt. Aktionsaufrufe, die den Torrent-Status ändern, sowie "getsettings" sind nicht zulässig.

Sofern nicht anderweitig angegeben, erfolgt jeder Aufruf mit "HTTP GET". Parameter werden wie gewöhnlich auf der Basis-URI hinzugefügt. Der erste Parameter sollte immer der Befehl sein (z. B. "?list" oder "?action").

Bei den meisten Aktionsbefehlen muss ein Hash übergeben werden. Hierbei handelt es sich um den Info-Hash des Torrents, der durch die Auflistung aller Torrents erhalten wird. Jeder Hash ist eine aus 40 Zeichen bestehende ASCII-Zeichenfolge. Manche Befehle akzeptieren mehrere aneinandergereihte Info-Hashes, z. B.: http://[IP]:[PORT]/gui/?action=[AKTION]&hash=[TORRENT HASH 1]&hash=[TORRENT HASH 2]&... Auf diese Weise wird die Anzahl der erforderlichen Anfragen verringert.

Wenn Boolean-Werte entweder durch ?action=setsetting oder ?action=setprops definiert werden, sollte der Werteparameter als 0 für "falsch" bzw. 1 für "wahr" anstelle der Zeichenfolge "wahr" bzw. "falsch" gesendet werden.

Tokenauthentifizierungssystem (wichtig!)

In µTorrent wurde ein Token-Authentifizierungssystem implementiert, um Site-übergreifende Aufruf-Manipulationen (Cross-Site Request Forgery, CSRF) zu verhindern. Alle Entwickler, die Applikationen erstellen, die das WebUI-Backend verwenden, MÜSSEN die Unterstützung dieses Systems implementieren, da die Applikation anderenfalls fehlschlägt, wenn der Benutzer webui.token_auth aktiviert hat.

In Version 1.8.3 oder früher ist die Authentifizierung standardmäßig deaktiviert (sie kann vom Benutzer jedoch manuell aktiviert werden). Diese Option wird in künftigen Versionen jedoch standardmäßig AKTIVIERT sein, sodass die Implementierung der Unterstützung eine Anforderung für künftige Kompatibilität darstellt.

Einstellungen ändern

Der Basisparameter für Einstellungen lautet ?action=getsettings. Wird dieser Parameter alleinstehend verwendet, wird eine Liste der Einstellungen im folgenden Format ausgegeben:

{
	"build": BUILD-NUMMER (Ganzzahl),
	"settings": [
	[
	OPTIONSNAME (Zeichenfolge),
	TYP* (Ganzzahl),
	WERT (Zeichenfolge)	],
	...
	]
	}

OPTIONSNAME ist der Name der Einstellung. Sie sind hier nicht aufgeführt, da manche Einstellungen (insbesondere im erweiterten Modus) je nach Version unterschiedlich sind und sich in den meisten Fällen selbst erklären. Hier finden Sie jedoch eine fast vollständige Liste für Version 1.8.2 als Referenz.

* TYP: TYP ist ein ganzzahliger Wert, der angibt, welche Art von Daten die Zeichenfolge WERT enthält. In der folgenden Liste sind die möglichen TYPen sowie die entsprechenden WERT-Typen aufgeführt:

0 = Ganzzahl
1 = Boolescher Wert
2 = Zeichenfolge

Zur Änderung der Einstellungen kann folgende URI verwendet werden: http://[IP]:[PORT]/gui/?action=setsetting&s=[EINSTELLUNG]&v=[WERT]

Mehrere Einstellungen können mit einem einzigen Aufruf geändert werden, indem s= und v= in der URI miteinander verkettet werden. s= definiert die Einstellung und v= ist der Wert für das unmittelbar vorangehende s=.

Um z. B. die globale Upload-Begrenzung auf 10 KBit/s und die globale Download-Begrenzung auf 40 KBit/s festzulegen, würden Sie folgende URI abfragen: http://[IP]:[PORT]/gui/?action=setsetting&s=max_ul_rate&v=10&s=max_dl_rate&v=40

Torrent-/Bezeichnungsliste

Um die Liste aller Torrents zu erhalten, senden Sie folgende Anfrage: http://[IP]:[PORT]/gui/?list=1 . Hierdurch werden die Torrents in folgender Form zurückgegeben:

{
	"build": BUILD-NUMMER (Ganzzahl),
	"label": [
	[
	BEZEICHNUNG (Zeichenfolge),
	TORRENTS MIT DIESER BEZEICHNUNG (Ganzzahl)	],
	...
	],
	"torrents": [
	[
	HASH (Zeichenfolge),
	STATUS* (Ganzzahl),
	NAME (Zeichenfolge),
	GRÖSSE (Ganzzahl in Bytes),
	PROZENTUALER FORTSCHRITT (Ganzzahl in Promille),
	HERUNTERGELADEN (Ganzzahl in Bytes),
	HOCHGELADEN (Ganzzahl in Bytes),
	VERHÄLTNIS (Ganzzahl in Promille),
	UPLOAD-GESCHWINDIGKEIT (Ganzzahl in Bytes pro Sekunde),
	DOWNLOAD-GESCHWINDIGKEIT (Ganzzahl in Bytes pro Sekunde),
	ETA (Ganzzahl in Sekunden),
	BEZEICHNUNG (Zeichenfolge),
	VERBUNDENE PEERS (Ganzzahl),
	PEERS IM SCHWARM (Ganzzahl),
	VERBUNDENE SEEDS (Ganzzahl),
	SEEDS IM SCHWARM (Ganzzahl),
	VERFÜGBARKEIT (Ganzzahl in 1/65535ths),
	TORRENT-REIHENFOLGE IN DER WARTESCHLANGE (Ganzzahl),
	VERBLEIBENDE (Ganzzahl in Bytes)	],
	...
	],
	"torrentc": CACHE-ID** (Zeichenfolge Ganzzahl)	}

* STATUS: Der STATUS ist ein durch Ganzzahlen repräsentiertes Bitfeld, das durch Addieren der verschiedenen Werte der entsprechenden Status gebildet wird:

1 = Gestartet
2 = Überprüfung
4 = Start nach Überprüfung
8 = Überprüft
16 = Fehler
32 = Angehalten
64 = In Warteschlange
128 = Geladen

Verfügt z. B. ein Torrent-Job über den Status 201 = 128 + 64 + 8 + 1, so ist er geladen, in der Warteschlange, überprüft und gestartet. Um festzustellen, ob der angegebene STATUS einen bestimmten Status enthält, sollte ein bitweiser AND-Operator verwendet werden.

** CACHE-ID: Die CACHE-ID ist eine Zahl, die von µTorrent für die entsprechenden Daten zufällig erzeugt wird. Wird die Torrent-Liste mit http://[IP]:[PORT]/gui/?list=1&cid=[CACHE-ID], angefragt, werden nur die Elemente zurückgegeben, die sich seit dem Senden der Liste geändert haben, die der CACHE-ID entspricht. Auf diese Weise wird die Bandbreitennutzung minimiert und das Parsen vereinfacht, indem die Menge der von µTorrent gesendeten Daten verringert wird. In dieser Situation wird "torrents" durch zwei neue Wörterbuchschlüssel ersetzt und es wird folgendes JSON-Objekt zurückgegeben:

{
	"build": BUILD-NUMMER (Ganzzahl),
	"label": [
	[
	BEZEICHNUNG (Zeichenfolge),
	TORRENTS MIT DIESER BEZEICHNUNG (Ganzzahl)	],
	...
	],
	"torrentp": [
	[
	HASH (Zeichenfolge),
	STATUS (Ganzzahl),
	NAME (Zeichenfolge),
	GRÖSSE (Ganzzahl in Bytes),
	PROZENTUALER FORTSCHRITT (Ganzzahl in Promille),
	HERUNTERGELADEN (Ganzzahl in Bytes),
	HOCHGELADEN (Ganzzahl in Bytes),
	VERHÄLTNIS (Ganzzahl in Promille),
	UPLOAD-GESCHWINDIGKEIT (Ganzzahl in Bytes pro Sekunde),
	DOWNLOAD-GESCHWINDIGKEIT (Ganzzahl in Bytes pro Sekunde),
	ETA (Ganzzahl in Sekunden),
	BEZEICHNUNG (Zeichenfolge),
	VERBUNDENE PEERS (Ganzzahl),
	PEERS IM SCHWARM (Ganzzahl),
	VERBUNDENE SEEDS (Ganzzahl),
	SEEDS IM SCHWARM (Ganzzahl),
	VERFÜGBARKEIT (Ganzzahl in 1/65535ths),
	TORRENT-REIHENFOLGE IN DER WARTESCHLANGE (Ganzzahl),
	VERBLEIBENDE (Ganzzahl in Bytes)        ],
	...
	],
	"torrentm": [
	HASH (Zeichenfolge),
	...
	]
	"torrentc": CACHE-ID (Zeichenfolge Ganzzahl)	}

Das Feld "torrentp" enthält eine Liste der Torrent-Jobs, die sich seit der zugehörigen CACHE-ID geändert haben, und ist in Bezug auf das Format mit dem Feld "torrents" identisch. Das Feld "torrentm" enthält eine Liste der Hashes für Torrent-Jobs, die seit der zugehörigen CACHE-ID entfernt wurden. In "torrentc" wird eine neue CACHE-ID vergeben, die für die nächste Listenanfrage verwendet werden kann.

Dateiliste

Um die Liste der Dateien in einem Torrent-Job zu erhalten, fragen Sie folgende URI ab: http://[IP]:[PORT]/gui/?action=getfiles&hash=[TORRENT HASH] . Folgendes Ergebnis wird ausgegeben:

{
	"build": BUILD-NUMMER (Ganzzahl),
	"files": [
	HASH (Zeichenfolge),
	[
	[
	DATEINAME (Zeichenfolge),
	DATEIGRÖSSE (Ganzzahl in Bytes),
	HERUNTERGELADEN (Ganzzahl in Bytes),
	PRIORITÄT* (Ganzzahl)	],
	...
	]
	]
}

* PRIORITÄT: Hierbei handelt es sich um einen ganzzahligen Wert, der die Priorität der Datei angibt. Folgende Liste enthält die möglichen PRIORITÄT-Werte und ihre Entsprechungen:

0 = Nicht herunterladen
1 = Niedrige Priorität
2 = Normale Priorität
3 = Hohe Priorität

Dieser Befehl akzeptiert mehrere Hashes. Er gibt mehrere "files"-Schlüssel/Werte-Paare zurück.

Torrent-Jobeigenschaften

Senden Sie folgende Anfrage, um eine Liste der verschiedenen Eigenschaften für einen Torrent-Job abzurufen: http://[IP]:[PORT]/gui/?action=getprops&hash=[TORRENT HASH] . Folgendes Ergebnis wird ausgegeben:

{
	"build": BUILD-NUMMER (Ganzzahl),
	"props": [
	{
	"hash": HASH (Zeichenfolge),
	"trackers": TRACKER* (Zeichenfolge),
	"ulrate": UPLOAD-BEGRENZUNG (Ganzzahl in Bytes pro Sekunde),
	"dlrate": DOWNLOAD-BEGRENZUNG (Ganzzahl in Bytes pro Sekunde),
	"superseed": SUPERSEEDING** (Ganzzahl),
	"dht": DHT VERWENDEN** (Ganzzahl),
	"pex": PEX VERWENDEN** (Ganzzahl),
	"seed_override": WARTESCHLANGE AUSSER KRAFT SETZEN** (Ganzzahl),
	"seed_ratio": SEED-VERHÄLTNIS (Ganzzahl in Promille),
	"seed_time": SEEDING-DAUER*** (Ganzzahl in Sekunden),
	"ulslots": UPLOAD-SLOTS (Ganzzahl)	}
	]
}

* TRACKER: Hierbei handelt es sich um eine Liste der vom Torrent-Job verwendeten Tracker. Jede neue Zeile wird durch einen Zeilenwechsel, gefolgt durch eine neue Zeile (\r\n) repräsentiert.

** SUPERSEEDING/VERWENDEN DHT/PEX VERWENDEN/WARTESCHLANGE AUSSER KRAFT SETZEN: Alle diese Optionen sind ganzzahlige Werte, die ihren jeweiligen Status angeben. Folgende Liste enthält die möglichen Werte und ihre Entsprechungen:

-1 = Nicht zulässig
0 = Deaktiviert
1 = Aktiviert

*** SEED-ZEIT: Hierbei handelt es sich um eine Ganzzahl, die die Mindestdauer (in Sekunden) angibt, die µTorrent nach Abschluss des Download des Torrents mit dem Seeding fortfahren soll. Ein Wert von 0 (null) bedeutet, dass keine minimale Seed-Zeit vorliegt.

Zur Änderung der Eigenschaften für einen Torrent kann folgende URI verwendet werden: http://[IP]:[PORT]/gui/?action=setprops&hash=[TORRENT HASH]&s=[EIGENSCHAFT]&v=[WERT]

Mehrere Eigenschaften können gleichzeitig geändert werden, indem weitere Paare von s= und v= angehängt werden. Mehrere Torrent-Jobs können in einer einzigen Anfrage geändert werden, indem ein weiterer hash=-Wert zusammen mit den zugehörigen Paaren von s= und v= angehängt wird. Alle folgenden Paare von s= und v= ändern die Eigenschaften des letzten angegebenen Hash.

Um z. B. eine Upload-Begrenzung von 10 KBit/s und eine Download-Geschwindigkeit von 20 KBit/s für [TORRENT HASH 1] festzulegen und gleichzeitig 4 Upload-Slots für [TORRENT HASH 2] zu definieren, fragen Sie folgende URI ab: 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

Aktionen

Dieser Abschnitt enthält eine Liste aller anderen möglichen Aktionen, die von der API unterstützt werden.

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

Diese Aktion weist µTorrent an, den angegebenen Torrent-Job bzw. die Torrent-Jobs zu starten. Für mehrere Torrent-Jobs können mehrere Hashes angegeben werden.

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

Diese Aktion weist µTorrent an, den angegebenen Torrent-Job bzw. die Torrent-Jobs zu beenden. Für mehrere Torrent-Jobs können mehrere Hashes angegeben werden.

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

Diese Aktion weist µTorrent an, den angegebenen Torrent-Job bzw. die Torrent-Jobs anzuhalten. Für mehrere Torrent-Jobs können mehrere Hashes angegeben werden.

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

Diese Aktion weist µTorrent an, den Start des bzw. der angegebenen Torrent-Jobs zu erzwingen. Für mehrere Torrent-Jobs können mehrere Hashes angegeben werden.

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

Diese Aktion weist µTorrent an, die Unterbrechung des bzw. der angegebenen Torrent-Jobs aufzuheben. Für mehrere Torrent-Jobs können mehrere Hashes angegeben werden.

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

Diese Aktion weist µTorrent an, den Inhalt des bzw. der angegebenen Torrent-Jobs erneut zu überprüfen. Für mehrere Torrent-Jobs können mehrere Hashes angegeben werden.

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

Diese Aktion entfernt den bzw. die angegebenen Torrent-Job(s) aus der Torrent-Jobliste. Für mehrere Torrent-Jobs können mehrere Hashes angegeben werden. Diese Aktion berücksichtigt die Option "Wenn möglich in Papierkorb verschieben".

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

Diese Aktion entfernt den bzw. die angegebenen Torrent-Job(s) aus der Torrent-Jobliste und entfernt die entsprechenden Torrent-Inhalte (Daten) von der Festplatte. Für mehrere Torrent-Jobs können mehrere Hashes angegeben werden. Diese Aktion berücksichtigt die Option "Wenn möglich in Papierkorb verschieben".

http://[IP]:[PORT]/gui/?action=setprio&hash=[TORRENT HASH]&p=[PRIORITÄT]&f=[DATEI-INDEX]

Diese Aktion legt die Priorität der angegebenen Datei(en) im Torrent-Job fest. Die möglichen Prioritätsstufen sind die von "getfiles" zurückgegebenen Werte. Eine Datei wird mit dem nullbasierten Index der Datei in der von "getfiles" zurückgegebenen Liste angegeben. Bei jedem Aufruf dieser Aktion kann nur eine Prioritätsstufe angegeben werden, die Angabe mehrerer Dateien ist jedoch möglich.

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

Durch diese Aktion wird ein Torrent-Job aus der angegebenen URL hinzugefügt. Bei Servern, die Cookies erfordern, können Cookies durch die Methode ":COOKIE:" gesendet werden (siehe hier). Die Zeichenfolge muss URL-kodiert sein.

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

Diese Aktion unterscheidet sich insofern von anderen Aktionen, als sie Daten mit "HTTP POST" anstelle von "HTTP GET" an µTorrent übermittelt. Das HTTP-Formular muss den enctype "multipart/form-data" verwenden und über ein Eingabefeld des Typs "file" mit dem Namen "torrent_file" verfügen, in dem der lokale Pfad zu der Datei gespeichert ist, die in µTorrent hochgeladen werden soll.

Beschränkungen

Es ist nicht möglich, einen Pfad zur Speicherung der Daten des Torrents anzugeben. Es ist möglich, das standardmäßige Download-Verzeichnis mit "getsettings" festzulegen, jedoch nicht für jeden einzelnen Torrent. Dieses Problem wird in einer späteren Version behoben.

Es ist nicht möglich, einzelne Dateien in einem Torrent-Job umzubenennen oder zu verschieben.

RSS ist in der API nicht implementiert.

Punkte

Besonderer Dank geht an Ultima für die Dokumentation des größten Teils der API in den Foren, der die meisten Informationen auf dieser Seite entnommen wurden.