API:Login/ru

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

Для ботов и других однопользовательских приложений, потребители OAuth только для владельца обычно представляют собой более простой и безопасный способ аутентификации, если целевая вики поддерживает OAuth.

Входить ли в учётную запись
Вашему клиенту потребуется войти в учётную запись MediaWiki, если:


 * ему нужно получить информацию или исполнить действие, разрешённое только участникам с определёнными правами
 * он выполняет большие запросы поиска, которые были бы неэффективны без использования доступным только привилегированным участникам больших (ударение на О) пределов на количество результатов за запрос

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

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

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


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

При наличии отдельной учётной записи, изменения, произведённые вашим приложением, легко отследить, а к учётной записи приложения можно применить особые группы прав (обычно группу ботов). Некоторые вики устанавливают внутреннюю политику автоматического редактирования и/или процедуру обработки запросов присвоения прав бота.

При входе в учётную запись создаются несколько токенов, необходимых для распознавания вошедшего пользователя сервером. В каждом вызове api.php, куки, установленная этим запросом, должна быть передана. Куки действительны примерно в течение месяца, и вам следует проверять необходимость войти в учётную запись на основании обнаружения выхода из неё (то есть, например, не входа в неё один раз за сеанс). Вы можете проверить это в любом запросе, использовав общий параметр.

Как войти в учётную запись
Вход в учётную запись через API требует отправку запроса на вход и построения куки (многие платформы построят куки автоматически). В MediaWiki 1.15.3+ необходимо подтвердить вход, повторно отправив запрос входа вместе в полученным токеном.

Структура запроса на вход
Тело POST может быть пустым. Запрос также вернёт куки сеанса в заголовке HTTP, которую вам придётся указать во втором запросе, если ваша платформа не делает этого автоматически. Параметр sessionid добавлен в MediaWiki 1.17.

Вам может понадобиться добавить параметр запроса, содержащий ваше доменное имя для аутентификации, если вы используете аутентификационный плагин наподобие Extension:LDAP Authentication.

Подтвердить токен
Если ответ к запросу выше был  вместо , вы можете пропустить этот шаг. (Дополнительный шаг был добавлен в MediaWiki 1.15.3.) В MediaWiki 1.15.4, первая фаза входа в ApiLogin.php не работает, так что параметр login/sessionid не возвращается, что делает подтверждение токена невозможным. Примените файл ApiLogin.php из MediaWiki 1.15.5 на вашей вики в качестве быстрого обхода проблемы, при этом планируйте обновление до 1.15.5. ApiLogin.php из MediaWiki 1.16+ несовместим с MediaWiki 1.15.3+.

Обработать куки
Успешный запрос  установит куки, необходимые для подтверждения входа. Многие платформы обработают эти куки автоматически (например, cookiejar в cURL). Если так, используйте это в своих интересах. Если нет, наиболее надёжный метод — прочитать их из заголовков Set-Cookie HTTP-ответа.

Если и это невозможно, возможно построить необходимые куки из различных значений, возвращённых вызовом, но это не рекомендуется, так как необходимые куки могут быть изменены без предупреждения (например, простое изменение  потребует изменения вашего кода ручного создания куки).

Когда включён CentralAuth, как на вики Викимедиа, пример выше не только осуществит вход в единственный домен, но и предоставит вам три куки центральной аутентификации в заголовках ответа Set-Cookie. Чтобы использовать их, продублируйте эти куки (то есть куки, чьи названия начинаются на «centralauth_») и установите поле домена куки на новый домен, в который вы хотите войти. Как только это сделано, каждый GET/POST-запрос к этому новому домену (предполагая, что у пользователя есть глобальная/SUL учётная запись) получит ответ, содержащий заголовки Set-Cookie, куки, специфичные для этого домена.

Ошибки
Ошибки возвращаются в поле result. Возможные значения включают:

Регулирование
В целях безопасности, в этом модуле присутствует функция торможения. По умолчанию разрешено 5 попыток входа за 300 секунд, но это может различаться на разных вики. Когда вы превышаете это ограничение, вход, даже если он в остальном правилен, будет неуспешен с результатом  и количество секунд в поле , которое необходимо подождать.

Примеры

 * Пример кода входа в PHP:
 * Пример входа (требует Snoopy)
 * Пример входа и навигации (использует только file_get_contents)
 * Пример входа (использует cURL): Snoopy не требуется
 * Example login code in JS (using JQuery)
 * Пример кода входа на Python