API:Заглавная страница

From MediaWiki.org
Jump to: navigation, search
This page is a translated version of the page API:Main page and the translation is 96% 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 Эта страница является частью документации по MediaWiki action API.
MediaWiki APIAPI:Main page



API действий MediaWiki

v · d · e
Это обзор действий, выполняемых с помощью API. Разделы с более подробной информацией и другие API ищите в меню справа.

API действий MediaWiki (MediaWiki action API) — это веб-служба, предоставляющая удобный доступ к функциям, данным и метаданным вики по HTTP, с помощью URL-адресов вида api.phpManual:api.php. Клиенты запрашивают различные «действия», указывая параметр action, чаще всего action=query, чтобы получить информацию. Он был известен как единственный API движка MediaWiki, но теперь существуют другие сетевые API, соединяющиеся с MediaWiki, такие как RESTBase и служба запросов к Викиданным.

Введение[edit]

Замечание Замечание: Если вы ищете «внутренний API» или «PHP API», смотрите интерфейс для расширений, позволяющий PHP разработчикам добавлять в MediaWiki новый функционал.

Замечание: Deprecation notices are sent to the low-traffic mediawiki-api-announce mailing list. Subscription is recommended.

Веб-API MediaWiki можно использовать для мониторинга проекта на базе MediaWiki, или для создания бота в целях его обслуживания. Он обеспечивает прямой высокоуровневый доступ к данным, содержащимся в базах данных MediaWiki. Клиентские программы могут автоматически заходить в свой аккаунт на вики, получать данные и вносить изменения, совершая HTTP-запросы к веб-службе. Поддерживаемые клиенты включают в себя ботов, тонкие веб-клиенты на JavaScript, такие как Навигационные окошки и LiveRC, пользовательские приложения, такие как Vandal Fighter и другие веб-сайты (инструменты Tool Labs').

В новых установках MediaWiki веб-служба разрешена по-умолчанию, но администратор может её заблокировать.

MediaWiki имеет ещё два внешних интерфейса:

  • Страница Special:Export, которая предоставляет массовый экспорт содержимого вики в формате XML. Смотрите Справка:ЭкспортHelp:Export для получения дополнительной информации.
  • Стандартный веб-интерфейс (которым вы с большой долей вероятности пользуетесь сейчас, читая эту страницу). Чтобы узнать о том, как пользоваться веб-интерфейсом, прочтите Manual:Параметры index.phpManual:Parameters to index.php.

Простой пример[edit]

Этот URL указывает веб-службе API англоязычной Википедии, чтобы та отправила вам содержимое главной страницы:

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

Используйте любой язык программирования для отправления GET-запроса HTML по этому URL (либо просто перейдите по этой ссылке в своём браузере), и вы получите JSON-документ, содержащий вики-разметку для страницы с названием «Main Page». Замена формата на jsonfm вернёт удобный для отладки результат, «структурированный» с помощью HTML.

Вот URL с указанием формата jsonfm, в качестве более легко читаемой ссылки, по которой можно перейти в браузере.

api.php?action=query&titles=Main%20Page&prop=revisions&rvprop=content&format=jsonfm [попробуйте в ApiSandbox]

Давайте разберём этот URL по частям, чтобы понять, как это работает.

Конечная точка[edit]

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

Это — «конечная точка» (endpoint). Это место — что-то вроде домашней страницы веб-службы API для MediaWiki. Этот URL — базовый URL для API английской Википедии, также как https://en.wikipedia.org/wiki/ — базовый URL для её веб-сайта.

Если вы пишете программу для работы с английской Википедией, любой URL, который вы строите, будет начинаться с этого базового URL. Если вы работаете с другии проектом MediaWiki, вам требуется найти его конечную точку и использовать именно её. Для всех вики-сайтов Викимедиа имеются конечные точки, устроенные по следующему шаблону:

https://www.mediawiki.org/w/api.php     # MediaWiki API
https://en.wikipedia.org/w/api.php      # API английской Википедии
https://nl.wikipedia.org/w/api.php      # API голландской Википедии
https://commons.wikimedia.org/w/api.php # API Викисклада


Версия MediaWiki: ≥ 1.17

Начиная с r75621, мы поддерживаем RSD-нахождение конечной точки: ищите link rel="EditURI" в исходном коде HTML любой страницы и получите URL api.php; сама же ссылка содержит дополнительную информацию. Например, на данной вики она такова:

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

Не существует иного безопасного пути нахождения конечной точки на какой-либо вики. Если вам повезёт, либо полный путь к index.php не будет скрыт под странными правилами переписывания так, что вам останется только взять ссылку редактирования (или истории) и заменить index.php (и т. д.) на api.php, либо вы сможете использовать путь скрипта по умолчанию (вроде w/api.php).

Теперь давайте перейдём к параметрам запроса в URL.

Формат[edit]

format=json Этот параметр сообщает веб-службе API Викимедиа, что мы ожидаем данные в формате JSON. Возможно, вы захотите использовать format=jsonfm, чтобы получить удобную для отладки HTML-версию результата. API поддерживает и другие форматы вывода, такие как XML и родной PHP, однако менее популярные форматы планируется убрать (phab:T95715), так что вы можете не захотеть использовать их.

Действие[edit]

action=query

Веб-служба API MediaWiki реализует десятки действий, а её расширения — ещё больше; динамически генерируемая справка API описывает все доступные операции с вики-сайтом. В нашем случае мы использовали действие «query» для получения некоторой информации.

Действие «query» является одним из самых нужных в API, и оно имеет Special:MyLanguage/API:Query.

То, что последует, будет просто описанием простого примера.

Параметры действий[edit]

titles=Main%20Page

Оставшаяся часть нашего URL содержит параметры для действия «query». Здесь мы сообщаем веб-службе API о том, что хотим информацию о вики-странице с названием «Main Page». (Загадочное %20 — это URL-кодировка символа пробела). Если вам нужно запросить множество страниц, укажите их всех в одном запросе для оптимизации ресурсов сети и сервера: titles=PageA|PageB|PageC. Для подробностей смотрите документацию по query.

prop=revisions

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

rvprop=content

Наконец, этот параметр говорит веб-службе API о том, что мы хотим последнюю версию страницы. Если бы мы передали rvprop=content|user вместо этого, мы бы получили последнюю версию содержимого страницы и имя пользователя, сделавшего самую последнюю версию.

Опять же, это всего лишь один пример. Подробнее запросы расписаны здесь, а в справке API перечислены все возможные действия, а также все возможные значения для rvprop и многое другое.

Введение в API от Roan Kattouw на San Francisco Hackathon January 2012


С чего начать[edit]

Перед тем, как вы начнёте пользоваться веб-службой API MediaWiki, не забудьте прочитать следующие документы:

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

Идентификация клиентского приложения[edit]

Когда вы делаете HTTP-запросы к API сетевых служб движка MediaWiki, обязательно укажите заголовок User-Agent, правильно идентифицирующий ваш клиент. Не используйте значение этого заголовка, предоставляемое вашей клиентской библиотекой по умолчанию. Вместо этого придумайте собственный заголовок, идентифицирующий ваш скрипт или службу и предоставляющий какие-либо способы связаться с вами (например, адрес электронной почты).

Пример строки User-Agent:

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

На вики Викимедиа, если вы не предоставите заголовок User-Agent или предоставите пустой или неконкретный, ваш запрос будет неудачен, и вы получите ошибку HTTP 403 (обратитесь к m:User-Agent policy). Другие сайты, на которых установлен MediaWiki, могут использовать подобную политику.

Если вы вызываете API из JavaScript, базирующегося на браузере, вам не удастся изменить заголовок User-Agent: браузер будет использовать свой. Чтобы обойти это ограничение, используйте заголовок 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
});

