Web API

Comunidad   Desarrolladores   Web API

Índice de contenidos

  1. ¿Qué es la WebUI?
  2. ¿Qué hay en la Web API?
  3. Notas generales para acceso a la API
  4. Sistema de autenticación de credenciales (muy importante)
  5. Modificación de ajustes de configuración
  6. Lista de torrents/etiquetas
  7. Lista de archivos
  8. Propiedades de trabajo de torrent
  9. Acciones
  10. Limitaciones
  11. Créditos

¿Qué es la WebUI?

Se trata de una función integrada en µTorrent para ofrecer un control casi total y facilitar la configuración de µTorrent desde aplicaciones locales y remotas, así como para mostrar el máximo de datos disponibles. Normalmente, esta función se utiliza en un explorador web con la WebUI que facilitamos, pero cualquier aplicación puede comunicarse directamente con µTorrent utilizando la Web API.

¿Qué hay en la Web API?

Es una API para acceder a las funciones de la WebUI integrada en µTorrent. Es independiente de la WebUI estándar incluida con µTorrent y no necesita nada en el lado del cliente (aparte de tener la opción activada).

La API es estable y muy completa. Con el tiempo se añadirán funciones que faltan y, por lo general, se conservará la compatibilidad con aplicaciones existentes, así que no tendrá que hacer gran cosa para que su aplicación siga funcionando con futuras versiones de µTorrent.

La interfaz de usuario web (WebUI) actual, así como determinados proyectos que usan la API, están disponibles en nuestro Github. En algunos momentos se mencionarán actualizaciones importantes de la API.

Hay muchos otros proyectos disponibles en la sección WebUI de los foros. También puede publicar su proyecto en esa ubicación.

Notas generales para acceso a la API

Una vez activada en la configuración de µTorrent seleccionando Preferencias -> Web UI, el URI base para acceder es http://[IP]:[PUERTO]/gui/. Los datos devueltos por las llamadas en el formato JSON.

La autenticación es de tipo HTTP básica. La cuenta de invitado, si se activa, está limitada a un subconjunto de las llamadas. No se permiten llamadas de acción que modifiquen el estado del torrent y los ajustes de getsettings.

A menos que se indique lo contrario, todas las llamadas se hacen mediante HTTP GET. Los parámetros se añaden al URI base normalmente. El primer parámetro deberá ser siempre el comando (p. ej., ?list o ?action).

La mayoría de los comandos de acción requieren un hash para validarse. Se trata en este caso del infohash del torrent, que se obtiene de las listas de todos los torrents. Cada hash es una cadena ASCII de 40 caracteres. Algunos comandos aceptan varios infohashes encadenados, p. ej., http://[IP]:[PUERTO]/gui/?action=[ACTION]&hash=[TORRENT HASH 1]&hash=[TORRENT HASH 2]&... para reducir el número de peticiones necesarias.

Al establecer valores booleanos, bien con ?action=setsetting o ?action=setprops, el parámetro de valor debe enviarse con 0 para "falso" o 1 para "verdadero" en vez de hacerlo con una cadena que indique el texto "true" ("verdadero" ) o "false" ("falso").

Sistema de autenticación de credenciales (muy importante)

En µTorrent se ha implementado un sistema de autenticación de credenciales para evitar peticiones falsas entre sitios (CSRF). Todos los desarrolladores que se dedican a crear aplicaciones en las que se usa el componente de administración WebUI deben brindar obligatoriamente asistencia para la implementación de dicho sistema, dado que, de lo contrario, la aplicación no se ejecutará correctamente si el usuario tiene activado webui.token_auth.

En las versiones 1.8.3 y anteriores, la autenticación de credenciales se desactiva de manera predeterminada (aunque los usuarios pueden activarla manualmente), pero dicha opción se activará de manera predeterminada en futuras versiones, así que ahora el soporte es un requisito imprescindible para garantizar la compatibilidad en el futuro.

Modificación de ajustes de configuración

El parámetro de base para la configuración es ?action=getsettings. Este parámetro, si se utiliza por separado, le permitirá ver una lista de configuración en el siguiente formato:

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

OPTION NAME es el nombre del ajuste. No se detallan aquí, ya que algunos de los ajustes (sobre todo los avanzados) varían según la versión y el significado de la mayoría resulta evidente. Ahora bien, si lo desea puede consultar una lista detallada y muy completa para 1.8.2 aquí.

* TYPE: El parámetro TYPE es un valor entero que indica qué tipo de datos contiene la cadena VALUE. A continuación puede ver una lista de los posibles valores TYPE y del VALUE al que corresponde cada uno:

  • 0 = Entero
  • 1 = Booleano
  • 2 = Cadena

