API:Página principal

From MediaWiki.org
Jump to: navigation, search
This page is a translated version of the page API:Main page and the translation is 97% complete.
Outdated translations are marked like this.
Other languages:
العربية • ‎български • ‎বাংলা • ‎Deutsch • ‎English • ‎español • ‎فارسی • ‎français • ‎हिन्दी • ‎Հայերեն • ‎Bahasa Indonesia • ‎italiano • ‎日本語 • ‎ಕನ್ನಡ • ‎한국어 • ‎lietuvių • ‎मैथिली • ‎मराठी • ‎Nederlands • ‎occitan • ‎polski • ‎پښتو • ‎português • ‎português do Brasil • ‎română • ‎русский • ‎سنڌي • ‎українська • ‎Tiếng Việt • ‎粵語 • ‎中文
Tools clipart.png This page is part of the MediaWiki action API documentation.
MediaWiki APIsAPI:Main page



MediaWiki action API

v · d · e
Esta é uma apresentação da API "operacional". Encontra no menu à direita subtópicos com mais detalhes e também outras API.

A API operacional do MediaWiki é um serviço web para acesso conveniente à funcionalidade, dados e metadados de uma wiki usando o protocolo HTTP através de um URL, e está normalmente localizada no ficheiro api.phpManual:api.php. Os clientes solicitam "operações" particulares especificando um parâmetro action, normalmente action=query para obter informação. Esta API era conhecida como a API do MediaWiki, mas entretanto foram disponibilizadas outras API para interagir com o MediaWiki, tais como a RESTBase e o serviço de consulta Wikidados.

Introdução[edit]

Nota Nota: Se o que procura é uma «API interna», uma «API de PHP», consulte a interface para extensões, que permite a programadores de PHP acrescentar funcionalidades a uma instalação MediaWiki.

Nota: Deprecation notices are sent to the low-traffic mediawiki-api-announce mailing list. Subscription is recommended.

