Wikibase/API

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page Wikibase/API and the translation is 95% complete.

Other languages:
Deutsch • ‎English • ‎Tiếng Việt • ‎Türkçe • ‎dansk • ‎español • ‎français • ‎lietuvių • ‎polski • ‎português • ‎română • ‎македонски • ‎русский • ‎العربية • ‎ไทย • ‎ဖၠုံလိက် • ‎中文 • ‎日本語 • ‎한국어
Versión de MediaWiki: 1.9
Por favor, consulte wikidata.org/w/api.php para obtener la documentación actualizada de la API de MediaWiki API, incluidos los módulos de la API wb de Wikibase, generados a partir de la fuente.

Introducción general

La API de Wikibase es proporcionada por un conjunto de extensiones que implementan módulos API de MediaWiki. Así que, para usarlo, deberás estar familiarizado con la API de acciones de MediaWiki: acciones, consultas, etc., y a su vez toda la experiencia que puedas tener con parámetros genéricos tales como curtimestamp y requestid, etc. también es válida para la API de Wikibase.

Los cambios en la API de Wikibase están sujetos a la política de interfaz estable.

Wikibase y Wikidata

Wikibase proporciona un mecanismo general para almacenar declaraciones como datos estructurados. Cualquier instalación de MediaWiki puede ejecutarlo. Datamodel in Wikidata.svg

(Véase Wikidata:Glosario para una explicación de estos términos.) En el clúster de Wikimedia, la mayoría de los wikis no ejecutan el conjunto completo de extensiones de Wikibase. Las declaraciones sobre elementos viven en el servidor wikidata.org . Dado que esto incluye declaraciones sobre los millones de elementos en Wikipedias, ¡es un recurso fantástico para consultar!

(Wikimedia Commons tiene su propia Wikibase para las propiedades de los archivos en Commons.)

Las extensiones implementan el action=query de submódulos

  • pageterms query property submodule
  • wikibase query meta submodule
  • wbcontentlanguages query meta submodule - (docs)

and the API modules

  • wbavailablebadges
  • wbcreateclaim
  • wbcreateredirect
  • wbeditentity
  • wbformatvalue
  • wbgetclaims
  • wbgetentities
  • wblinktitles
  • wbmergeitems
  • wbparsevalue
  • wbremoveclaims
  • wbremovequalifiers
  • wbremovereferences
  • wbsearchentities
  • wbsetaliases
  • wbsetclaim
  • wbsetclaimvalue
  • wbsetdescription
  • wbsetlabel
  • wbsetqualifier
  • wbsetreference
  • wbsetsitelink
  • wbsgetsuggestions

Para generar la documentación de uno solo de estos módulos, anexa /wbmoduleName a Special:ApiHelp; por ejemplo, visita Special:ApiHelp/wbgetentities.

Para generar la documentación de varios módulos en una sola página, pasa los nombres de los módulos, separados por |, como el parámetro submodules en api.php?action=help&submodules...; por ejemplo, esta URL genera la documentación de todos los módulos enumerados anteriormente.

Clientes Wikibase

Muchos wikis de Wikimedia incorporan la extensión Cliente Wikibase. Esto permite a los clientes de la API instalados en ellos

  • consultar el submódulo meta Wikibase para determinar las URL para el repositorio de Wikibase ver la página de ayuda de la API
  • consultar el submódulo de propiedades pageterms para obtener información de Wikidata sobre páginas del wiki local

Post o get

  • Requests that change content should use a token.
  • Requests should use HTTP POST or GET requests according to api module. Modules that change content use POST. Use POST to avoid problem with non-behaving proxies.
  • Clients should be aware of and handle errors from the API.

Parámetros de módulos

Algunos parámetros están casi siempre disponibles. Las formas plurales se utilizan en los casos en que un parámetro puede tomar varios valores.

id | ids 
Identifica una entidad o unas entidades específicas, generalmente un elemento. La forma plural se utiliza en wbgetentities. Las listas de identificadores deberían usar | como separador.
site ∩ title | sites ∩ titles 
Identifica uno o varios elementos. La forma plural se usa en wbgetentities. Solo se permite que o bien sites o bien titles tenga valores múltiples, pero no ambos.
language | languages 
El idioma se usa como mecanismo de filtro para filtrar etiquetas y descripciones en acciones de lectura o para identificar un idioma específico en acciones de escritura.
format 
Debe estar siempre en json (o jsonfm para depuración) o xml (o xmlfm para depuración). No se admiten otros formatos.
summary 
Añade un resumen personalizado además de generado por el sistema.
token 
Una cadena cifrada que el solicitante debe enviar en caso de que se cumplimente la petición.
baserevid 
Un identificador para la última revisión conocida que se debe enviar para que el servidor pueda detectar conflictos de edición.

