Wikibase/API/ru

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

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

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

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

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

Расширения реализуют подмодули and the API modules Чтобы сгенерировать документацию API только для одного из этих модулей, после Special:ApiHelp следует добавить, например, перейдите по странице Special:ApiHelp/wbgetentities.
 * pageterms query property submodule
 * wikibase query meta submodule0
 * wbavailablebadges
 * wbcreateclaim
 * wbcreateredirect
 * wbeditentity
 * wbformatvalue
 * wbgetclaims
 * wbgetentities
 * wblinktitles
 * wbmergeitems
 * wbparsevalue
 * wbremoveclaims
 * wbremovequalifiers
 * wbremovereferences
 * wbsearchentities
 * wbsetaliases
 * wbsetclaim
 * wbsetclaimvalue
 * wbsetdescription
 * wbsetlabel
 * wbsetqualifier
 * wbsetreference
 * wbsetsitelink
 * wbsgetsuggestions

Чтобы сгенерировать документацию API по нескольким модулям на одной странице, передайте разделённые символом  названия модулей в параметре   в запросе  ; например, |query+wikibase|wbavailablebadges|wbcreateclaim|wbcreateredirect|wbeditentity|wbformatvalue|wbgetclaims|wbgetentities|wblinktitles|wbmergeitems|wbparsevalue|wbremoveclaims|wbremovequalifiers|wbremovereferences|wbsearchentities|wbsetaliases|wbsetclaim|wbsetclaimvalue|wbsetdescription|wbsetlabel|wbsetqualifier|wbsetreference|wbsetsitelink|wbsgetsuggestions этот URL генерирует документацию по всем вышеперечисленным модулям.

Клиенты Wikibase
Многие вики Викимедиа (но,, не ) работают с установленным расширением Wikibase Client. Это расширение позволяет клиентам API:
 * делать запросы к метаинформационному подмодулю,, чтобы определять URL полного хранилища данных Wikibase см. справку API по этому подмодулю
 * делать запросы к подмодулю определения свойств,, чтобы получать информацию с Викиданных о страницах на текущей вики

POST и GET

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

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


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

wbgetentities
Module to get the content of several entities, possibly with only parts of the entity included. Entities that are checked for existence, but not found, are reported (bugzilla:45509). During lookup both sites and titles can be a list, that is if the entities are items, but the shorter one is cycled to match the longer one. If one of the lists contain a single entry it will be used for all entries from the other list. If both lists are equally long the sitelinks will be well-formed pairs. getEntities( ( ids XOR ( sites, titles ) ), *props, *languages )
 * ids are numeric identifiers for existing entities, if an entity does not exist they will be marked as missing.
 * sites ∩ titles is pairs that identifies multiple existing entities (only items), if they do not exist they will be marked as missing.
 * props which list to report, possibly filtered by language if they are language specific. Possible values are info, labels, descriptions, sitelinks, claims, datatype, aliases, separated with |. Note that sitelinks are not language specific.
 * sort
 * dir
 * languages are one or more languages to filter the list against. If it is missing all valid languages are reported.
 * languagefallback Apply language fallback for languages defined in the "languages" parameter
 * normalize Try to normalize the page title against the client site (This only works if exactly one site and one page have been given)
 * ungroupedlist Do not group snaks by property id


 * Examples


 * Request
 * Result


 * Request
 * Result

wbeditentity

 * id is the numeric identifier for an existing item, if the item does not exist an error is returned.
 * site ∩ title 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


 * Request
 * Result


 * Request
 * Result


 * Request
 * Result


 * Request
 * Result


 * Request
 * Result


 * Request

or


 * Result


 * Request
 * Result


 * Request
 * Result


 * Request
 * Result


 * Request
 * Result


 * Request

or


 * Result

wbsetlabel
Module to set a label for a single Wikibase entity.


 * id is the numeric identifier for an existing item, if the item does not exist an error is returned.
 * site ∩ title 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

Set the label of the item "Q42" to the English language string "Wikimedia":

Set the label of the item with sitelink "enwiki → Earth" to the English language string "Planet Earth"

wbsetdescription
Module to set a description for a single Wikibase entity.


 * id is the numeric identifier for an existing item, if the item does not exist an error is returned.
 * site ∩ title 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.

English language : page with a sitelink to enwiki:Wikipedia :
 * Set the string "An encyclopedia that everyone can edit" for page with id "Q42" as a description in
 * Set the string "An encyclopedia that everyone can edit" as a description in English language for

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. 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.
 * site ∩ title 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


 * Request
 * Result


 * Request
 * Result


 * Request
 * Result

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.
 * site ∩ title 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


 * Request
 * Result


 * Request
 * Result

wbgetclaims
Module for getting Wikibase claims.


 * entity is Id of the entity from which to obtain claims.
 * property is optional parameter to include the specified property. Currently the only recognized value is references.
 * claim a GUID identifying the claim. Required unless entity is provided.
 * rank is optional filter to return only the claims that have the specified rank. (deprecated, normal, preferred)
 * props which list to report, possibly filtered by language if they are language specific. Note that sitelinks are not language specific.


 * Examples


 * Request
 * Result

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


 * Request
 * Result


 * Request
 * Result


 * Request
 * Result


 * Note: value parameters "globe" and "precision" are optional. Default for "globe" is "http://www.wikidata.org/entity/Q2" (earth).


 * Request
 * Result


 * Request
 * Result

