API da Web

Comunidade   Desenvolvedores   API da Web

Índice

  1. O que é o WebUI?
  2. O que é a API da Web?
  3. Notas gerais para acesso à API
  4. Sistema de autenticação de token (importante!)
  5. Modificando configurações
  6. Lista de Torrent/rótulos
  7. Lista de arquivos
  8. Propriedades de função do Torrent
  9. Ações
  10. Limitações
  11. Créditos

O que é o WebUI?

É um recurso interno do µTorrent para um controle quase total e configuração do µTorrent em aplicativos locais e remotos, bem como para exibição da maioria dos dados disponíveis. Normalmente, esse recurso é usado em um navegador da Web com o WebUI que fornecemos, mas qualquer aplicativo pode "falar" diretamente com µTorrent usando a API da Web.

O que é a API da Web?

É uma API para acessar as funções do WebUI interno ao µTorrent. É independente do WebUI padrão fornecido pelo µTorrent e não exige nada no lado do cliente, a não ser que a opção esteja ativada.

A API é estável e completa. Funcionalidade inexistente será adicionada ao longo do tempo e a compatibilidade com aplicativos existentes, em geral, será preservada, portanto, pouco ou nenhum trabalho será necessário para manter o seu aplicativo funcionando em futuras versões do µTorrent.

O atual WebUI, bem como os projetos selecionados que fazem uso da API, estão disponíveis em Github. Atualizações importantes da API serão mencionadas aqui e lá.

Muitos outros projetos estão disponíveis na seção WebUI dos fóruns. Você também pode publicar seu projeto lá.

Notas gerais para acesso à API

Depois de habilitadas as configurações do µTorrent (Preferências -> WebUI), a URI base para acessá-lo é http://[IP]:[PORTA]/gui/. Os dados retornados pelas chamadas estão no formato JSON.

A autenticação é feita com base na autenticação HTTP básica. A conta de convidado, se habilitada, está limitada a um subconjunto das chamadas. As chamadas de ação que modificam o estado da torrent e a obtenção de configurações estão desabilitadas.

A menos que observado em contrário, cada chamada é feita usando HTTP GET. Os parâmetros são adicionados na URI base como normal. O primeiro parâmetro deve ser sempre o comando (por exemplo, ?list ou ?action).

A maioria dos comandos de ação requerem a passagem de hash. Este é o infohash da torrent, obtido na listagem de todas as torrents. Cada hash é uma cadeia de caracteres ASCII com 40 caracteres. Alguns comandos aceitam vários infohashes encadeados juntos; por exemplo, http://[IP]:[PORTA]/gui/?action=[ACTION]&hash=[TORRENT HASH 1]&hash=[TORRENT HASH 2]&... para reduzir o número de solicitações necessárias.

Ao configurar valores booleanos, seja por ?action=setsetting ou por ?action=setprops, o parâmetro de valor deve ser enviado como 0 para "false" ou como 1 para "true", e não como uma cadeia de caracteres indicando "true" ou "false".

Sistema de autenticação de token (importante!)

A sistema de autenticação por token foi implementado no µTorrent para evitar falsificação de solicitação entre sites (CSRF). Todos os aplicativos de criação de desenvolvedores que usem o back-end WebUI DEVEM implementar suporte para esse sistema, caso contrário, o aplicativo falhará se o usuário tiver habilitado webui.token_auth.

Na versão 1.8.3 e anteriores, a autenticação por token foi desabilitada por padrão (embora os usuários possam habilitá-la manualmente), mas essa opção SERÁ habilitada por padrão em futuras versões, portanto, a implementação de suporte agora é um requisito para compatibilidade futura.

Modificando configurações

O parâmetro base para configurações é ?action=getsettings. O uso desse parâmetro por si só fornecerá uma lista de configurações no seguinte formato:

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

OPTION NAME é o nome da configuração. Essas configurações não ficam listadas aqui, pois algumas delas (principalmente as avançadas) variam dependendo da versão e a maioria são autoexplicativas. No entanto, uma lista praticamente completa para o 1.8.2 é fornecida aqui para a sua avaliação.

* TYPE: O TYPE é um valor inteiro que indica qual tipo de dados está incluído na cadeia de caracteres VALUE. A seguir há uma lista dos possíveis TYPEs e tipos de VALUE a que correspondem:

  • 0 = Número inteiro
  • 1 = Booleano
  • 2 = Cadeia de caracteres

