API per il Web

Community   Sviluppatori   API per il Web

Sommario

  1. Definizione di WebUI
  2. Definizione di API per il Web
  3. Informazioni generali sull'accesso all'API
  4. Sistema di autenticazione basato su token (importante!)
  5. Modifica impostazioni
  6. Elenco torrent/etichette
  7. Elenco file
  8. Proprietà lavoro torrent
  9. Azioni
  10. Limitazioni
  11. Riconoscimenti

Definizione di WebUI

Si tratta di una funzionalità integrata di µTorrent che consente di controllare e configurare le funzionalità, sia da applicazioni locali che remote, oltre a visualizzare la maggior parte dei dati disponibili. Queste funzionalità vengono utilizzate normalmente in un browser Web con la WebUI fornita. Utilizzando la Web API, tuttavia, ogni applicazione può comunicare direttamente con µTorrent.

Definizione di API per il Web

Si tratta di un'API che consente di accedere alle funzioni della WebUI integrata in µTorrent. Ciò non dipende dalla WebUI standard di µTorrent e non richiede risorse sul lato client oltre all'attivazione dell'opzione in questione.

L'API è stabile e quasi del tutto completa. Le funzionalità mancanti verranno aggiunte col tempo, preservando la compatibilità con le applicazioni esistenti. Servirà pertanto pochissimo lavoro per far funzionare la tua applicazione anche con le future versioni di µTorrent.

L'attuale WebUI, così come alcuni progetti scelti che utilizzano l'API, sono disponibili su Github. Gli aggiornamenti più importanti all'API verranno indicati in entrambi i punti.

Sono disponibili molti altri progetti nella sezione dei forum dedicata a WebUI. Qui è possibile pubblicare anche il tuo progetto!

Informazioni generali sull'accesso all'API

Dopo aver abilitato l'impostazione di µTorrent (Preferenze -> WebUI), l'URL di base per accedervi è http://[IP]:[PORTA]/gui/. I dati restituiti dalle chiamate sono in formato JSON.

L'autenticazione viene eseguita con un'autenticazione HTTP di base. L'account ospite, se abilitato, può usufruire solo di un sottoinsieme delle chiamate. Non è possibile utilizzare i getsettings e le chiamate di azione che modifichino lo stato del torrent.

Se non viene indicata una diversa procedura, ogni chiamata verrà eseguita utilizzando HTTP GET. Come da prassi, i parametri vengono aggiunti all'URL di base. Il primo parametro dovrebbe essere sempre il comando (es. ?list o ?action).

Occorre un hash per inviare la maggior parte dei comandi d'azione. Questo è l'infohash del torrent, ottenuto dall'elenco di tutti i torrent. Ogni hash è una stringa ASCII di 40 caratteri. Alcuni comandi accettano infohash multipli concatenati fra loro, es. http://[IP]:[PORTA]/gui/?action=[ACTION]&hash=[TORRENT HASH 1]&hash=[TORRENT HASH 2]&... per ridurre il numero delle richieste necessarie.

Al momento di impostare i valori booleani con ?action=setsetting o con ?action=setprops, il parametro di valore andrebbe inviato come 0 per "false" o come 1 come "true", non come stringa "true" o "false".

Sistema di autenticazione basato su token (importante!)

In µTorrent è stato implementato un sistema di autenticazione dei token per impedire la contraffazione delle richieste cross-site (CSRF, Cross-Site Request Forgeries). Tutti gli sviluppatori di applicazioni che utilizzano il backend WebUI DEVONO implementare il supporto a questo sistema. In caso contrario, se l'utente abilitasse webui.token_auth, l'applicazione non avrebbe esito positivo.

Nella versione 1.8.3 e precedenti, l'autenticazione dei token era disabilitata per impostazione predefinita (anche se gli utenti potevano abilitarla manualmente). Nelle versioni future quest'opzione SARÀ abilitata per impostazione predefinita: il supporto di tale funzione è adesso un requisito necessario per la compatibilità futura.

Modifica impostazioni

Il parametro di base per le impostazioni è ?action=getsettings. Usando questo parametro senza aggiunte si otterrà un elenco delle impostazioni basato sul seguente formato:

{
	"build": BUILD NUMBER (integer),
	"settings": [
	[
	OPTION NAME (string),
	TYPE* (integer),
	VALUE (string)	],
	...
	]
	}

OPTION NAME è il nome dell'impostazione. Non sono elencate qui poiché alcune impostazioni (in particolare le più avanzate) variano a seconda della versione e sono molto semplici da comprendere. Tuttavia, a questo indirizzo è possibile consultare un elenco pressoché completo per la versione 1.8.2.

* TYPE: TYPE è un numero intero che indica il tipo di dati inserito all'interno della stringa VALUE. Segue l'elenco dei possibili TYPE e dei tipi corrispondenti di VALUE:

  • 0 = Numero intero
  • 1 = Booleano
  • 2 = Stringa

