API:ЧаВО (FAQ)

From MediaWiki.org
Jump to navigation Jump to search
This page is a translated version of the page API:FAQ and the translation is 98% complete.

Outdated translations are marked like this.
Other languages:
Bahasa Indonesia • ‎Deutsch • ‎English • ‎Ido • ‎Limburgs • ‎Nederlands • ‎Tiếng Việt • ‎Türkçe • ‎bosanski • ‎català • ‎dansk • ‎español • ‎français • ‎hrvatski • ‎italiano • ‎kurdî • ‎occitan • ‎polski • ‎português • ‎português do Brasil • ‎sicilianu • ‎suomi • ‎svenska • ‎čeština • ‎беларуская • ‎беларуская (тарашкевіца)‎ • ‎български • ‎русский • ‎українська • ‎العربية • ‎فارسی • ‎हिन्दी • ‎অসমীয়া • ‎মেইতেই লোন্ • ‎ಕನ್ನಡ • ‎ไทย • ‎中文 • ‎日本語 • ‎粵語 • ‎한국어
Эта страница находится в стадии разработки

Также прочтите API:Заглавная страница . На ней есть ответы на некоторые вопросы, на которые здесь ответа нет, а также ссылки на другие полезные страницы.

Как же я могу ...

получить помощь?

  1. Прочтите этот FAQ
  2. Попробуйте найти ответ на свой вопрос в документации по API здесь или на самодокументируемой странице по API
  3. Если Вы не можете найти ответ на свой вопрос в интернете,
  4. Задайте вопрос в IRC на канале #mediawiki подключиться в сети Freenode.

отправить отчёт об ошибке или запрос на введение возможности?

Если вы нашли ошибку в API или хотите запросить введение новой возможности, вы можете сообщить об этом на Phabricator. Сначала произведите поиск по существующим ошибкам (пожалуйста, не отправляйте дублирующие сообщения об ошибках), выберите продукт MediaWiki-API, когда сообщаете об ошибке в API. Если функциональность, которую вы запрашиваете, или ошибка о которой вы сообщаете, относится к расширению (например, AbuseFilter, FlaggedRevs), добавьте проект того расширения, например, «MediaWiki-extensions-AbuseFilter».

определить, какое действие или подмодуль вызвать?

API движка MediaWiki большой, и расширения увеличивают его ещё сильнее. Некоторые предложения:

  • Если вы пытаетесь получить информацию о странице, возможно, вам понадобится использовать prop= подмодуль action=query. Другие подмодули query возвращают списки и метаинформацию о вики. Просмотреть генерируемую справку по API для всех подмодулей query.
  • Если вы видите, что страница выполняет интересное действие после её изначальной загрузки, она, должно быть, делает запрос к API.
    • Откройте консоль разработчика в вашем браузере и поищите в ней запросы к api.php.
    • Весь код, выполняющийся на вики Викимедиа, открыт, так что вы можете просмотреть исходный код, выполняя запросы к API. Один из способов обнаружить исходный код — вставить в конец URL страницы ?uselang=qqx, чтобы увидеть ключи сообщений около области, в которой представлены результаты API, потом найти эти ключи в локализованных файлах сообщений i18n/en.json ядра и расширений.
  • Вы можете просмотреть всю развернутую генерируемую справку по API на одной странице, добавив в конец recursivesubmodules=1, вот так.

Ссылки на генерируемую справку по API, указанные выше, ведут на английскую Википедию. Вам следует просмотреть генерируемую справку по API на той вики, где вы будете делать запросы к API, поскольку разные вики имеют разные настройки и наборы расширений.

вызвать API?

Посылайте HTTP-запросы к api.php. Например, на английской Википедии URL — https://en.wikipedia.org/w/api.php . На большинстве других вики api.php расположен с похожим URL: просто используйте api.php, вместо index.php в действиях на странице. Начиная с 1.17, MediaWiki поддерживает Really Simple Discovery; исходный код HTML каждой страницы содержит RSD-ссылку, указывающую на RSD-дескриптор, сообщающий, где найти API. Если вы не можете определить URL api.php на вики, принадлежащей третьим лицам (не Викимедиа), обратитесь к её владельцу. На вики может быть отключён API, см. $wgEnableAPI.

Чтобы поэкспериментировать с API

  • используйте Special:ApiSandbox
  • включите консоль разработчика в вашем браузере и просматривайте сетевые запросы к api.php, в то время как вы взаимодействуете с вики

контролировать выходной формат?

Передайте &format=someformat в строке запроса. См. список форматов вывода для дополнительной информации.

проверить, доступен ли модуль API?

Вы можете использовать action=paraminfo для запроса информации о модулях и подмодулях API (например, query+geosearch), которые вы хотите вызвать. Массив paraminfo.modules в ответе должен содержать ключ path для каждого модуля и подмодуля, все отсутствующие данные означают недоступность модулей.

Если модуль API недоступен, при этом вам известно, какое расширение его реализует, вы можете проверить, загружено ли это расширение, отправив запрос на метаинформацию siteinfo с параметром siprop=extensions и посмотрев, содержится ли название расширения в возвращённом списке.

Даже если похоже, что модуль доступен, вы всегда должны обрабатывать ошибки API.

обнаружить ошибки?

См. Ошибки и предупреждения.

Ошибочный ответ от API задаст заголовок HTTP MediaWiki-API-Error и возвратит структуру error. Для примера ответа с ошибкой перейдите на страницу https://en.wikipedia.org/w/api.php?action=blah.

получить содержимое страницы (wikitext)?

