Jump to content

API:Учебное пособие

From mediawiki.org
This page is a translated version of the page API:Tutorial and the translation is 100% complete.
Languages:

В этом учебном пособии вы узнаете о MediaWiki Action API, как его использовать, формате запроса, простом запросе и примерах проектов с использованием Action API.

Просматривать демо-приложения на Toolforge

Обзор API MediaWiki Action

MediaWiki Action API — это веб-сервис с архитектурным стилем RESTful, который позволяет пользователям выполнять определенные вики-действия, такие как создание страниц, аутентификация, анализ, поиск и т. д. API:Главная страница - хорошее начало для понимания API.

Ваша программа отправляет запросы в API для доступа к функциям вики. Например, войти в вики, создать и редактировать страницу, искать по заголовку, искать по тексту контента или проанализировать контент. API Action доступен для разработчиков третьих сторон, разработчикам расширений Wikimedia и администраторов сайтов wiki.

В правой боковой панели этой страницы есть много функций, которые поддерживаются API, сгруппированных по категориям. Перед отправкой запросов на сервер вики, сначала прочитайте страницы обзора, такие как data formats, errors and warnings, и Action API FAQ.

Как использовать API MediaWiki Action

Вы можете запросить данные с клиентской стороны на сервер через HTTP и получить ответ в стандартном формате (обычно JSON). Запрос состоит из конечной точки и набора параметров. Существует два типа запросов, которые могут быть выполнены: GET и POST. Для запроса GET параметр будет содержать строку запроса в URL. Для запроса POST форматируйте параметры в JSON формате.

Формат запроса

Все Wikimedia Wikis имеют конечные точки в этом формате http://example.org/w/api.php. Для работы на главном сайте MediaWiki или английской Википедии используйте соответствующую конечную точку. Например, английская Википедия это https://en.wikipedia.org/w/api.php. Для тестирования новых учетных записей или тестирования редактирования страниц используйте конечную точку тестирования вики https://test.wikipedia.org/w/api.php.

В строке запроса в URL, добавьте параметр action. Он сообщает API, какую операцию выполнять. Наиболее популярным действием является query (URL будет содержать action=query), что позволяет получать данные из вики. После параметра action, добавьте другой параметр, чтобы указать, какой из трех типов модулей запроса вы хотите выполнять:

  • prop - получить свойства страниц  
  • list - получить список страниц , соответствующих определенному критерию
  • meta - получить мета-информацию о вики и пользователе

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

Request format
Request format

Простые запросы

Давайте возьмем пример простых запросов, чтобы понять, как выглядит типичный запрос и ответ GET в контексте Action API.

Давайте выполним поиск заголовка в вики. Мы будем использовать search модуль задокументированный на API:Search .

GET-запрос

Чтобы искать заголовки страниц или содержимое, соответствующее Craig Noone, URL для запроса HTTP GET будет:

api.php?action=query&list=search&srsearch=Craig%20Noone&format=json [попробуйте в ApiSandbox]

Объяснение каждой части URL:

  • http://en.wikipedia.org/w/api.php - главная конечная точка. В этом случае это английская Википедия.
  • action=query означает получение данных из вики.
  • list=search означает получить список страниц, соответствующих критериям.
  • srsearch=Craig%20Noone указывает на заголовок страницы или содержимое, которое нужно искать. %20 указывает на пространственный знак в URL-адресе.
  • format=json указывает на JSON результат, который является рекомендуемым форматом выходного результата.

Ответ

Ответ - это документ в формате JSON с списком названий страниц, которые соответствуют "Крейгу Ноуну": 

{
    "batchcomplete": "",
    "continue": {
        "sroffset": 10,
        "continue": "-||"
    },
    "query": {
        "searchinfo": {
            "totalhits": 210
        },
        "search": [
            {
                "ns": 0,
                "title": "Craig Noone",
                "pageid": 18846922,
                "size": 22548,
                "wordcount": 1771,
                "snippet": "<span class=\"searchmatch\">Craig</span> Stephen <span class=\"searchmatch\">Noone</span> (born 17 November 1987) is an English professional footballer who plays as a winger for Bolton Wanderers. Born in Kirkby, he has also",
                "timestamp": "2018-11-02T22:25:45Z"
            },
            {
                "ns": 0,
                "title": "Noone",
                "pageid": 32906333,
                "size": 553,
                "wordcount": 64,
                "snippet": "<span class=\"searchmatch\">Noone</span> is a surname that may refer to:  <span class=\"searchmatch\">Craig</span> <span class=\"searchmatch\">Noone</span> (born 1987), English football midfielder Jimmie <span class=\"searchmatch\">Noone</span> (1895–1944), American jazz clarinetist Kathleen",
                "timestamp": "2015-08-16T05:16:17Z"
            }
            ...
        ]
    }
}


Примеры проектов с использованием Action API

Некоторые примеры проектов в Викимедиа, которые используют Action API:

  • Wikipedia iOS App, в которой одна из функций - поиск страниц вики рядом с вашим местоположением.
  • Боты, которые работают на вики. Pywikibot - это бот-фреймворк, написанный на языке Python, который взаимодействует с API MediaWiki, используемым многими разработчиками ботов.
  • Использование API при визуализации данных, полученных из вики. Например, это neat visualization показывает редактирование в режиме реального времени, сделанное на Википедии.

Дополнительные примечания

  • Несколько Special:MyLanguage/Sites using MediaWiki сайтов используют MediaWiki. Они могут работать с другой версией MediaWiki и, в свою очередь, API. Некоторые параметры модуля, поддерживаемые в одной версии, могут быть отменены или удалены в других. Вы можете узнать об этом в документации каждого модуля через API модуль помощи.
  • Если вы хотите сделать много звонков в API, и, возможно, запустить очень затратных и активных ботов, поговорите с администраторами вики заранее, чтобы они не блокировали вас. См. список metawiki:Administrators_of_Wikimedia_projects Администраторы проектов Wikimedia. Читайте больше об этой теме на API:Этикет .
  • Все данные, изменяющие действия, такие как запись, редактирование или перемещение страницы, и наблюдение или патрулирование изменений, требуют токенов. Вам нужно будет получить токены через API:Токены для дальнейшего использования.

Ресурсы

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