Para cambiar la configuración, puede utilizar el siguiente URI: http://[IP]:[PUERTO]/gui/?action=setsetting&s=[CONFIGURACIÓN]&v=[VALOR]

Pueden cambiarse varios ajustes de configuración en una sola petición encadenando s= y v= en el URI. s= define el ajuste y v= es el valor del s= que lo precede.

Por ejemplo, para establecer la carga global máxima en 10 KiB/s y la descarga global máxima en 40 KiB/s, se pediría el siguiente URI: http://[IP]:[PUERTO]/gui/?action=setsetting&s=max_ul_rate&v=10&s=max_dl_rate&v=40

Lista de torrents/etiquetas

Para obtener una lista con todos los torrents, pida http://[IP]:[PUERTO]/gui/?list=1 . Se devolverá la lista de torrents de la siguiente manera:

{
	"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 es un campo de bit representado como enteros y que se obtiene sumando los diferentes valores de los estados correspondientes:

  • 1 = Started (Iniciado)
  • 2 = Checking (Comprobando)
  • 4 = Start after check (Iniciar tras comprobación)
  • 8 = Checked (Comprobado)
  • 16 = Error
  • 32 = Paused (En pausa)
  • 64 = Queued (En cola)
  • 128 = Loaded (Cargado)

Por ejemplo, si un trabajo de torrent tiene un estado de 201 = 128 + 64 + 8 + 1, se cargará, se pondrá en cola, se comprobará y se iniciará. Deberá utilizarse un operador Y a nivel de bit para determinar si el STATUS dado contiene un estado particular.

** CACHE ID: CACHE ID es un número generado de forma aleatoria por µTorrent para los datos dados. Al solicitar la lista de torrents utilizando http://[IP]:[PUERTO]/gui/?list=1&cid=[ID DE CACHÉ], solo se devolverán los elementos que hayan cambiado desde que se envió la lista correspondiente a CACHE ID. Esto permite minimizar el uso de ancho de banda y simplificar el análisis al reducir la cantidad de datos enviados por µTorrent. En esta situación, dos nuevas claves de diccionario sustituyen a los "torrents" y el JSON devuelto presentará el siguiente aspecto:

{
	"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 matriz "torrentp" contiene una lista con los trabajos de torrent que han cambiado desde la CACHE ID correspondiente y es idéntica en formato a la matriz de "torrents". La matriz "torrentm" contiene una lista con los hashes de trabajos de torrent que se hayan eliminado desde la CACHE ID correspondiente. En torrentc se facilitará una CACHE ID nueva que puede utilizarse para la siguiente petición de lista.

Lista de archivos

Para obtener la lista de archivos de un trabajo de torrent, solicite este URI: http://[IP]:[PUERTO]/gui/?action=getfiles&hash=[TORRENT HASH] . El resultado será el siguiente:

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

* PRIORITY: Es un valor entero que indica la prioridad del archivo. A continuación ofrecemos una lista donde se indican los posibles valores de PRIORITY y a qué corresponde cada uno:

  • 0 = Don't Download (No descargar)
  • 1 = Low Priority (Prioridad baja)
  • 2 = Normal Priority (Prioridad normal)
  • 3 = High Priority (Prioridad alta)

Este comando acepta varios hashes. Devolverá varios pares clave/valor tipo "files" ("archivos").

Propiedades de trabajo de torrent

Si necesita una lista con las diversas propiedades de un trabajo de torrent, pida http://[IP]:[PUERTO]/gui/?action=getprops&hash=[TORRENT HASH] . El resultado será el siguiente:

{
	"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: Lista de los trackers utilizados por el trabajo de torrent. Cada nueva línea se representa por medio de un retorno de carro y un símbolo de nueva línea (\r\n).

** INITIAL SEEDING/USE DHT/USE PEX/OVERRIDE QUEUEING: Estas opciones son todas valores enteros que indican sus respectivos estados (uso compartido inicial/usar DHT/usar PEX/anular cola). A continuación ofrecemos una lista donde se indican los posibles valores y a qué corresponde cada uno:

  • -1 = Not allowed (No permitido)
  • 0 = Disabled (Desactivado)
  • 1 = Enabled (Activado)

*** SEEDING TIME: valor entero que representa el tiempo mínimo (en segundos) durante el que µTorrent seguirá compartiendo (seeding) después de finalizar la descarga del torrent. Un valor de 0 (cero) indica que no hay un tiempo mínimo de compartición (seeding).

Para cambiar las propiedades de un torrent, se puede utilizar el siguiente URI: http://[IP]:[PUERTO]/gui/?action=setprops&hash=[TORRENT HASH]&s=[PROPIEDAD]&v=[VALOR]

Se pueden cambiar varias propiedades a la vez añadiendo más parejas s= y v=. Pueden modificarse varios trabajos de torrent con una sola petición añadiendo otro valor hash= junto a las parejas s= y v= correspondientes. Cualquiera de las siguientes parejas s= y v= modificarán las propiedades del último hash especificado.

Por ejemplo, para establecer un límite de 10 KiB/s en la velocidad de carga y de 20 KiB/s en la de descarga para [TORRENT HASH 1], a la vez que se establecen 4 slots de carga para [TORRENT HASH 2], solicite el siguiente URI: http://[IP]:[PUERTO]/gui/?action=setprops&hash=[TORRENT HASH 1]&s=ulrate&v=10240&s=dlrate&v=20480&hash=[TORRENT HASH 2]&s=ulslots&v=4

Acciones

Esta sección contiene una lista con todas los demás acciones posibles y compatibles con la API.

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

Esta acción indica a µTorrent que debe iniciar el trabajo o los trabajos de torrent especificados. Pueden especificarse varios hashes para que actúen en varios trabajos de torrent.

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

Esta acción indica a µTorrent que debe detener los trabajos de torrent especificados. Pueden especificarse varios hashes para que actúen en varios trabajos de torrent.

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

Esta acción indica a µTorrent que debe poner en pausa los trabajos de torrent especificados. Pueden especificarse varios hashes para que actúen en varios trabajos de torrent.

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

Esta acción indica a µTorrent que debe forzar el inicio de los trabajos de torrent especificados. Pueden especificarse varios hashes para que actúen en varios trabajos de torrent.

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

Esta acción indica a µTorrent que debe reanudar los trabajos de torrent especificados. Pueden especificarse varios hashes para que actúen en varios trabajos de torrent.

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

Esta acción indica a µTorrent que debe volver a comprobar el contenido de torrent de los trabajos de torrent especificados. Pueden especificarse varios hashes para que actúen en varios trabajos de torrent.

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

Esta acción elimina de la lista el trabajo o trabajos de torrent especificados. Pueden especificarse varios hashes para que actúen en varios trabajos de torrent. Esta acción respecta la opción de mover a papelera de reciclaje si es posible.

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

Esta acción elimina de la lista el trabajo o trabajos de torrent especificados y elimina también del disco los contenidos de torrent (datos) correspondientes. Pueden especificarse varios hashes para que actúen en varios trabajos de torrent. Esta acción respecta la opción de mover a papelera de reciclaje si es posible.

http://[IP]:[PUERTO]/gui/?action=setprio&hash=[TORRENT HASH]&p=[PRIORIDAD]&f=[ÍNDICE DE ARCHIVOS]

Esta acción establece la prioridad para el archivo o archivos especificados en el trabajo de torrent. Los niveles de prioridad disponibles son los valores que devuelve "getfiles". Los archivos se especifican mediante el índice de base cero del archivo (dicho índice puede encontrarse en la lista que devuelve "getfiles"). En cada llamada a esta acción puede especificarse un solo nivel de prioridad, pero varios archivos.

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

Esta acción añade un trabajo de torrent procedente de la URL dada. Si el servidor requiere cookies, estas pueden enviarse con el método :COOKIE: (más información aquí). La cadena debe tener codificación URL.

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

Esta acción es diferente de otras en las que se utiliza HTTP POST en vez de HTTP GET para enviar datos a µTorrent. El formulario HTTP debe utilizar un tipo de codificación "multipart/form-data" y contar con un campo de especificación de datos de tipo "file" con el nombre "torrent_file" que almacene la ruta local al archivo que se desea cargar en µTorrent.

Limitaciones

No es posible especificar una ruta para guardar los datos de un torrent. Es posible establecer la carpeta de descarga predeterminada con getsettings, pero no para cada torrent individual. Esta función se rectificará en una versión futura.

No es posible cambiar de nombre o reubicar archivos individuales en un trabajo de torrent.

No se implementa RSS en la API.

Créditos

Nuestro agradecimiento a Ultima por documentar la gran mayoría de la API en los foros, que es de donde se sacó la mayor parte de la información de esta página.

 @uTorrent

 

 µTorrent Blog

Introducing BTC: A Torrenting Shortcut
Ver mensajes publicados

 Foros de comunidad

Seeding
Ver mensajes publicados

Obtener µTorrent
Versión 3.3 para Windows

Otros idiomas y plataformas

© 2013 BitTorrent, Inc. µTorrent es una marca de BitTorrent, Inc. Acerca de nosotros Blog Prensa Confidencialidad Contrato de licencia de usuario final Terms IRC