Per modificare le impostazioni, è possibile utilizzare il seguente URL: http://[IP]:[PORTA]/gui/?action=setsetting&s=[SETTING]&v=[VALUE]

Unendo s= e v= nell'URL, è possibile modificare più impostazioni in una singola richiesta. s= definisce l'impostazione e v= e il valore relativo alla s= che lo precede immediatamente.

Per esempio, per impostare il limite globale di upload a 10KiB/s e quello di download a 40KiB/s, bisogna richiedere questo URL: http://[IP]:[PORTA]/gui/?action=setsetting&s=max_ul_rate&v=10&s=max_dl_rate&v=40

Elenco torrent/etichette

Per ottenere l'elenco di tutti i torrent, richiedere http://[IP]:[PORTA]/gui/?list=1 . Ciò restituirà i torrent nel seguente modo:

{
	"build": BUILD NUMBER (integer),
	"label": [
	[
	LABEL (string),
	TORRENTS IN LABEL (integer)	],
	...
	],
	"torrents": [
	[
	HASH (string),
	STATUS* (integer),
	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 seconds),
	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 integer)	}

* STATUS: STATUS è un bitfield rappresentato come numeri interi, ottenibile aggiungendo i diversi valori per gli status corrispondenti:

  • 1 = In download
  • 2 = In controllo
  • 4 = Avviato dopo il controllo
  • 8 = Controllo
  • 16 = Errore
  • 32 = In pausa
  • 64 = In coda
  • 128 = Caricato

Ad esempio, se un processo di torrent ha uno stato di 201 = 128 + 64 + 8 + 1, ciò significa che è stato caricato, messo in coda, controllato ed avviato. È necessario utilizzare un operatore bitwise AND per stabilire se un certo STATUS contenga uno stato particolare.

** CACHE ID: Il CACHE ID è un numero casuale generato da µTorrent per i dati forniti. Richiedendo l'elenco dei torrent mediante http://[IP]:[PORTA]/gui/?list=1&cid=[CACHE ID], verranno restituiti solo gli elementi modificati dopo l'invio dell'elenco corrispondente al CACHE ID. Riducendo la quantità di dati inviati da µTorrent, è possibile diminuire l'utilizzo della larghezza di banda e semplificare l'analisi. In questo caso, le due nuove chiavi del dizionario sostituiscono "torrents". Il JSON restituito avrà il seguente aspetto:

{
	"build": BUILD NUMBER (integer),
	"label": [
	[
	LABEL (string),
	TORRENTS IN LABEL (integer)	],
	...
	],
	"torrentp": [
	[
	HASH (string),
	STATUS (integer),
	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 seconds),
	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 integer)	}

La matrice "torrentp" contiene un elenco dei processi di torrent modificati dal CACHE ID corrispondente ed ha un formato identico alla matrice "torrents". La matrice "torrentm" contiene l'elenco degli hash dei processi di torrent eliminati dal CACHE ID corrispondente. In torrentc verrà aggiunto un nuovo CACHE ID, che potrà essere utilizzato per la prossima richiesta di elenco.

Elenco file

Per ottenere l'elenco dei file di un processo di torrent, richiedere questo URL: http://[IP]:[PORTA]/gui/?action=getfiles&hash=[TORRENT HASH] . Verrà restituito il risultato seguente:

{
	"build": BUILD NUMBER (integer),
	"files": [
	HASH (string),
	[
	[
	FILE NAME (string),
	FILE SIZE (integer in bytes),
	DOWNLOADED (integer in bytes),
	PRIORITY* (integer)	],
	...
	]
	]
}

* PRIORITY: È un numero intero che indica la priorità del file. Segue un elenco dei possibili valori di PRIORITY e di ciò che corrisponde ad ognuno di essi:

  • 0 = Non scaricare
  • 1 = Priorità bassa
  • 2 = Priorità normale
  • 3 = Priorità alta

Questo comando accetta hash multipli. Esso restituirà più coppie chiave/valore per "file".

Proprietà lavoro torrent

Per ottenere un elenco delle proprietà di un processo di torrent, richiedere http://[IP]:[PORTA]/gui/?action=getprops&hash=[TORRENT HASH] . Verrà restituito il risultato seguente:

