Web-API

Community   Ontwikkelaars   Web-API

Inhoudsopgave

  1. Wat is de WebUI?
  2. Wat is de web-API?
  3. Algemene opmerkingen voor API-toegang
  4. Token Authentication System (belangrijk!)
  5. Instellingen aanpassen
  6. Lijst met torrents/etiketten
  7. Lijst met bestanden
  8. Eigenschappen voor torrenttaken
  9. Acties
  10. Beperkingen
  11. Dankwoord

Wat is de WebUI?

Het gaat om functionaliteit die in µTorrent is ingebouwd, waarmee µTorrent zowel via lokale als externe applicaties bijna volledig kan worden beheerd en geconfigureerd. Ook kunnen bijna alle beschikbare gegevens worden weergegeven. Normaal gesproken wordt deze functionaliteit in een webbrowser gebruikt met de aangeboden WebUI, maar elke willekeurige applicatie kan via de web-API rechtstreeks communiceren met µTorrent.

Wat is de web-API?

Deze API geeft toegang tot de functies van de WebUI en is ingebouwd in µTorrent. Deze staat los van de onafhankelijke standaard-WebUI die wordt aangeboden door µTorrent, en vereist niets meer dan het inschakelen van de optie op de client.

De API is stabiel en zo goed als volledig. Missende functies zullen te zijner tijd worden toegevoegd en de compatibiliteit met bestaande applicaties zal over het algemeen behouden blijven. De toepassing zal dus gemakkelijk bruikbaar te maken zijn in toekomstige versies van µTorrent.

De huidige WebUI en geselecteerde projecten die gebruikmaken van de API zijn beschikbaar via Github. Net zoals daar, worden ook hier de belangrijke API-updates vermeld.

Vele andere projecten zijn beschikbaar in het gedeelte WebUI-gedeelte van de forums. Daar kun je je project ook plaatsen.

Algemene opmerkingen voor API-toegang

Nadat deze is ingeschakeld bij de µTorrent-instellingen (Instellingen -> WebUI), is de basis-URL voor toegang http://[IP]:[POORT]/gui/. De gegevens die door oproepen worden teruggezonden zijn in JSON-indeling.

Authenticatie gaat via de normale HTTP-authenticatie. Het bezoekersaccount is, indien deze is ingeschakeld, beperkt tot een subset oproepen. Actieoproepen die de torrentstatus wijzigen en de functie Getsettings zijn niet toegestaan.

Tenzij anders aangegeven, wordt iedere oproep gedaan met behulp van HTTP GET. Parameters worden zoals altijd toegevoegd aan de basis-URL. De eerste parameter is altijd het commando (bijv. ?list of ?action).

De meeste acties vereisen een hash om verder te gaan. Dit is de torrent-infohash die wordt verkregen door alle torrents in een lijst te plaatsen. Iedere hash is een ASCII string die bestaat uit 40 tekens. Sommige commando's accepteren meerdere infohashes achter elkaar, bijv. http://[IP]:[POORT]/gui/?action=[ACTION]&hash=[TORRENT-HASH 1]&hash=[TORRENT-HASH 2]&... om het aantal vereiste verzoeken omlaag te brengen.

Wanneer de booliaanse waarden worden ingesteld op ?action=setsetting of ?action=setprops, moet de parameterwaarde worden verzonden als 0 voor "onwaar" of 1 voor "waar" in plaats van een string die "waar" of "onwaar" aangeeft.

Token Authentication System (belangrijk!)

Er is een token authentication system geïmplementeerd in µTorrent om CSRF (Cross-Site Request Forgeries) te voorkomen. Alle ontwikkelaars die applicaties creëren en gebruikmaken van de WebUI, MOETEN ondersteuning voor dit systeem implementeren, omdat de applicatie niet werkt wanneer de gebruiker webui.token_auth heeft ingeschakeld.

In 1.8.3 en eerder is het TAS standaard uitgeschakeld (hoewel gebruikers het handmatig kunnen inschakelen), maar deze optie zal in toekomstige versies standaard worden ingeschakeld. Daarom is het implementeren van ondersteuning op dit moment vereist om toekomstige compatibiliteit te waarborgen.

Instellingen aanpassen

De basisparameter voor instellingen is ?action=getsettings. Door deze parameter automatisch te gebruiken, wordt een lijst van instellingen samengesteld in de volgende indeling:

{
	"build": BUILD NUMBER (integer),
	"settings": [
	[
	OPTIENAAM (string),
	TYPE* (heel getal),
	VALUE (string)	],
	...
	]
	}

