Jump to content

Wikibase/API

From mediawiki.org
This page is a translated version of the page Wikibase/API and the translation is 87% complete.
Versão MediaWiki:
1.9

O que é a API Wikibase

Wikibase fornece um mecanismo para armazenar declarações, como dados estruturados. As declarações sobre os itens estão no servidor do wikidata.org. Veja Wikidata:Glossary para mais informações sobre Wikibase e outros conceitos.

Declaração

A API do Wikibase permite consultar, adicionar, remover e editar informações no Wikidata ou em qualquer outra instância do Wikibase.

Este é fornecido por meio de um conjunto de extensões para os módulos da API do MediaWiki. Portanto, para usar a API Wikibase, você deve ter uma familiaridade básica com a MediaWiki Action API: ações, consultas, etc., bem como com parâmetros genéricos como curtimestamp e requestid.

Como usar

Envie solicitações para a API por meio de HTTP, da mesma forma que com a MediaWiki Action API. Veja API:Tutorial#Como usar para obter informações sobre como usar o MediaWiki Action API.

Formato da solicitação

O endpoint da API é https://wikidata.org/w/api.php.

Na consulta, adicione o parâmetro action, que informa à API qual ação executar. Por exemplo, action=wbgetentities informa à API para obter os dados das entidades da Wikibase. Para submódulos meta e de propriedade, use action=query&meta=yourmodule e action=query&prop=modulename, respectivamente.

Alguns parâmetros estão quase sempre disponíveis. As formas plurais são usadas nos casos em que um parâmetro pode assumir vários valores. Os parâmetros são:

  • id/ids: Identifica uma entidade ou entidades específicas, tipicamente um item. A forma plural é usada em wbgetentities. As listas de ids devem ser separadas pela barra vertical
  • site ∩ title/sites ∩ titles: Identifica um único item ou vários itens. A forma plural é usada em wbgetentities. Apenas um dos sites e titles pode ter vários valores ao mesmo tempo.
  • language/languages: O parâmetro language filtra rótulos e descrições em ações get ou identifica um idioma específico para um conjunto de ações.
  • format: Deve ser sempre definido como json (ou jsonfm para depuração), ou xml (ou xmlfm para depuração). Nenhum outro formulário é suportado.
  • summary: Adiciona um resumo especificado pelo usuário além do gerado pelo sistema.
  • token: Uma string criptografada que o solicitante deve passar para que a solicitação seja atendida.
  • baserevid: Uma id para a última revisão conhecida que deve ser passada para que o servidor possa detectar colisões de edição.

Pesquisa simples

Solicitações GET

Obtenha o item para a página "Berlim" na Wikipédia em inglês.

Explicação de cada parte da URL:

  • http://www.wikidata.org/w/api.php é o endpoint principal.
  • Por exemplo, action=wbgetentities informa à API para obter os dados das entidades da Wikibase.
  • sites=enwiki significa obter os dados da Wikipedia em inglês.
  • titles=Berlin indica o título da página da qual obter dados.
  • props=descriptions indica as propriedades a serem obtidas das entidades, neste caso a propriedade são as descrições das entidades.
  • languages=en filtra os resultados para o idioma inglês.
  • format=json indica a saída JSON (formato de saída recomendado).

Resposta

{
    "entities": {
        "Q64": {
            "type": "item",
            "id": "Q64",
            "descriptions": {
                "en": {
                    "language": "en",
                    "value": "capital and largest city of Germany"
                }
            }
        }
    },
    "success": 1
}

A resposta de uma solicitação geralmente conterá:

  • Uma chave success com uma conversão booleana como um número inteiro se a solicitação for bem-sucedida. Se o número inteiro for zero, quaisquer valores adicionais podem estar errados.
  • Uma chave error com um objeto de duas, opcionalmente três chaves, code, info e *, se a solicitação não for bem-sucedida.
  • Informações sobre a action. A informação é passada no nível superior ou sob item se for um único item, ou items se forem vários. Se forem vários itens, cada um será encontrado em uma chave com seu próprio ID de item.

Objetos vazios são retornados como arrays JSON e não como objetos, enquanto parâmetros vazios removem a entrada real do item.

Documentação da API e módulos Wikibase

A documentação gerada na fonte para a API MediaWiki Action, incluindo os módulos API Wikibase 'wb', está disponível em wikidata.org/w/api.php

Meta submodules

  • wikibase: ⧼Apihelp-query+wikibase-description⧽
  • wbcontentlanguages: Devolve informação sobre os idiomas de conteúdo que a extensão Wikibase aceita em diferentes contextos.

Property submodules

  • pageterms: ⧼Apihelp-query+pageterms-description⧽
  • wbentityusage: ⧼Apihelp-query+wbentityusage-description⧽

API modules

Possíveis erros

Possíveis erros para qualquer módulo pode ser encontrado usando action=paraminfo&modules=modulename. The error format corresponds to that of the MediaWiki Action API. See API:Errors and warnings#Legacy format.

Todas as mensagens de erro dos módulos Wikibase devem ser internacionalizadas (i18n) e localizadas (l10n). O idioma do usuário conectado será o padrão para as mensagens de erro, mas você pode substituí-lo adicionando uselang=languageCode à string de consulta da URL.

Error type Code Info
An internationalized error message that isn't localized. no-such-item <wikibase-api-no-such-item>
A correctly localized error message. no-such-item There are no such item to be found
A localized variant.(Norwegian) no-such-item Det finnes ingen slik item

Additional notes

Muitas wikis da Wikimedia funcionam com a extensão de Cliente da Wikibase. Isto permite que os clientes da API nas mesmas

  • consultem o submódulo meta wikibase para determinar os URLs para o repositório completo da Wikibase consulte a ajuda da respetiva API
  • consultem o submódulo da propriedade pageterms para obter alguma informação da Wikidata sobre páginas da wiki local
  • Os módulos de calendário que podem ser usados com Wikibase são o calendário gregoriano (d:Q1985727) e o calendário juliano (d:Q1985786).
  • A API usa IDs de revisão para detecção de colisão de edição. Se houver uma colisão de edição, o solicitante deve adquirir um ID de revisão mais recente para poder continuar. Isso normalmente envolve solicitar wbgetentities para o item em questão e, em seguida, armazenar (e usar) a revisão da entrada.
  • Qualquer instalação do MediaWiki pode executar o Wikibase. No cluster Wikimedia, a maioria dos wikis não executa o conjunto completo de extensões Wikibase. O Wikimedia Commons tem seu próprio Wikibase personalizado para propriedades dos arquivos armazenado no Commons
  • Não teste o valor de info para um erro específico, em vez disso, use o valor de code, pois ele permanecerá independente da localização.

Veja também