Normalmente el valor de retorno tiene, o bien una clave success con un booleano convertido a entero, o bien una clave error con un objeto formato por dos o a veces tres claves, code, info y *. La última es información adicional. La información sobre la acción se pasa en el nivel superior o en item si es un solo elemento o en items si son varios. Si son varios elementos, cada uno se puede encontrar en una clave con su propio identificador de elemento. Véanse los párrafos Éxito y Errores.

  • Ten en cuenta que los objetos vacíos se devuelven como arrays json y no como objetos.
  • Ten en cuenta que los parámetros vacíos eliminan la entrada del elemento.

Módulos

wbgetentities

Please see the live docs and try the examples in the API Sandbox.

wbeditentity

live docs

  • id is the numeric identifier for an existing item, if the item does not exist an error is returned.
  • sitetitle is a pair that identifies a single existing item, if the item does not exist an error is returned.
  • data
  • clear is a marker to clear out the complete item and start from scratch.
  • new
Examples

wbsetlabel

Module to set a label for a single Wikibase entity. See live docs.

  • id is the numeric identifier for an existing item, if the item does not exist an error is returned.
  • sitetitle is a pair that identifies a single existing item, if the item does not exist an error is returned.
  • language is the language for the label. The language must be a valid identifier.
  • value is the value of the label

wbsetdescription

Module to set a description for a single Wikibase entity. See live docs.

  • id is the numeric identifier for an existing item, if the item does not exist an error is returned.
  • sitetitle is a pair that identifies a single existing item, if the item does not exist an error is returned.
  • language is the language for the description. The language must be a valid identifier.
  • value is the value of the description.
Set the string "An encyclopedia that everyone can edit" for page with id "Q42" as a description in English language
api.php?action=wbsetdescription&id=Q42&language=en&value=An%20encyclopedia%20that%20everyone%20can%20edit
Set the string "An encyclopedia that everyone can edit" as a description in English language for page with a sitelink to enwiki
Wikipedia: api.php?action=wbsetdescription&site=enwiki&title=Wikipedia&language=en&value=An%20encyclopedia%20that%20everyone%20can%20edit

wbsetaliases

Module to set, add and remove aliases from items. Aliases are alternate names for the items, that can be queried and used for lookup. See live docs.

setAliases( ( id XOR ( site, title ) ) OR baserevid, ( add OR remove ) XOR set, *summary )
  • id is the numeric identifier for an existing item, if the item does not exist an error is returned.
  • sitetitle is a pair that identifies a single existing item, if the item does not exist an error is returned.
  • set contains a list of strings that will be used as the new list of aliases. The values are normalized before they are used.
  • add contains a list of additional strings that will be used as aliases. The values are normalized before they are used.
  • remove contains a list of strings that will be removed from the the list of aliases. The values are normalized before they are used.
  • language
Examples

wbsetsitelink

Module to define new links to pages at external client sites. During processing of requests the module will query the external site to verify the existence of the page and to acquire the canonical form of the prefix and the pagename.

linkSite( ( id XOR ( site, title ) ) OR baserevid, linksite, linktitle, *summary )
  • id is the numeric identifier for an existing item, if the item does not exist an error is returned.
  • sitetitle is a pair that identifies a single existing item, if the item does not exist an error is returned.
  • linksite is the site id for a client site that will be the target of the new link. The site will be queried during the call.
  • linktitle is the title of the page at the client site that will be the target of the new link. The site will be queried during the call.
  • badges is the list of badges linked to the given sitelink.
Examples

wbgetclaims

Please see the live docs and try the examples in the API Sandbox.

wbcreateclaim

  • entity is the id of the entity you are adding the claim to.
  • snaktype (value, novalue, somevalue)
  • property is the id of the snaks property.
  • value of snak when creating a claim with a snak that has a value.
Examples


wbsetclaim

Module for creating or updating an entire Claim.

  • claim a claim in json form
  • index
Example


wbsetclaimvalue

Module for setting the value of a Wikibase claim.

  • claim a GUID identifying the claim. Required.
  • snaktype (value, novalue, somevalue).
  • value of snak when setting a claim with a snak that has a value in JSON format.


Example

wbremoveclaims

Module for removing Wikibase claims.

  • claim a GUID identifying the claim.
Example


wbsetqualifier

Module for creating a qualifier or setting the value of an existing one.

  • claim a GUID identifying the claim. Required.
  • property Id of the snaks property
  • value Object value in JSON format.
  • snaktype
  • snakhash
Examples

wbremovequalifiers

Module for removing a qualifier from a claim.

  • claim a GUID identifying the claim. Required.
  • qualifiers a hash of the qualifier that should be removed.
Examples