OPTIENAAM is de naam van de instelling. Deze worden hier niet vermeld, omdat sommige instellingen (vooral de geavanceerde) per versie verschillen en de meeste bovendien voor zich wijzen. Hier kun je echter een bijna volledige lijst voor 1.8.2 bekijken.

* TYPE: Het TYPE is een hele waarde die aangeeft welk gegevenstype besloten ligt in de string WAARDE. Hieronder volgt een lijst met de mogelijke TYPEs en de corresponderende WAARDEs:

  • 0 = Heel getal
  • 1 = Booliaans
  • 2 = String

Als je de instellingen wilt wijzigen, kun je de volgende URI gebruiken: http://[IP]:[POORT]/gui/?action=setsetting&s=[INSTELLING]&v=[WAARDE]

Met een verzoek kunnen meerdere instellingen worden gewijzigd door s= en v= in de URI achter elkaar te plakken. s= definieert de instelling en v= is de waarde voor de s= die er vlak voor komt.

Als je bijvoorbeeld de algemene uploadcap. op 10KiB/s wilt instellen en de algemene downloadcap. op 40KiB/s, zou je deze URL krijgen: http://[IP]:[POORT]/gui/?action=setsetting&s=max_ul_rate&v=10&s=max_dl_rate&v=40

Lijst met torrents/etiketten

Als je de lijst met alle torrents wilt, moet je het volgende verzoeken: http://[IP]:[POORT]/gui/?list=1 . Hierdoor worden de torrents op deze manier teruggezonden:

{
	"build": BUILD NUMBER (integer),
	"label": [
	[
	LABEL (string),
	TORRENTS IN LABEL (integer)	],
	...
	],
	"torrents": [
	[
	HASH (string),
	STATUS* (heel getal),
	NAME (string),
	SIZE (integer in bytes),
	PERCENT PROGRESS (integer in 'per mils'),
	DOWNLOADED (integer in bytes),
	UPLOADED (integer in bytes),
	RATIO (integer in per mils),
	UPLOAD SPEED (integer in bytes per second),
	DOWNLOAD SPEED (integer in bytes per second),
	ETA (integer in seconden),
	LABEL (string),
	PEERS CONNECTED (integer),
	PEERS IN SWARM (integer),
	SEEDS CONNECTED (integer),
	SEEDS IN SWARM (integer),
	AVAILABILITY (integer in 1/65535ths),
	TORRENT QUEUE ORDER (integer),
	REMAINING (integer in bytes)	],
	...
	],
	"torrentc": CACHE-ID** (string in heel getal)	}

* STATUS: De STATUS is een bitveld dat wordt gepresenteerd in hele getallen, die wordt verkregen door de verschillende waardes voor corresponderende statussen bij elkaar op te tellen:

  • 1 = Gestart
  • 2 = Controleren
  • 4 = Starten na controle
  • 8 = Gecontroleerd
  • 16 = Fout
  • 32 = Gepauzeerd
  • 64 = In de wachtrij
  • 128 = Geladen

Als een torrenttaak bijvoorbeeld de status 201 = 128 + 64 + 8 + 1 heeft, is deze geladen, in een wachtrij geplaatst, gecontroleerd en gestart. Een bitwise EN een operator moeten worden gebruikt om te bepalen of de toegewezen STATUS een bepaalde status bevat.

** CACHE-ID: De CACHE-ID is een getal dat door µTorrent willekeurig wordt gegenereerd voor de geleverde gegevens. Wanneer je de torrentlijst verzoekt met http://[IP]:[POORT]/gui/?list=1&cid=[CACHE-ID], worden alleen de items die zijn gewijzigd sinds de lijst die correspondeert met de CACHE-ID was verzonden, teruggezonden. Dit wordt gebruikt om het bandbreedtegebruik te minimaliseren en parsing te vereenvoudigen door het aantal gegevens dat door µTorrent wordt verzonden, te verminderen. In dit geval wordt "torrents," door twee nieuwe dictionary keys vervangen. De teruggezonden JSON zal er nu als volgt uitzien:

{
	"build": BUILD NUMBER (integer),
	"label": [
	[
	LABEL (string),
	TORRENTS IN LABEL (integer)	],
	...
	],
	"torrentp": [
	[
	HASH (string),
	STATUS (heel getal),
	NAME (string),
	SIZE (integer in bytes),
	PERCENT PROGRESS (integer in 'per mils'),
	DOWNLOADED (integer in bytes),
	UPLOADED (integer in bytes),
	RATIO (integer in per mils),
	UPLOAD SPEED (integer in bytes per second),
	DOWNLOAD SPEED (integer in bytes per second),
	ETA (integer in seconden),
	LABEL (string),
	PEERS CONNECTED (integer),
	PEERS IN SWARM (integer),
	SEEDS CONNECTED (integer),
	SEEDS IN SWARM (integer),
	AVAILABILITY (integer in 1/65535ths),
	TORRENT QUEUE ORDER (integer),
	REMAINING (integer in bytes)        ],
	...
	],
	"torrentm": [
	HASH (string),
	...
	]
	"torrentc": CACHE-ID (string in heel getal)	}