Para alterar configurações, a seguinte URI pode ser usada: http://[IP]:[PORTA]/gui/?action=setsetting&s=[SETTING]&v=[VALUE]

Várias configurações podem ser alteradas em uma única solicitação por meio do encadeamento de s= e v= na URI. s= define a configuração e v= é o valor da s= imediatamente precedente.

Por exemplo, para configurar o limite global de utilização de carregamento como 10 KiB/s e o limite global de utilização de download como 40 KiB/s, esta seria a URI a ser solicitada: http://[IP]:[PORTA]/gui/?action=setsetting&s=max_ul_rate&v=10&s=max_dl_rate&v=40

Lista de Torrent/rótulos

Para obter a lista de todas as torrentes, solicite http://[IP]:[PORTA]/gui/?list=1 . Isso retornará as torrentes da seguinte forma:

{
	"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: O STATUS indica bits habilitados em uma área indevida, representados como números inteiros, os quais são obtidos pela adição dos diferentes valores dos status correspondentes:

  • 1 = Iniciado
  • 2 = Verificando
  • 4 = Iniciar após verificação
  • 8 = Verificado
  • 16 = Erro
  • 32 = Pausado
  • 64 = Enfileirado
  • 128 = Carregado

Por exemplo, se um trabalho de torrent tiver um status 201 = 128 + 64 + 8 + 1, isso significará que ele foi carregado, enfileirado, verificado e iniciado. Um operador AND bit a bit deve ser usado para determinar se o STATUS fornecido contém um status em particular.

** CACHE ID: A CACHE ID é um número gerado aleatoriamente pelo µTorrent para os dados fornecidos. Ao solicitar a lista de torrentes usando http://[IP]:[PORTA]/gui/?list=1&cid=[CACHE ID], somente os itens alterados desde o envio da lista correspondente à CACHE ID serão retornados. Isso é usado para minimizar a utilização de largura de banda e para simplificar a análise diminuindo a quantidade de dados enviados pelo µTorrent. Nessa situação, duas novas chaves de dicionário substituem "torrents" e o JSON retornado terá esta aparência:

{
	"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)	}

A matriz "torrentp" contém uma lista dos trabalhos de torrent que foram alterados desde a CACHE ID correspondente e é idêntica em formato à matriz "torrents". A matriz "torrentm" contém uma lista dos hashes de trabalhos de torrent que foram removidos desde a CACHE ID correspondente. Uma nova CACHE ID será fornecida em torrentc e poderá ser usada para a próxima solicitação de lista.

Lista de arquivos

Para obter a lista de arquivos de um trabalho de torrent, solicite esta URI: http://[IP]:[PORTA]/gui/?action=getfiles&hash=[TORRENT HASH] . Isto retornará o seguinte:

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

* PRIORITY: um valor inteiro que indica a prioridade do arquivo. A seguir há uma lista dos possíveis valores de PRIORITY e a respectiva correspondência:

  • 0 = Não baixar
  • 1 = Prioridade Baixa
  • 2 = Prioridade Normal
  • 3 = Prioridade Alta

Esse comando aceita vários hashes. Ele retornará vários pares de chave/valor de "arquivos".

Propriedades de função do Torrent

Para obter uma lista das várias propriedades de um trabalho de torrent, solicite http://[IP]:[PORTA]/gui/?action=getprops&hash=[TORRENT HASH] . Isto retornará o seguinte:

{
	"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: Esta é uma lista dos rastreadores usados pelo trabalho de torrent. Cada nova linha é representada por retorno de carro seguido por uma nova linha (\r\n).

** INITIAL SEEDING/USE DHT/USE PEX/OVERRIDE QUEUEING: Essas opções são todas valores inteiros que indicam os respectivos estados. A seguir há uma lista dos possíveis valores e a respectiva correspondência:

  • -1 = Não permitido
  • 0 = Desabilitado
  • 1 = Habilitado

*** SEEDING TIME: Número inteiro representando a quantidade mínima de tempo (em segundos) em que o µTorrent deve continuar a propagação após o término do download da torrent. Um valor de 0 (zero) significa nenhum tempo mínimo de envio.

Para alterar as propriedades de uma torrent, a seguinte URI pode ser usada: http://[IP]:[PORTA]/gui/?action=setprops&hash=[TORRENT HASH]&s=[PROPERTY]&v=[VALUE]

Várias propriedades podem ser alteradas de uma só vez por meio da anexação de mais pares s= e v=. Vários trabalhos de torrent podem ser modificado em uma única solicitação, anexando outro valor hash= juntamente com seus respectivos pares s= e v=. Qualquer um dos seguintes pares s= e v= modificará as propriedades do último hash especificado.

Por exemplo, para configurar um limite de taxa de carregamento de 10 KiB/s e uma taxa de download de 20 KiB/s para [TORRENT HASH 1], enquanto configura simultaneamente 4 slots de carregamento para [TORRENT HASH 2], solicite a seguinte URI: 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

Ações

Esta seção contém uma lista de todas as outras ações possíveis e aceitas pela API.

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

Esta ação diz ao µTorrent para iniciar o(s) trabalho(s) de torrent especificado(s). Vários hashes podem ser especificados para atuar em vários trabalhos de torrent.

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

Esta ação diz ao µTorrent para interromper o(s) trabalho(s) de torrent especificado(s). Vários hashes podem ser especificados para atuar em vários trabalhos de torrent.

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

Esta ação diz ao µTorrent para pausar o(s) trabalho(s) de torrent especificado(s). Vários hashes podem ser especificados para atuar em vários trabalhos de torrent.

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

Esta ação diz ao µTorrent para forçar a inicialização do(s) trabalho(s) de torrent especificado(s). Vários hashes podem ser especificados para atuar em vários trabalhos de torrent.

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

Esta ação diz ao µTorrent para cancelar a pausa do(s) trabalho(s) de torrent especificado(s). Vários hashes podem ser especificados para atuar em vários trabalhos de torrent.

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

Esta ação diz ao µTorrent para verificar novamente o conteúdo das torrent do(s) trabalho(s) de torrent especificado(s). Vários hashes podem ser especificados para atuar em vários trabalhos de torrent.

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

Esta ação remove os trabalhos de torrent especificados da lista de trabalhos de torrent. Vários hashes podem ser especificados para atuar em vários trabalhos de torrent. Esta ação respeita a opção "Mover para a lixeira se possível".

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

Esta ação remove os trabalhos de torrent especificados da lista de trabalhos de torrent além dos conteúdos correspondentes das torrents (dados) do disco. Vários hashes podem ser especificados para atuar em vários trabalhos de torrent. Esta ação respeita a opção "Mover para a lixeira se possível".

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

Esta ação diz define a prioridade dos arquivos especificados no trabalho de torrent. Os níveis de prioridade possíveis são os valores retornados por "getfiles". Um arquivo é especificado usando o índice baseado em zero do arquivo dentro da lista retornado por "getfiles". Somente um nível de prioridade pode ser especificado em cada chamada para a ação, mas vários arquivos podem ser especificados.

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

Esta ação adiciona um trabalho de torrent à URL fornecida. Para servidores que exigem cookies, o método :COOKIE: pode ser usado para enviar os cookies (veja aqui). A cadeia de caracteres deve ser uma URL codificada.

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

Esta ação é diferente da outra ação que usa HTTP POST em vez de HTTP GET para enviar dados ao µTorrent. A forma HTTP deve usar um enctype de "dados de várias partes/formulário" e tem um campo de entrada do tipo "arquivo" com o nome "torrent_file", que armazena o caminho local para o arquivo a ser carregado no µTorrent.

Limitações

Não é possível especificar um caminho para salvar dados de uma torrent. É possível configurar o diretório padrão de download com getsettings, mas não cada torrent individual. Isso será corrigido em versão posterior.

Não é possível renomear ou realocar arquivos individuais em um trabalho de torrent.

O RSS não está implementado na API.

Créditos

Obrigado por sair do Ultima para documentar a grande maioria das APIs nos fóruns, de onde foi extraída a maioria das informações desta página.

 no uTorrent

 

 µTorrent Blog

Introducing BTC: A Torrenting Shortcut
Ver publicações

 Fóruns da comunidade

Recommendation for forum for basic questions about clients and VPN
Ver publicações

Obtenha o µTorrent
Versão 3.3 para Windows

Outras plataformas e idiomas

© 2013 BitTorrent, Inc. µTorrent é uma marca comercial da BitTorrent, Inc. Sobre nós Blog Imprensa Privacidade EULA Terms IRC