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 100% complete.

Other languages:
Deutsch • ‎English • ‎Tiếng Việt • ‎Türkçe • ‎dansk • ‎español • ‎français • ‎lietuvių • ‎polski • ‎português • ‎română • ‎македонски • ‎русский • ‎العربية • ‎ไทย • ‎ဖၠုံလိက် • ‎中文 • ‎日本語 • ‎한국어
Версия MediaWiki: 1.9
См. wikidata.org/w/api.php для полной, современной документации API MediaWiki, включающей модули 'wb' Wikibase. Документация генерируется из исходного кода.

Общее вступление

API Wikibase предоставляется набором расширений, реализующих модули API MediaWiki. Так что чтобы использовать его, вам следует быть несколько осведомлёнными на тему сетевого API MediaWiki: действия, query-запросы, и т.д., и, наоборот, ваши знания об общих параметрах, таких как curtimestamp, requestid и других, применимых к API Wikibase.

Изменения API Wikibase производятся согласно политике стабильности интерфейса.

Wikibase и Викиданные

Wikibase предоставляет общий механизм хранения утверждений в виде структурированных данных. Любая вики на MediaWiki может запустить его. Datamodel in Wikidata.svg

(См. wikidata:Glossary для объяснения этих терминов.) На кластере Викимедиа, большинство вики не выполняют весь набор расширений Wikibase. Утверждения о пунктах находятся на сервере wikidata.org . Так как это включает утверждения о миллионах объектов из Википедий, по этому ресурсу неплохо бывает выполнить поиск!

(Склад Викимедиа обладает собственным Wikibase для свойств файлов на Складе.)

Расширения реализуют подмодули action=query

  • 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

Чтобы сгенерировать документацию API только для одного из этих модулей, после Special:ApiHelp следует добавить /wbmoduleName, например, перейдите по странице Special:ApiHelp/wbgetentities.

Чтобы сгенерировать документацию API по нескольким модулям на одной странице, передайте разделённые символом | названия модулей в параметре submodules в запросе api.php?action=help&submodules...; например, этот URL генерирует документацию по всем вышеперечисленным модулям.

Клиенты Wikibase

Многие вики Викимедиа (но, $1 по состоянию на февраль 2015$2, не $mw) работают с установленным расширением Wikibase Client. Это расширение позволяет клиентам API:

  • делать запросы к метаинформационному подмодулю, Wikibase, чтобы определять URL полного хранилища данных Wikibase см. справку API по этому подмодулю
  • делать запросы к подмодулю определения свойств, pageterms, чтобы получать информацию с Викиданных о страницах на текущей вики

POST и GET

  • Запросы, изменяющие содержимое, должны использовать токен.
  • Запросам следует использовать HTTP POST или GET в зависимости от модуля API. Модули, изменяющие содержимое, используют метод POST. Используйте POST, чтобы избегать проблем при подключении через плохо работающие прокси.
  • Клиенты должны знать об ошибках при работе с API и обрабатывать полученные сообщения о них.

Параметры модулей

Некоторые параметры доступны практически всегда. Формы множественного числа используются в случаях, когда параметр может принимать список из нескольких значений.

id | ids 
Идентифицирует объект entity или объекты entities, самый типичный объект item. Форма множественного числа доступна в wbgetentities. Списки идентификаторов следует разделять символом |.
site ∩ title | sites ∩ titles 
Определяет один объект или несколько объектов. Множественное число используется в wbgetentities. Одновременно только один из параметров sites и titles может принимать множественное число.
language | languages 
Указанный язык используется для фильтрации меток и описаний в действиях, получающих данные, или для определения конкретного языка в действиях, задающих данные.
format 
Допустимые значения — только json (или jsonfm для отладки) и xml (или xmlfm для отладки), другие форматы не поддерживаются.
summary 
Добавляет указанное пользователем описание действия вместо описания, генерируемого системой. Если параметр не указан, модуль сгенерирует своё описание, а если это невозможно, описание будет предоставлено самим объектом.
token 
Зашифрованная строка, которую должен передать делающий запрос, чтобы запрос был выполнен.
baserevid 
Идентификатор последней известной версии, который должен быть передан, чтобы сервер мог обнаруживать конфликты правок.