A API operacional do MediaWiki pode ser usada para monitorizar uma instalação MediaWiki, ou criar um robô para atividades automáticas de manutenção. A API dá acesso direto de alto nível ao conteúdo das bases de dados do MediaWiki. Aplicações cliente podem autenticar-se numa wiki, obter dados e publicar alterações automaticamente, enviando pedidos HTTP ao serviço web. A gama de clientes suportados inclui robôs, clientes simples em JavaScript baseados em tecnologias web, como popups de navegação ou o LiveRC, aplicações de utilizadores finais como Vandal Fighter, e outros sites da Internet (Tool Labs' utilitários).

Nas instalações novas do MediaWiki, o serviço web é ativado por padrão, mas os administradores podem desativá-lo.

O MediaWiki tem duas outras interfaces externas:

Um exemplo simples[edit]

Este URL diz ao serviço web da API da Wikipédia de língua inglesa para enviar de volta o conteúdo da página principal:

https://en.wikipedia.org/w/api.php?action=query&titles=Main%20Page&prop=revisions&rvprop=content&format=json

Pode usar qualquer linguagem de programação para enviar um pedido GET de HTTP para este URL (ou apenas visitar o link no seu browser) e obterá de volta um documento JSON que inclui o texto em notação wiki da página «Main Page». Alterando o formato para jsonfm obtém-se em resultado um HTML formatado para facilitar a despistagem de erros.

Aqui está o URL jsonfm na forma de link legível.

api.php?action=query&titles=Main%20Page&prop=revisions&rvprop=content&format=jsonfm [try in ApiSandbox]

Vamos analisar o URL para demonstrar como ele funciona.

O ponto de destino[edit]

https://en.wikipedia.org/w/api.php

O «ponto de destino» é este. É como se fosse a página principal da API web do MediaWiki. Este URL é o URL base para a API da Wikipédia inglesa, tal como https://en.wikipedia.org/wiki/ é o URL base para o respetivo site na Internet.

Se está a escrever um programa para usar a Wikipédia inglesa, todos os URL que construir irão começar por este URL base. Se estiver a usar uma instalação diferente do MediaWiki, terá de encontrar o ponto de destino dela e usá-lo. Todas as wikis da Wikimedia têm pontos de destino que seguem este padrão:

https://www.mediawiki.org/w/api.php     # API do MediaWiki
https://en.wikipedia.org/w/api.php      # API da Wikipédia inglesa
https://nl.wikipedia.org/w/api.php      # API da Wikipédia holandesa
https://commons.wikimedia.org/w/api.php # API da Wikimedia Commons


MediaWiki version: ≥ 1.17

A partir da versão r75621, temos um processo RSD de descoberta do ponto de destino: procure o elemento link rel="EditURI" no código-fonte HTML de qualquer página e extraia o URL que conduz ao ficheiro api.php; o link que encontrar conterá informação adicional. Por exemplo, nesta wiki o elemento link rel="EditURI" é:

<link rel="EditURI" type="application/rsd+xml" href="//www.mediawiki.org/w/api.php?action=rsd" />

Não há outra forma segura de localizar o ponto de destino de qualquer wiki. Se tiver sorte, ou o caminho completo até o ficheiro index.php não está ocultado por detrás de regras de reescrita estranhas e neste caso só precisa de usar um link "edit" (ou history) e substituir index.php (etc.) por api.php, ou pode usar o caminho para scripts padrão (como w/api.php).

Passemos aos parâmetros que constam no texto de consulta do URL.

O formato[edit]

format=json Isto diz à API que queremos que os dados sejam enviados de volta no formato JSON. Também pode tentar format=jsonfm para obter uma versão do HTML que facilita o processo de despistagem de erros. A API suporta outros formatos de saída, tais como XML e PHP nativo, mas há planos de remover os formatos menos populares (phab:T95715), por isso pode não ser aconselhável usá-los.

A operação[edit]

action=query

A API web do MediaWiki implementa dezenas de operações e as extensões implementam muitas mais; a ajuda da API, que é gerada dinamicamente, documenta todas as operações disponíveis numa wiki. Neste caso, estamos a usar a operação «query» para obter alguma informação.

A operação «query» é uma das operações mais importantes da API, e em si mesma tem uma documentação vasta.

O que se segue é apenas a explicação de um exemplo simples.

Parâmetros específicos da operação[edit]

titles=Main%20Page

O resto do URL de exemplo contém parâmetros usados pela operação «query». Aqui, estamos a informar à API web que queremos informação sobre a página da wiki com o título «Main Page». (O %20 resulta da codificação por cento do carácter espaço.) Se precisa de consultar várias páginas, coloque-as todas num único pedido, para otimizar recursos na utilização da rede e do servidor: titles=PageA|PageB|PageC. Consulte a documentação de query para mais detalhes.

prop=revisions

Pode solicitar muitos tipos de informação, ou propriedades, acerca de uma página. Este parâmetro diz à API web que queremos informação sobre uma revisão específica da página. Como não especificámos nenhuma informação da revisão, A API dá-nos informação sobre a revisão mais recente — a página principal da Wikipédia inglesa tal como ela está neste momento.

rvprop=content

Finalmente, este parâmetro diz à API que queremos o conteúdo da última revisão da página. Se tivéssemos passado rvprop=content|user, obteríamos o conteúdo mais recente da página e o nome do utilizador que criou a revisão mais recente.

Novamente, isto é só um exemplo. As consultas são explicadas em mais detalhe aqui, e a página de referência da API lista todas as operações possíveis, todos os valores possíveis para rvprop, e por aí adiante.

Um texto de introdução à API de Roan Kattouw na San Francisco Hackathon, janeiro 2012


Começar[edit]

Antes de começar a usar a API web do MediaWiki, leia estes documentos:

Para além disto, aquilo que necessita de ler depende do que pretende fazer. No menu à direita encontra ligações para documentação mais detalhada e específica, e abaixo são apresentadas mais algumas regras gerais.

Identificar o seu cliente[edit]

Quando enviar pedidos de HTTP ao serviço web da API do MediaWiki, certifique-se de que especifica um cabeçalho User-Agent que identifica devidamente o seu cliente. Não use o User-Agent padrão fornecido pela sua biblioteca de cliente, mas crie um cabeçalho personalizado que identifica o seu script ou serviço e fornece uma forma qualquer de contactá-lo (por exemplo, o seu e-mail).

Uma linha User-Agent de exemplo pode ser assim:

MyCoolTool/1.1 (https://example.org/MyCoolTool/; [email protected]) BasedOnSuperLib/1.4

Nas wikis da Wikimedia, se não fornecer um cabeçalho User-Agent, ou se aquele que fornecer estiver vazio ou for genérico, o seu pedido irá falhar com o erro HTTP 403 (cf. m:User-Agent policy). Outras instalações do MediaWiki podem ter normas semelhantes.

Se está a chamar a API a partir de JavaScript via o browser, não pode alterar o cabeçalho User-Agent: o browser usará o seu próprio. Para contornar este problema, use o cabeçalho Api-User-Agent.

// Using XMLHttpRequest
xhr.setRequestHeader( 'Api-User-Agent', 'Example/1.0' );

// Using jQuery
$.ajax( {
    url: remoteUrlWithOrigin,
    data: queryData,
    dataType: 'json',
    type: 'POST',
    headers: { 'Api-User-Agent': 'Example/1.0' },
    success: function(data) {
       // do something with data
    }
} );

// Using mw.Api, specify it when creating the mw.Api object
var api = new mw.Api( {
    ajax: {
        headers: { 'Api-User-Agent': 'Example/1.0' }
    }
} );
api.get( {...} ).done(function(data) {
    // do something with data
});

No PHP, pode identificar o seu user-agent com código como este:

ini_set('user_agent', 'MyCoolTool/1.1 (https://example.org/MyCoolTool/; [email protected]) BasedOnSuperLib/1.4');

Ou, se usar cURL:

curl_setopt($curl, CURLOPT_USERAGENT, 'MyCoolTool/1.1 (https://example.org/MyCoolTool/; [email protected]) BasedOnSuperLib/1.4');

Autenticação[edit]

O seu cliente provavelmente precisará de entrar no MediaWiki, possivelmente através da sua conta de utilizador. Consulte a página de autenticação do manual para mais detalhes.

Etiqueta da API[edit]

Leia também: API:Etiqueta

Se ou seus pedidos obtiverem dados que podem ser armazenados em cache, deve providenciar para que o sejam, de forma a evitar pedir os mesmos dados repetidamente. Pode encontrar mais informações sobre limitações de pedidos, concorrência e etiqueta da API, em API:Etiqueta. Alguns clientes têm a capacidade de armazenar dados em cache eles mesmos, mas para outros (em particular, clientes JavaScript) isto não é possível.

De acordo com a especificação HTTP, os pedidos POST não podem ser armazenados em cache. Portanto, quando está a ler dados da API web, deve usar pedidos GET e não POST.

Note também que um pedido não pode ser servido pela API a partir da cache, a menos que o URL seja exatamente o mesmo. Se pedir api.php?....titles=Foo|Bar|Hello, e armazenar o resultado em cache, pedir api.php?....titles=Hello|Bar|Hello|Foo não passará pela cache — embora o MediaWiki devolva os mesmos dados!

Deve ter o cuidado de normalizar os URL que envia ao serviço web do MediaWiki, de modo que a introdução de dados ligeiramente diferentes pelo utilizador não cause pedidos HTTP desnecessários. Pode normalizar listas de títulos de páginas, removendo duplicados e ordenando os títulos por ordem alfabética. Técnicas semelhantes funcionam para outros tipos de dados.

Links úteis[edit]

A barra de menu do lado direito desta página contém ligações para documentação mais detalhada e específica. Encontra abaixo mais alguns links relacionados com a API na sua totalidade.

Links arquivados[edit]

Retrieved from "https://www.mediawiki.org/w/index.php?title=API:Main_page/pt&oldid=2347654"