wbsetclaim
Module for creating or updating an entire Claim.


 * claim a claim in json form
 * index


 * Example


 * Request
 * Result

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


 * Request
 * Result

wbremoveclaims
Module for removing Wikibase claims.


 * claim a GUID identifying the claim.


 * Example


 * Request
 * Result

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
 * snaktype
 * snakhash


 * Examples

In this example, p4 is a string property
 * Request
 * Result


 * Request
 * Result


 * Request
 * Result

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


 * Request
 * Result

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


 * Request
 * Result


 * Request
 * Result

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


 * Request
 * Result

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


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


 * Примеры


 * Запрос
 * Result


 * Request
 * Result


 * Request
 * Result

wblinktitles
Module to associate two articles on two different wikis with a Wikibase item.


 * tosite ∩ totitle is pair that identifies first sitelink
 * fromsite ∩ fromtitle is pair that identifies second sitelink


 * Examples


 * Request
 * Result

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"


 * Examples


 * Request
 * Result

wbparsevalue
Module to parse strings using a backend ValueParser.


 * parser
 * values
 * options


 * Examples


 * Request
 * Result

wbformatvalue
Module for formatting DataValues.
 * generate
 * datavalue
 * datatype
 * options


 * Examples


 * Request
 * Result

wbentityusage
Module as a prop in  to add entity usage data to the result.
 * Examples


 * Request
 * Result

wbcheckconstraints
Module to check constraints for given entities or claims.


 * id Entity ID(s) of entities (items, properties, …) that you want to check. All statements of the entities will be checked. Can be combined with claimid to check some individual statements of other entities.
 * claimid Statement ID(s) of individual statements that you want to check. Can be combined with id, but the statements listed here need not belong to the IDs listed there.
 * constraintid If specified, only check these constraints (otherwise: all of them). The ID of a constraint is the statement ID of the corresponding statement on the property where the constraint is defined.

The output format of the wbcheckconstraints action is based on the Wikibase JSON format, but in every place where the Wikibase JSON format can contain a snak, the wbcheckconstraints response instead contains an object with members  and. is the hash of the corresponding snak, and  is a list of the individual constraint reports for that snak.

Embedded in the output structure are individual constraint report results, which are objects with the following members:
 * : The main status of the result. The main statuses are,  , and   (violation of non-mandatory constraint). Other statuses include   (entity is an exception to the constraint),   (unimplemented or unknown constraint),   (parameters of the constraint definition are broken), and   (constraint check skipped on deprecated statement). While the API is still evolving, other statuses may be added without prior notice.
 * : The property ID of the property of the snak being checked, which is also the property on which the constraint is defined.
 * : An object with the following members:
 * : The ID of the constraint, which is the statement ID of the constraint statement that defines the constraint.
 * : The constraint type, which is an item ID.
 * : The label of the item with the ID given in, in the user's language.
 * : A link to a help page for the constraint type.


 * : A human-readable message explaining the result (mainly in case of a violation), in HTML format.
 * : The statement ID being checked, if the result belongs to the main snak of a statement. This member is absent on check results for qualifiers, references, and any other snaks that aren't main snaks of saved statements.
 * : If this optional member is present and contains a truthy value, the result was cached. The value may be an object with a  member, which indicates how outdated the value might be, in seconds.
 * Examples


 * Request
 * Result

Time

 * Calendar model
 * Q1985727 - Gregorian calendar
 * Q1985786 - Julian calendar

Token
An Edit token is required to make edits. This token can be obtained through query&meta=tokens, or by the deprecated action=tokens. See also Manual:Edit token.

Revision
The API uses revision ids for edit collision detection. If the revision id is known from an previous reply, page load or similar, then pass on the revision to the edit. Without the revision id it is not possible to detect edit collisions in a reliable way. If there is an edit collision the requester must acquire a newer revision id to be able to continue. This typically involves requesting wbgetentities for the item in question, and then storing (and using) the revision from the entry.

Ошибки
Possible errors for all modules can be found at, for example wbeditentity

"Expected" errors will will have a standardized form: The servedby is given unconditionally for error messages, but could be missing for some less than fatal errors. In some cases error messages can be appended to a success and be called warning(s).
 * example :

All error messages from the Wikibase modules should be internationalized (i18n) and localized (l10n), but note that error messages from the base API system may not be localized. The user language for the logged in user (usually the same as in the web interface) will be the default for error messages. You can override this by supplying  in the URL query string

Do not test the info value for a particular error, instead use the code value as this will remain independent of localization.

An internationalized error message that isn't localized as it should will have additional angle brackets. With correctly localized error message the angle brackets will go away and the info string will print out in clear text. Assuming the user is logged in and use English language it will print as something like the following. Switching to Norwegian in the Special:Preferences or by appending  it will change the text of the info string to a localized variant, while the code string remains constant. A lot of error messages are not properly localized.
 * example :

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

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

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

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

См. также

 * API:Main page
 * Руководство:Параметр maxlag
 * API:Межсайтовые запросы