Обычно у возвращаемого значения или есть ключ success, содержащий приведённое к целому булево значение, или ключ error, содержащий два (необязательно — три) ключа code, info и *. Этот последний ключ ассоциирован с дополнительной информацией. Информация о действии или передаётся на верхнем уровне, или в ключе item (для единичных объектов) или items (для множественных). Если объектов несколько, каждый находится под ключом, равным своему идентификаторы. См. также разделы Успешное выполнение и Ошибки.

  • Обратите внимание, что пустые объекты возвращаются как массивы JSON, а не как объекты JSON.
  • Обратите внимание, что при указании пустых параметров содержимое самого свойства объекта удаляется.

Модули

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

Модуль для поиска запрашиваемой информации.

  • search — искомая текстовая строка
  • language — язык поиска
  • type — тип возвращаемых объектов
  • limit — максимальное количество возвращаемых результатов (по умолчанию 7)
  • continue — смещение, с которого начинать запрос после предыдущего поиска
Примеры

wblinktitles

Модуль, ассоциирующий две статьи на двух разных вики с одним объектом Wikibase.

  • tositetotitle — пара, определяющая ссылку на первую статью
  • fromsitefromtitle — пара, определяющая ссылку на вторую статью
Примеры

wbmergeitems

Модуль, объединяющий две записи в Wikibase.

  • fromid — числовой идентификатор записи, из которой объединяются данные
  • toid — числовой идентификатор записи, в которую объединяются данные
  • ignoreconflicts — массив элементов записи, конфликты для которых игнорируются. Может содержать только значения label и/или description и/или sitelink.
Примеры

wbparsevalue

Модуль, выполняющий синтаксический разбор строк с использованием серверного обработчика ValueParser.

  • parser
  • values
  • options
Примеры

wbformatvalue

Модуль для форматирования значений данных (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
Примеры

wbentityusage

Модуль как свойство (prop) в action=query, чтобы включить данные по использованию объекту в результат.

Примеры

wbcheckconstraints

Этот модуль входит в отдельное расширение WikibaseQualityConstraints.

Модуль, проверяющий данные утверждения или объекты на соответствие заданным условиям.

  • id Идентификатор(ы) объекта/объектов (записей, свойств, …), которые вы хотите проверить. Будет проведена проверка всех утверждений для этих объектов. Возможно сочетание с claimid для проверки каких-либо отдельных утверждений для других объектов.
  • claimid Идентификатор(ы) отдельных утверждений, которые вы хотите проверить. Может сочетаться с параметром id, но перечисленные в этом параметре утверждения могут не принадлежать идентификаторам, перечисленным в id.
  • constraintid Если параметр указан, проверяются только приведённые утверждения (если не указан, проверяются все). Идентификатор ограничения — это идентификатор соответствующего утверждения для свойства, для которого это ограничение определено.

Формат вывода действия wbcheckconstraints основан на формате Wikibase JSON, но везде, где формат Wikibase JSON может содержать snak, ответ запроса к wbcheckconstraints вместо этого содержит объект с членами hash и reports. hash — это хэш соответствующего snak, а reports — список отчётов по отдельным ограничениям для этого snak.

Так же, как и в формате Wikibase JSON, члены утверждения qualifiers и references могут отсутствовать, если пусты, а член mainsnak присутствует всегда, даже если пуст.)

В структуру вывода встроены результаты отчётов об отдельных ограничениях, представленные объектами со следующими членами:

status
Основной статус результата. Основные статусы — compliance, violation и warning (нарушение необязательного ограничения). Другие статусы — exception (сущность является исключением из ограничения), todo (нереализованное или неизвестное ограничение), deprecated (параметры определения ограничения содержат ошибки) и deprecated (проверка ограничена пропущена для утверждения, отмеченного как устаревшее). API ещё находится в активной разработке, и новые статусы могут быть добавлены без преждевременного объявления.
property
Идентификатор свойства, соответствующий свойству проверяемого snak, и это то же свойство, на котором определено ограничение.
constraint
Объект со следующими членами:
id
Идентификатор ограничения, то есть идентификатор утверждения, определяющего ограничение.
type
Тип ограничения, представленный идентификатором записи.
typeLabel
Переведённая на язык пользователя метка записи, идентификатор которой указан в type.
link
Ссылка на страницу справки по типу ограничения.
message-html
Удобное для восприятия сообщение, объясняющее результат (обычно в случае нарушения), в формате HTML.
claim
Идентификатор проверяемого утверждения, если результат принадлежит основному snak утверждения. Этот член отсутствует в результатах проверок спецификаторов, ссылок, и других snak, которые не являются основными snak сохранённых утверждений.
cached
Если этот необязательный член присутствует и содержит сводящееся к булевой истине значение, это означает, что результат был кэширован. Это значение может быть объектом с членом maximumAgeInSeconds, которое показывает, насколько (в секундах) могло устареть значение.
Примеры

Значения данных

Время

Модель календаря
  • d:Q1985727 - григорианский календарь
  • d:Q1985786 - юлианский календарь

Токен

Для совершения правок требуется токен редактирования. Этот токен может быть получен через query&meta=tokens, или через устаревшие действие action=tokens. См. также Manual:Edit token. См. также Manual:Edit token .

Версия

API использует идентификаторы версий для обнаружения конфликтов редактирования. Если идентификатор версии известен из предыдущего ответа, загрузки страницы или какого-либо похожего события, передайте версию редактированию. Без идентификатора версии невозможно с высокой точностью обнаруживать конфликты редактирования. Если конфликт редактирования уже обнаружен, запрашивающий должен получить идентификатор более новой версии, чтобы получить возможность продолжить. Для этого обычно запрашивается wbgetentities для соответствующей записи, а из ответа считывается (и используется) идентификатор версии.

Ошибки

Возможные для всех модулей ошибки могут быть найдены по адресу /w/api.php?action=paraminfo&modules=modulename, например wbeditentity

«Ожидаемые» ошибки будут иметь стандартизованную форму:

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

Для сообщений error информация servedby передаётся безусловно, но при некоторых менее критических ошибках может отсутствовать. В некоторых случаях сообщения error могут быть вставлены в конец success под названием warning(s).

Все сообщения об ошибках в модулях Wikibase должны быть интернационализованы (i18n) и локализованы (l10n), но важно отметить, что сообщения об ошибках, исходящих из основы API, могут не быть локализованы. Язык текущего вошедшего в учётную запись пользователя (обычно такой же, как и в веб-интерфейсе) будет использоваться по умолчанию в сообщениях об ошибках. Это поведение можно переопределить, указав uselang=languageCode в URL-строке запроса.

Не проверяйте значение info на соответствие какой-либо конкретной ошибке, вместо этого используйте значение code, так как оно независимо от локализации.

Интернационализованное сообщение об ошибке, которое не локализовано, как оно должно быть, будет заключено в дополнительные угловые скобки.

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

Если сообщение об ошибке правильно локализовано, угловые скобки будут убраны, и информационная строка будет выведена прямым текстам. Если предположить, что пользователь вошёл в учётную запись и использует английский язык, будет выведено что-то наподобие следующего:

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

Переключение на норвежский язык в Special:Preferences или дописывание в URL uselang=no изменит текст строки «info» на локализованный вариант, в то время как строка «code» останется неизменной.

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

Большое количество сообщений об ошибках не локализованы должным образом.

Успех

Может быть удалён, так как все обычные вызовы вернут какого-либо рода данные, если не возникло ошибочное состояние.

Если достигнут «успех», у него будет следующая форма, когда format=jsonfm

{
	"success": /* int */
}

Интерпретация значения «успеха» может зависеть от непосредственных параметров вызова, но обычно это булево значение, приведённое к целочисленному типу. Его смысл — то, что все предыдущие проверки имели результат true. Если число равно нулю, какие-либо дополнительные значения могут быть неправильными.

В структуре после успешного вызова могут быть дополнительные значения.

См. также