В PHP вы можете идентифицировать свою программу-агент, например, кодом, подобным этому:

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

Или если вы используете cURL:

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

Вход[edit]

Вероятно, что вашему клиенту потребуется войти в учётную запись, возможно, под своим собственным аккаунтом. Обратитесь к странице руководства по входу в учётную запись для подробностей.

Этикет использования API[edit]

Также следует прочитать: API:Этикет

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

Согласно спецификации протокола HTTP, POST-запросы не могут быть кэшированы. Таким образом, когда вы читаете данные из API сетевых служб, вам следует использовать метод GET, а не POST.

Также обратите внимание, что запрос не может быть обращён к кэшу, если в URL есть хоть какие-то различия. Если вы делаете запрос по адресу api.php?....titles=Foo|Bar|Hello, последующий запрос к api.php?....titles=Hello|Bar|Hello|Foo не обратится к кэшу, хотя MediaWiki возвращает те же данные!

Вам следует позаботиться о нормализации URL, которые вы посылаете сетевой службе MediaWiki, чтобы незначительно иной ввод пользователя не привёл к потере времени на ненужные HTTP-запросы. Вы можете нормализовать список названий страниц, удалив дубликаты и отсортировав названия в алфавитном порядке. Подобные методики работают для других видов данных.

Полезные ссылки[edit]

Меню в правой части этой страницы ссылается на более подробную, конкретную для той или иной задачи документацию. Вот некоторые ссылки, относящиеся к API в целом:

Архивные ссылки[edit]

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