Если вы просто хотите чистый викитекст без какой-либо другой информации, лучше всего использовать режим action=raw index.php вместо API: https://en.wikipedia.org/w/index.php?action=raw&title=Main_Page. Обратите внимание, что это выведет необработанный викитекст без какого-либо форматирования. См. также документацию action=raw .

Чтобы получить больше информации о странице и о последней версии, используйте API: https://en.wikipedia.org/w/api.php?action=query&prop=revisions&titles=Main_Page. См. также документацию к модулю prop=revisions .

Вы можете получить до 50 страниц за запрос к API: https://en.wikipedia.org/w/api.php?action=query&prop=revisions&rvprop=content&titles=Main_Page%7CArticles. Это работает также с генераторами.

получить содержимое страницы (HTML)?

Если вам нужен только HTML, лучше использовать режим action=render index.php вместо API: https://en.wikipedia.org/wiki/Main_Page?action=render. См. документацию action=render .

С появлением RESTBase, на вики Викимедиа вместо этого можно запросить кэшированный HTML-код страницы, например, https://en.wikipedia.org/api/rest_v1/page/html/Main_Page (в целях улучшения производительности следует отметить, что это также доступно на https://en.wikipedia.org/api/rest_v1/page/html/Main_Page, чтобы повторно использовать существующее сетевое соединение с вики). В отличие от ?action=render, такой запрос выдаёт завершённый HTML-документ (то есть <html><head>различные метаданные</head><body>...</body></html>); вы можете использовать библиотеку обработки HTML, чтобы получить HTML-содержимое тега <body> (см. документацию).

Чтобы получить информацию, получаемую из викитекста во время парсинга (ссылки, категории, разделы и т. д.), вы можете:

действовать в связи с внесёнными в 2015 году изменениями в API?

Поведение по умолчанию продолжения запроса было изменено в MediaWiki 1.26. Если вы запрашиваете дополнительные данные на основании информации о продолжении, полученной из ответа API, вам необходимо обновить свой код. Либо

Также, начиная с MediaWiki 1.25, доступна улучшенная структура вывода для форматов JSON и PHP , если вы добавите formatversion=2 к своим запросам. По состоянию на июль 2015, эта функция всё ещё считается экспериментальной, поскольку некоторые модули API могут получить дальнейшие улучшения, связанные с этим режимом. Если вы готовы рисковать возможной необходимостью внести в будущем изменения для адаптации под новый вариант, намного лучше обрабатывать результаты API, используя параметр formatversion=2.

Почему ...

я получаю HTTP 403 ошибки?

Это может означать, что вы не указываете заголовок HTTP User-Agent, или что ваш User-Agent пуст или внесён в чёрный список (m:User-Agent policy). См. руководство по быстрому старту для большей информации. Также это может означать, что вы указываете & в строке GET-запроса: Викимедиа блокирует все такие запросы, используйте для них POST.

я получаю readapidenied ошибку?

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

я получаю badtoken ошибки?

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

я получаю предупреждения вместо токенов (Action 'edit' is not allowed for the current user)?

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

я получаю ошибку mustposttoken?

Действие, которое вы пытаетесь совершить, должно быть запрошено с использованием метода HTTP POST. Возможно, вы щёлкнули по ссылке на URL api.php в браузере или изменили существующий URL в адресной строке браузера, что приводит к запросу с методом GET. Вам нужно использовать библиотеку (например, модуль mediawiki.api ResourceLoader) или утилиту, способную отправлять POST-запросы; обычно также необходимо предоставлять API куки сеанса и токен, чтобы MediaWiki мог проверить, что вы действительно вошедший в учётную запись пользователь, обладающий нужными правами для выполнения действия. В качестве оригинального способа вы можете использовать утилиту командной строки cURL, предоставляя ей каждый параметр API, используя -F 'action=delete' -F 'token=шестнадцатеричные данные+\', и необходимые куки браузера, используя -H 'Cookie:ваши куки сеанса'. Панель Network окна инструментов разработчика в браузере (Ctrl+Shift+I) в Firefox и Chromium имеет пункт меню "Copy as cURL", который, хотя и может помочь, требует кропотливой работы.

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

X не доступно через API?

Не все возможности, доступные в пользовательском интерфейсе, доступны в API. Такие возможности не были реализованы, поскольку либо никто не добрался до этого, либо никто этого не запрашивал. Для информации об отправке запросов на введение возможностей, см. выше.

мой вызов API на вики Викимедиа просто возвращает ошибку HTML?

Если вы вызываете API POST-запросами, удостоверьтесь, что эти запросы не используют Content-Type: multipart/form-data. Это происходит, например, если вы используете CURL для доступа к API и передаёте параметры POST в виде массива. Прокси-сервера Squid, используемые на frontend-серверах на вики-ферме Викимедиа, не обрабатывают такие запросы корректно, и поэтому выдаётся ошибка.

Вместо этого используйте нотацию "value1=key1&value2=key2...", передавая параметры в виде строк, как в GET-запросах.

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

Также следует отметить, что некоторое программное обеспечение (например, cURL) посылает заголовок Expect: 100-continue для более длинных POST-запросов (более 1024 байт). Вики Викимедиа, проходящие через сервера Squid, не могут справиться с этим. Если вы всё ещё получаете ошибки HTML при отправке POST-запросов, и вы не вошли в учётную запись, попробуйте задать пустой заголовок Expect (например, используя cURL в командной строке, используйте опцию --header 'Expect:').

очень длинные URL запросов к API не работают?

Существует ограничение на размер URL, который может быть использован при отправке GET-запросов к API. Это ограничение зависит от сайта. У сайтов Викимедиа это примерно 8100 символов. Чтобы обойти ограничение, используйте POST-запросы (вам также может понадобиться задать заголовок Expect, как сказано выше).