De "torrentp"-array bevat een lijst met torrenttaken die zijn gewijzigd sinds de corresponderende CACHE-ID en is identiek aan de "torrents"-array in de indeling. De "torrentm"-array bevat een lijst met hashes voor torrenttaken die zijn verwijderd sinds de corresponderende CACHE-ID. In torrentc zal een nieuwe CACHE-ID worden verstrekt die kan worden gebruikt voor het volgende lijstverzoek.

Lijst met bestanden

Als je de lijst met bestanden in een torrenttaak wilt, moet je deze URL verzoeken: http://[IP]:[POORT]/gui/?action=getfiles&hash=[TORRENT-HASH] . Hierdoor wordt het volgende teruggezonden:

{
	"build": BUILD NUMBER (integer),
	"files": [
	HASH (string),
	[
	[
	BESTANDSNAAM (string),
	BESTANDSGROOTTE (heel getal in bytes),
	DOWNLOADED (integer in bytes),
	PRIORITEIT* (heel getal)	],
	...
	]
	]
}

* PRIORITEIT: Deze waarde is een heel getal dat de prioriteit van het bestand aangeeft. Hieronder volgt een lijst met de mogelijke PRIORITEITen en de corresponderende waardes:

  • 0 = Niet downloaden
  • 1 = Lage prioriteit
  • 2 = Normale prioriteit
  • 3 = Hoge prioriteit

Dit commando accepteert meerdere hashes. Het zal meerdere "bestanden" sleutel/waarde-paren terugzenden.

Eigenschappen voor torrenttaken

Als je een lijst met verschillende eigenschappen voor een torrenttaak wilt, moet je verzoeken http://[IP]:[POORT]/gui/?action=getprops&hash=[TORRENT-HASH] . Hierdoor wordt het volgende teruggezonden:

{
	"build": BUILD NUMBER (integer),
	"props": [
	{
	"hash": HASH (string),
	"trackers": TRACKERS* (string),
	"ulrate": UPLOAD LIMIT (integer in bytes per second),
	"dlrate": DOWNLOAD LIMIT (integer in bytes per second),
	"superseed": INITIAL SEEDING** (integer),
	"dht": USE DHT** (integer),
	"pex": USE PEX** (integer),
	"seed_override": OVERRIDE QUEUEING** (integer),
	"seed_ratio": SEED RATIO (integer in per mils),
	"seed_time": SEEDING TIME*** (integer in seconds),
	"ulslots": UPLOAD SLOTS (integer)	}
	]
}

* TRACKER: Dit is een lijst met de trackers die worden gebruikt bij de torrenttaak. Iedere newline wordt weergegeven door een carriage return gevolgd door een newline (\r\n).

** INITIAL SEEDING/USE DHT/USE PEX/OVERRIDE QUEUEING: Deze opties zijn alle gehele waardes die de respectievelijke statussen aangeven. Hieronder volgt een lijst met de mogelijke waardes en waarmee deze corresponderen:

  • -1 = Niet toegestaan
  • 0 = Uitgeschakeld
  • 1 = Ingeschakeld

*** SEEDINGTIJD: Dit is een heel getal dat de minimale tijd (in seconden) aangeeft hoe lang µTorrent door moet gaan met uploaden nadat de torrent is gedownload. Een waarde van 0 (nul) betekent dat er geen minimale uploadtijd is.

Als je de eigenschappen van een torrent wilt wijzigen, kun je de volgende URL gebruiken: http://[IP]:[POORT]/gui/?action=setprops&hash=[TORRENT-HASH]&s=[EIGENSCHAP]&v=[WAARDE]

Meerder eigenschappen kunnen tegelijkertijd worden gewijzigd door meerdere s= en v= paren toe te voegen. Met een verzoek kunnen meerdere torrenttaken worden gewijzigd door een extra waarde hash= toe te voegen aan de bijbehorende s= en v= paren. Elk volgend s= en v= paar zal de eigenschappen van de laatst opgegeven hash wijzigen.