wbsetreference

Module for creating a reference or setting the value of an existing one.

  • statement a GUID identifying the statement. Required.
  • snaks
  • snaks-order
  • reference a hash of the reference that should be updated.
  • index
Examples

wbremovereferences

Module for removing one or more references of the same statement.

  • statement a GUID identifying the statement. Required.
  • references a hash of the reference that should be updated.
Example

wbsearchentities

Módulo para buscar entidades.

  • search es la cadena de texto que se busca
  • language es el idioma en el que se hace la búsqueda
  • type es el tipo de entidades que devolver
  • limit es el número máximo de resultados que devolver (por defecto son 7)
  • continue desplazamiento, para proseguir una consulta previa
Ejemplos

wblinktitles

Módulo para asociar dos artículos de dos wikis diferentes con un elemento Wikibase.

  • tositetotitle es el par que identifica el primer enlace de sitio
  • fromsitefromtitle es el par que identifica el segundo enlace de sitio
Ejemplos

wbmergeitems

Module to merge two Wikibase items.

  • fromid is the numeric identifier for the item to merge from
  • toid is the numeric identifier for the item to merge to
  • ignoreconflicts Array of elements of the item to ignore conflicts for, can only contain values of "label" and or "description" and or "sitelink"
Ejemplos

wbparsevalue

Módulo para analizar gramaticalmente los strings usando un backend ValueParser.

  • parser
  • values
  • options
Ejemplos

wbformatvalue

Módulo para formatear DataValues.

  • generate: The desired output format to generate. One of the following values: text/plain, text/x-wiki, text/html. Default: text/x-wiki.
  • datavalue: The data to format. This has to be the JSON serialization of a DataValue object. This parameter is required.
  • datatype: The value's data type. This is distinct from the value's type. One of the following values: commonsMedia, geo-shape, globe-coordinate, monolingualtext, quantity, string, tabular-data, time, url, external-id, wikibase-item, wikibase-property, math.
  • property: This can (and should) be used instead of datatype to indicate the property ID for this value. For instance, in the case of an external-id with a formatter URL, the value will be formatted with the appropriate link.
  • options: This takes a JSON object containing various options to customize the rendering. The lang field can always be supplied, with a Wikimedia language code (for instance to determine how month names will be rendered for dates). The list of options supported by each datatype is not centralized yet but can be guessed from here: https://github.com/search?utf8=%E2%9C%93&q=%22OPT%22+user%3Awmde+user%3ADataValues+extension%3Aphp&type=Code
Ejemplos

wbentityusage

Module as a prop in action=query to add entity usage data to the result.

Ejemplos

wbcheckconstraints

Este módulo forma parte de la extensión WikibaseQualityConstraints.

Módulo para comprobar restricciones para reclamaciones o entidades dadas.

  • id Identificador(es) de entidad correspondientes a las entidades (elementos, propiedades, …) que deseas verificar. Se verificarán todas las declaraciones de las entidades. Se puede combinar con claimid para verificar algunas declaraciones individuales de otras entidades.
  • claimid Identificador(es) de declaración correspondientes a las declaraciones individuales que deseas verificar. Se puede combinar con id, pero las declaraciones enumeradas aquí no tienen por qué pertenecer a los identificadores enumerados allá.
  • constraintid Si están especificadas, se verificarán solo esas restricciones (en caso contrario, se verificarán todas). El identificador de una restricción es el identificador de declaración de la declaración correspondiente de la propiedad en la que se define esa restricción.
  • status Devolver solo resultados de verificación con estos estados. Solo las peticiones que limitan los estados a violation|warning|bad-parameters se benefician del almacenamiento en caché. (Este también es el valor predeterminado.)

El formato de salida de la acción wbcheckconstraints se basa en el formato JSON de Wikibase, pero en cualquier lugar donde el formato JSON de Wikibase pudiera contener un snak, la respuesta wbcheckconstraints contiene en su lugar un objeto con los atributos hash y reports. hash es el hash del snak correspondiente, y reports es una lista de los informes de restricciones individuales de ese snak.

Al igual que en el formato JSON de Wikibase, los componentes qualifiers y references de una declaración pueden estar completamente ausentes si están vacíos, mientras que el componente mainsnak siempre está presente, incluso aunque esté vacío.)

Incluidos en la estructura de la salida hay resultados de informes de restricciones individuales, que son objetos con los siguientes componentes:

status
El estado principal del resultado. Los estados principales son compliance, violation y warning (violación de restricción no obligatoria). Otros estados son exception (la entidad es una excepción para la restricción), todo (restricción no implementada o desconocida), bad-parameters (los parámetros de la definición de la restricción están rotos) y deprecated (la comprobación de la restricción se ignoró por declaración obsoleta). A medida que la API sigue evolucionando, se podrán añadir estados nuevos sin aviso.
property
La propiedad ID de la propiedad del snak siendo comprobada, la cual también es la propiedad en la que se define la restricción.
constraint
Un objeto con los miembros siguientes:
id
El identificador de la restricción, que es el identificador de declaración correspondiente a la declaración de restricción que define la restricción.
type
El tipo de restricción, que es un identificador de elemento.
typeLabel
La etiqueta del elemento con el identificador dado en type, en el idioma del usuario.
link
Un enlace a una página de ayuda para el tipo de restricción.
message-html
Un mensaje inteligible para humanos que explica el resultado (principalmente en caso de una vulneración), en formato HTML.
claim
El identificador de declaración que se está verificando, en caso de que el resultado pertenezca al snak principal de una declaración. Este miembro está ausente en resultados de verificación para calificadores, referencias y cualquier otro snak que no sea el snak principal de declaraciones guardadas.
cached
If this optional member is present and contains a truthy value, the result was cached. El valor puede ser un objeto con un componente maximumAgeInSeconds, que indica lo desactualizado que puede estar el valor, en segundos.
Ejemplos

Valores de los datos

Tiempo

Modelo de calendario

Token

An Edit token is required to make edits. This token can be obtained through query&meta=tokens, or by the deprecated action=tokens . Véase también Manual:Ficha de edición .

Revisión

La API utiliza identificadores de revisión para detectar conflictos de ediciones. Si se conoce el identificador de revisión de una respuesta, carga de página o acción similar anterior en el tiempo, entonces pasa el identificador a la edición. Sin el identificador, no es posible detectar conflictos de ediciones con fiabilidad. En caso de conflicto de ediciones, el solicitante debe obtener un identificador de revisión más reciente para poder continuar. Esto suele conllevar la necesidad de pedir wbgetentities para el elemento en cuestión y luego almacenar (y usar) la revisión de la entrada.

Errores

Se pueden encontrar errores posibles para todos los módulos en /w/api.php?action=paraminfo&modules=modulename, por ejemplo, wbeditentity

Los errores «esperados» tendrán un formato estandarizado:

ejemplo 
api.php?action=blah&format=jsonfm
{
	"servedby": "srv273",
	"error": {
		"code": "unknown_action",
		"info": "Unrecognized value for parameter 'action': blah"
	}
}

El servedby está incluido incondicionalmente en mensajes error, pero puede estar ausente de errores que no sean fatales. En algunos casos, mensajes error pueden estar anexados a un success y denominarse warning(s).

Todos los mensajes de error de los módulos de Wikibase deberían estar internationalizados (i18n) y localizados (l10n), pero ten en cuenta que los mensajes de error del sistema base de la API pueden no estar localizados. El idioma que tenga definido el usuario conectado (generalmente el mismo que en la interfaz web) será el predeterminado para mensajes de error. Sin embargo, puedes especificar otro idioma añadiendo uselang=languageCode a la cadena de la consulta en la URL

No pruebes a utilizar el valor de info para un determinado error, en lugar de ello usa el valor de code porque será independiente de la localización.

Un mensaje de error internacionalizado que no esté localizado como debería estará rodeado por un par de cuñas.

ejemplo 
api.php?action=wbgetentities&titles=ThisPageDoesNotExist&sites=fi&format=jsonfm
{
	"error": {
		"code": "no-such-item",
		"info": "<wikibase-api-no-such-item>"
	}
}

Si el mensaje de error está correctamente localizado, las cuñas desaparecerán y se mostrará la cadena en texto plano. Suponiendo que el usuario esté conectado y use como idioma el inglés, se mostrará más o menos como sigue.

{
	"error": {
		"code": "no-such-item",
		"info": "There are no such item to be found"
	}
}

Al cambiar al noruego en las Especial:Preferencias o al añadir uselang=no a la URL, cambiará el texto de la cadena info a una variante localizada, aunque la cadena code permanezca constante.

{
	"error": {
		"code": "no-such-item",
		"info": "Det finnes ingen slik item"
	}
}

Muchos mensajes de error no están correctamente localizados.

Éxito

Se puede eliminar, ya que todas las llamadas normales devolverán algún tipo de datos a menos que haya una condición de error.

Si se consigue un éxito (success), tendrá la siguiente forma cuando format=jsonfm

{
	"success": /* int */
}

La interpretación del valor para success podrá depender de los parámetros de la llamada, pero normalmente es un booleano que está convertido a entero. Su significado es que todos los tests anteriores se han evaluado como verdaderos. Si el número es 0 (cero) cualquier otro valor adicional puede ser incorrecto.

Puede haber valores adicionales en la estructura después de una llamada exitosa.

Véase también