{
	"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: Questo è un elenco dei tracker utilizzati dal processo di torrent. Ogni "nuova riga" è costituita da un "ritorno a capo" seguito da una "nuova riga" (\r\n).

** INITIAL SEEDING/USE DHT/USE PEX/OVERRIDE QUEUEING: Tali opzioni sono numeri interi che indicano i loro rispettivi stati. Segue un elenco dei possibili valori e di ciò che corrisponde ad ognuno di essi:

  • -1 = Non consentito
  • 0 = Disattivato
  • 1 = Attivato

*** SEEDING TIME: Questo numero intero rappresenta la quantità minima di tempo (in secondi) in cui µTorrent deve proseguire il seeding dopo aver completato il download del torrent. Un valore pari a 0 (zero) non indica alcun tempo minimo di seeding.

Per modificare le proprietà di un torrent è possibile utilizzare il seguente URL: http://[IP]:[PORTA]/gui/?action=setprops&hash=[TORRENT HASH]&s=[PROPERTY]&v=[VALUE]

Aggiungendo altre coppie s= e v= è possibile cambiare più proprietà allo stesso tempo. Aggiungendo un altro valore hash= insieme alle sue coppie s= e v= è possibile modificare più processi di torrent in una singola richiesta. Ogni coppia seguente s= e v= modificherà le proprietà dell'ultimo hash specificato.

Ad esempio, per impostare un limite di velocità di upload pari a 10 KiB/s ed uno di download pari a 20 KiB/s per [TORRENT HASH 1] attivando allo stesso tempo 4 slot di upload per [TORRENT HASH 2], richiedere il seguente URL: http://[IP]:[PORTA]/gui/?action=setprops&hash=[TORRENT HASH 1]&s=ulrate&v=10240&s=dlrate&v=20480&hash=[TORRENT HASH 2]&s=ulslots&v=4

Azioni

Questa sezione contiene un elenco di tutte le azioni eseguibili e supportate dall'API.

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

Questa azione indica ad µTorrent di avviare il processo o i processi di torrent specificati. È possibile indicare più hash per agire su processi multipli di torrent.

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

Questa azione indica ad µTorrent di interrompere il processo o i processi di torrent specificati. È possibile indicare più hash per agire su processi multipli di torrent.

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

Questa azione indica ad µTorrent di mettere in pausa il processo o i processi di torrent specificati. È possibile indicare più hash per agire su processi multipli di torrent.

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

Questa azione indica ad µTorrent di forzare l'avvio del processo o dei processi di torrent specificati. È possibile indicare più hash per agire su processi multipli di torrent.

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

Questa azione indica ad µTorrent di ripristinare dalla pausa il processo o i processi di torrent specificati. È possibile indicare più hash per agire su processi multipli di torrent.

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

Questa azione indica ad µTorrent di ricontrollare il contenuto del torrent per il processo o per i processi di torrent specificati. È possibile indicare più hash per agire su processi multipli di torrent.

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

Questa azione eliminerà i processi di torrent specificati dal relativo elenco. È possibile indicare più hash per agire su processi multipli di torrent. Questa azione rispetta l'opzione "Sposta nel cestino se possibile".

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

Questa azione eliminerà i processi di torrent specificati dal relativo elenco, eliminando anche il corrispondente contenuto (dati) dal disco. È possibile indicare più hash per agire su processi multipli di torrent. Questa azione rispetta l'opzione "Sposta nel cestino se possibile".

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

Questa azione imposta la priorità dei file specificati nel processo di torrent. I livelli possibili di priorità sono i valori restituiti da "getfiles". È possibile specificare un file usando il relativo indice, basato su zeri, che si trova nell'elenco restituito da "getfiles". Anche se è possibile specificare un solo livello di priorità per ogni chiamata a questa azione, è possibile indicare più file.

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

Questa azione aggiunge un processo di torrent partendo dall'URL fornito. Per i server che li richiedono, è possibile inviare i cookie utilizzando il metodo :COOKIE: (vedi qui). La stringa deve avere codifica URL.

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

Questa azione è diversa dalle altre poiché, per inviare dati ad µTorrent, utilizza HTTP POST invece di HTTP GET. Il modulo HTTP deve utilizzare un enctype "multipart/form-data" e disporre di un campo di immissione di tipo "file" e nome "torrent_file" che memorizzi il percorso locale del file da inviare ad µTorrent.

Limitazioni

Non è possibile indicare un percorso per salvare i dati di un torrent. Usando getsettings è possibile impostare la cartella di download predefinita, ma non di ogni singolo torrent. Ciò verrà risolto in una versione successiva.

Non è possibile rinominare o cambiare la posizione dei singoli file di un processo di torrent.

L'RSS non è implementato nell'API.

Riconoscimenti

Si ringrazia Ultima per aver documentato la maggior parte delle API nei forum da cui è stata tratta la maggior parte delle informazioni di questa pagina.

 @uTorrent

 

 µTorrent Blog

Introducing BTC: A Torrenting Shortcut
Visualizza post

 Forum community

uTorrent do not seeding when the computer wake up after hibernation.
Visualizza post

Scarica µTorrent
Versione 3.3 per Windows

Altre piattaforme e lingue

© 2013 BitTorrent, Inc. µTorrent è un marchio registrato di BitTorrent, Inc. Chi siamo Blog Comunicati stampa Privacy EULA Terms IRC