Als je bijvoorbeeld de uploadsnelheid wilt instellen op 10 KiB/s en de downloadsnelheid op 20 KiB/s voor [TORRENTHASH 1], terwijl je tegelijkertijd 4 uploadslots instelt voor [TORRENTHASH 2], moet je de volgende URL verzoeken: http://[IP]:[POORT]/gui/?action=setprops&hash=[TORRENT-HASH 1]&s=ulrate&v=10240&s=dlrate&v=20480&hash=[TORRENT-HASH 2]&s=ulslots&v=4

Acties

Dit gedeelte bevat een lijst met alle andere mogelijke acties die door de API worden ondersteund.

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

Hierdoor start µTorrent de specifieke torrenttaak/taken. Er kunnen meerdere hashes worden opgegeven voor meerdere torrenttaken.

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

Hierdoor stopt µTorrent de opgegeven torrenttaak/taken. Er kunnen meerdere hashes worden opgegeven voor meerdere torrenttaken.

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

Hierdoor pauzeert µTorrent de opgegeven torrenttaak/taken. Er kunnen meerdere hashes worden opgegeven voor meerdere torrenttaken.

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

Hierdoor wordt µTorrent gedwongen de opgegeven torrenttaak/taken te starten. Er kunnen meerdere hashes worden opgegeven voor meerdere torrenttaken.

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

Hierdoor laat µTorrent de opgegeven torrenttaak/taken weer doorgaan. Er kunnen meerdere hashes worden opgegeven voor meerdere torrenttaken.

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

Hierdoor controleert µTorrent de torrentinhoud opnieuw voor de opgegeven torrenttaak/taken. Er kunnen meerdere hashes worden opgegeven voor meerdere torrenttaken.

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

Hierdoor wordt/worden de opgegeven torrenttaak/taken verwijderd uit de lijst met torrenttaken. Er kunnen meerdere hashes worden opgegeven voor meerdere torrentacties. Hierdoor wordt de optie "Verplaats naar prullenbak indien mogelijk" beschikbaar.

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

Hierdoor wordt/worden de opgegeven torrenttaak/taken uit de lijst met torrenttaken verwijderd en wordt ook de corresponderende torrentinhoud van de schijf verwijderd. Er kunnen meerdere hashes worden opgegeven voor meerdere torrentacties. Hierdoor wordt de optie "Verplaats naar prullenbak indien mogelijk" beschikbaar.

http://[IP]:[POORT]/gui/?action=setprio&hash=[TORRENT-HASH]&p=[PRIORITEIT]&f=[BESTANDSINDEX]

Hierdoor wordt de prioriteit voor de opgegeven bestanden in de torrentactie ingesteld. De mogelijke prioriteitniveaus zijn de waardes die worden teruggezonden door "getfiles". Een bestand wordt opgegeven op basis van de zero-index van het bestand in de lijst die is teruggezonden door "getfiles". Per oproep voor deze actie mag maar één prioriteitniveau worden opgegeven. Er mogen echter wel meerdere bestanden worden opgegeven.

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

Hierdoor wordt een torrenttaak uit de gegeven URL toegevoegd. Voor servers die cookies vereisen, kunnen cookies worden verzonden met de :COOKIE: methode (zie hier). De string moet URL-gecodeerd zijn.

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

Deze actie verschilt van andere acties in het gebruik van HTTP POST in plaats van HTTP GET voor het verzenden van gegevens naar µTorrent. Het HTTP-formulier moet een enctype van "multipart/form-data" gebruiken en een invoerveld hebben van het type "file" met de naam "torrent_file" waarop het lokale pad naar het bestand dat je gaat uploaden naar µTorrent wordt opgeslagen.

Beperkingen

Het is niet mogelijk om een pad op te geven om de gegevens van een torrent op te slaan. Het is mogelijk om de standaarddownloadmap in te stellen met getsettings, maar niet voor elke individuele torrent. Dit zal in latere versies worden verholpen.

Het is niet mogelijk om individuele bestanden in een torrenttaak te hernoemen of te verplaatsen.

RSS is niet geïmplementeerd in de API.

Dankwoord

Ga naar Ultima voor het vastleggen van de grote meerderheid van de API's op de forums. Daar komt de meeste informatie op deze pagina vandaan.

 @uTorrent

 

 µTorrent Blog

Introducing BTC: A Torrenting Shortcut
Berichten weergeven

 Communityforums

µTorrent 3.3.1 RC
Berichten weergeven

µTorrent downloaden
Versie voor Windows

Andere platforms en talen

© 2013 BitTorrent, Inc. µTorrent is een handelsmerk van BitTorrent, Inc. Over ons Blog Media Privacy EULA Terms IRC