Axuda da API de MediaWiki
Esta é unha páxina de documentación da API de MediaWiki xerada automaticamente.
Información xeral
Estado: A API de MediaWiki é unha interface estable e consolidada que ten un mantemento activo e está en constante mellora. Aínda que intentamos evitalo, ocasionalmente precisamos facer cambios importantes que rompen a estrutura anterior; podes apuntarte á lista de discusión mediawiki-api-announce para recibires información acerca das actualizacións.
Solicitudes incorrectas: Cando se envían solicitudes incorrectas á API, envíase unha cabeceira HTTP coa chave «MediaWiki-API-Error» e, a seguir, tanto o valor da cabeceira como o código de erro devolto quedarán definidos co mesmo valor. Para obter máis información, consulta API: Erros e avisos.
Probas: Para facilitar as solicitudes de proba á API, consulta Special:ApiSandbox.
Métodos de solicitude
As solicitudes feitas á API de acción poden utilizar métodos GET e POST. Prefírese o método GET, que permite que as solicitudes sexan enrutadas a servidores de réplica máis rápidos e que as respostas sexan almacenadas en caché, a menos que a lonxitude do enderezo URL con parámetros exceda o seu límite de lonxitude (normalmente 8000 bytes) ou un módulo só acepte solicitudes POST.
Os parámetros das solicitudes POST poden enviarse na parte de consulta do enderezo URL da solicitude (como nas solicitudes GET) e no corpo de solicitude POST; está permitido mesturar ambas os dous modos nunha solicitude. Certos parámetros, como os contrasinais, deben enviarse no corpo da solicitude. Se o mesmo parámetro se envía como parte do enderezo URL e tamén no corpo da solicitude, debe ter o mesmo valor en ambos os dous lugares.
Tipos de datos
A entrada de MediaWiki debería ser UTF-8 normalizada por NFC. MediaWiki pode intentar converter outras entradas, pero isto pode provocar que fallen algunhas operacións (como editar coas comprobacións MD5).
Os parámetros que toman varios valores envíanse normalmente cos valores separados mediante un carácter de barra vertical; por exemplo, param=value1|value2 ou param=value1%7Cvalue2. Se un valor debe conter unha barra vertical, usa U+001F (o separador de unidades) como separador e engade o prefixo U+001F ao valor; por exemplo, param=%1Fvalue1%1Fvalue2.
Algúns tipos de parámetros nas solicitudes á API necesitan máis explicacións:
- boolean
Os parámetros booleanos funcionan como as caixas de verificación HTML: se se especifica o parámetro, independentemente do seu valor, considérase verdadeiro. Para un valor falso, omite o parámetro por completo.
- expiry
Os tempos de caducidade poden ser relativos (por exemplo, 5 months ou 2 weeks) ou absolutos (por exemplo, 2014-09-18T12:34:56Z). Para que non caduque, usa infinite, indefinite, infinity ou never.
- timestamp
As marcas de tempo poden especificarse en varios formatos, consulta os formatos de entrada da biblioteca de marcas de tempo documentados en mediawiki.org para obter máis información. Recoméndase a data e hora ISO 8601: 2001-01-15T14:56:00Z. A cadea now pódese usar para especificar a hora actual.
Límites
A meirande parte dos módulos da API aceptan 50 entradas en parámetros multivaluados e poden devolver ata 500 resultados por consulta (50 resultados no caso das consultas lentas).
Aqueles usuarios co dereito apihighlimits (Botse Administradores) teñen límites ampliados, con 500 entradas e 5.000 resultados (500 resultados no caso das consultas lentas).
Parámetros modelados
Os parámetros modelados admiten casos nos que un módulo da API necesita un valor para cada valor dalgún outro parámetro. Por exemplo, se houbese un módulo da API para solicitar froita, podería ter un parámetro froitas para especificar que froitas se están solicitando e un parámetro modelado {froita}-cantidade para especificar cantas froitas de cada queres solicitar. Un cliente da API que queira 1 mazá, 5 plátanos e 20 amorodos podería facer unha solicitude como froitas=mazás|plátanos|amorodos&mazás-cantidade=1&plátanos-cantidade=5&amorodos-cantidade=20.
Módulo principal
- Fonte: MediaWiki
- Licenza: GPL-2.0-or-later
Specify the action to perform, the format of the response, and options that apply to all API modules.
- action
Que acción realizar. Este parámetro debe enviarse como parte do enderezo URL da solicitude (non do corpo POST) para facilitar o seu uso na depuración, análise e enrutamento ou filtrado de solicitudes.
- abusefiltercheckmatch
- Verificar se un filtro de abusos coincide cun conxunto de variables, unha edición ou un evento rexistrado do rexistro de abusos.
- abusefilterchecksyntax
- Revisar a sintaxe dun filtro de abusos.
- abusefilterevalexpression
- Avalía unha expresión do filtro de abusos.
- abusefilterunblockautopromote
- Desbloquea a un usuario de recibir autopromocións debido a unha consecuencia do filtro de abusos.
- abuselogprivatedetails
- Ver detalles privados dunha entrada do rexistro de abusos.
- acquiretempusername
- Adquirir un nome de usuario temporal e almacenalo na sesión actual, se a creación de contas temporais está habilitada e o usuario actual non iniciou a sesión. Se xa se gardou un nome, devolve ese mesmo nome.
- antispoof
- Comprobar un nome de usuario coas comprobacións de normalización de AntiSpoof
- block
- Bloquear un usuario.
- centralauthtoken
- Obter un identificador central de autorización para facer unha petición autenticada a un wiki asociado.
- centralnoticecdncacheupdatebanner
- Solicitar a purga do contido do cartel almacenado na caché CDN (cliente) para os usuarios anónimos, para o cartel e o idioma solicitados
- centralnoticechoicedata
- Obter os datos necesarios para escoller un cartel para un proxecto e lingua dados
- centralnoticequerycampaign
- Obter todos os parámetros de configuración dunha campaña.
- changeauthenticationdata
- Cambiar os datos de autenticación do usuario actual.
- changecontentmodel
- Cambiar o modelo de contido dunha páxina
- checktoken
- Verificar a validez dun identificador de action=query&meta=tokens.
- clearhasmsg
- Limpar a bandeira
hasmsgpara o usuario actual - clientlogin
- Conectarse á wiki usando o fluxo interactivo.
- communityconfigurationedit
- Change the content of a configuration provider in Community configuration
- compare
- Obter as diferencias entre dúas páxinas.
- createaccount
- Crear unha nova conta de usuario.
- createlocalaccount
- Forzar a creación dunha conta local. Debe existir unha conta central.
- delete
- Borrar a páxina.
- deleteglobalaccount
- Eliminar un usuario global.
- discussiontoolsedit
- Publicar unha mensaxe nunha páxina de conversa.
- discussiontoolsfindcomment
- Atopar un comentario mediante o seu identificador ou o seu nome.
- discussiontoolsgetsubscriptions
- Obter os estados de subscrición dos fíos indicados.
- discussiontoolssubscribe
- Subscribirse (ou cancelar a subscrición) para recibir notificacións dun fío.
- discussiontoolsthank
- Enviar unha notificación pública de agradecemento por un comentario.
- echocreateevent
- Activar manualmente unha notificación a un usuario
- echomarkread
- Marcar as notificacións como lidas para o usuario actual.
- echomarkseen
- Marcar as notificacións como vistas para o usuario actual.
- echomute
- Silenciar ou activar as notificacións de determinados usuarios ou páxinas.
- edit
- Crear e editar páxinas.
- editmassmessagelist
- Editar unha lista de entrega de mensaxes en masa.
- emailuser
- Enviar un correo electrónico a un usuario.
- expandtemplates
- Expandir tódolos modelos dentro do wikitexto.
- featuredfeed
- Retorna unha fonte de novas de contidos destacados
- feedcontributions
- Devolve a lista de contribucións dun usuario.
- feedrecentchanges
- Devolve un ficheiro de cambios recentes.
- feedwatchlist
- Devolve o fluxo dunha lista de vixilancia.
- filerevert
- Revertir o ficheiro a unha versión anterior.
- globalblock
- Bloquear ou desbloquear globalmente un usuario.
- globalpreferenceoverrides
- Cambiar preferencias locais para a conta de usuario actual.
- globalpreferences
- Cambiar as preferencias da conta de usuario actual.
- globaluserrights
- Engadir/eliminar un usuario a/de grupos globais.
- help
- Amosar axuda para os módulos indicados.
- imagerotate
- Este módulo foi desactivado.
- import
- Importar unha páxina doutra wiki, ou dun ficheiro XML.
- jsonconfig
- Permite o acceso directo ó subsistema JsonConfig.
- languagesearch
- Procurar nomes de lingua en calquera script.
- linkaccount
- Vincular unha conta dun provedor externo ó usuario actual.
- login
- Iniciar sesión e obter as cookies de autenticación.
- logout
- Terminar e limpar os datos de sesión.
- managetags
- Realizar tarefas de xestión relacionadas coa modificación de etiquetas.
- massmessage
- Enviar unha mensaxe a unha lista de páxinas.
- mergehistory
- Fusionar os historiais das páxinas.
- move
- Mover unha páxina.
- opensearch
- Buscar no wiki mediante o protocolo OpenSearch.
- options
- Cambiar as preferencias do usuario actual.
- paraminfo
- Obter información sobre módulos API.
- parse
- Fai a análise sintáctica do contido e devolve o resultado da análise.
- patrol
- Patrullar unha páxina ou edición.
- protect
- Cambiar o nivel de protección dunha páxina.
- purge
- Borrar a caché para os títulos indicados.
- query
- Consultar datos de e sobre MediaWiki.
- removeauthenticationdata
- Elimina os datos de autenticación do usuario actual.
- resetpassword
- Envía un correo de inicialización de contrasinal a un usuario.
- revisiondelete
- Borrar e restaurar revisións.
- rollback
- Desfacer a última edición da páxina.
- rsd
- Exportar un esquema RSD (Really Simple Discovery).
- setglobalaccountstatus
- Agochar ou bloquear (ou amosar ou desbloquear) unha conta de usuario global.
- setnotificationtimestamp
- Actualizar a data e hora de notificación das páxinas vixiadas.
- setpagelanguage
- Cambiar a lingua dunha páxina.
- shortenurl
- Acurtar un URL longo nun máis curto.
- sitematrix
- Obter a lista dos sitios da Wikimedia.
- spamblacklist
- Validar un o máis enderezos URL contra a lista de bloqueos de spam.
- streamconfigs
- Expón a configuración do fluxo de eventos. Devolve só format=json con formatversion=2.
- strikevote
- Permite ós administradores anular ou restaurar un voto.
- tag
- Engadir ou eliminar etiquetas de cambio de revisións individuais ou entradas de rexistro.
- templatedata
- Obter os datos almacenador pola extensión TemplateData.
- thank
- Enviar unha notificación de agradecemento a un editor.
- titleblacklist
- Validar un título de páxina, ficheiro ou nome de usuario contra a lista negra de títulos.
- torblock
- Comprobar se un enderezo IP está bloqueado como un nodo de saída de Tor.
- transcodereset
- Os usuarios co permiso "transcode-reset" poden reiniciar e volver executar un traballo de transcodificación.
- unblock
- Desbloquear un usuario.
- undelete
- Restaurar modificacións dunha páxina borrada.
- unlinkaccount
- Elimina unha conta vinculada do usuario actual.
- upload
- Subir un ficheiro, ou obter o estado das subas pendentes.
- userrights
- Cambiar a pertencia dun usuario a un grupo.
- validatepassword
- Valida un contrasinal contra as políticas de contrasinais da wiki.
- watch
- Engadir ou borrar páxinas da lista de vixilancia do usuario actual.
- webapp-manifest
- Devolve un manifesto de aplicación web.
- webauthn
- Módulo API para comunicarse entre o servidor e o cliente durante o proceso de rexistro/autenticación.
- bouncehandler
- Interno. Recibir un correo electrónico rexeitado e procesalo para xestionar o destinatario erróneo.
- categorytree
- Interno. Módulo interno para a extensión CategoryTree.
- chartinfo
- Interno. Recuperar a conta actual dos usos únicos de páxinas con gráficos. Os usos múltiples do mesmo gráfico na mesma páxina considéranse un único uso.
- cirrus-check-sanity
- Interno. Informa sobre a corrección dun rango de identificadores de páxina no índice de procura
- cirrus-config-dump
- Interno. Descarga da configuración de CirrusSearch.
- cirrus-profiles-dump
- Interno. Descarga dos perfís de CirrusSearch para este wiki.
- cirrus-schema-dump
- Interno. Descarga do esquema de CirrusSearch (configuración e correspondencias) para este wiki.
- codemirror-validate
- Interno. Comprobar se hai erros de validación no contido dado
- collection
- Interno. Módulo da API para realizar varias operacións na colección dun usuario do wiki.
- cspreport
- Interno. Usado polos navegadores para informar de violacións da política de confidencialidade de contido. Este módulo non debe se usado nunca, excepto cando é usado automaticamente por un navegador web compatible con CSP.
- discussiontoolscompare
- Interno. Obter información sobre os cambios no comentario entre dúas revisións da páxina.
- discussiontoolspageinfo
- Interno. Devolve os metadatos necesarios para iniciar as ferramentas de conversa.
- discussiontoolspreview
- Interno. Previsualizar unha mensaxe nunha páxina de conversa.
- editcheckreferenceurl
- Interno. Check the status of a URL for use as a reference.
- fancycaptchareload
- Interno. Obter un novo FancyCaptcha.
- jsondata
- Interno. Recuperar os datos JSON localizados.
- jsontransform
- Interno. Recuperar os datos JSON transformados por unha función de Lua.
- parser-migration
- Interno. Analizar unha páxina con dúas configuracións de analizador diferentes.
- readinglists
- Interno. Operacións de escritura das listas de lectura.
- sanitize-mapdata
- Interno. Realiza a validación dos datos para a extensión Kartographer
- scribunto-console
- Interno. Módulo interno para servir peticións XHR dende a consola Scribunto.
- securepollauth
- Interno. Permite que un wiki remoto autentique os usuarios antes de concederlles acceso para votar nas eleccións.
- stashedit
- Interno. Preparar unha edición na caché compartida.
- timedtext
- Interno. Proporciona contido de texto cronometrado para o seu uso polos elementos <track>
- ulslocalization
- Interno. Obter a localización do ULS na lingua dada.
- ulssetlang
- Interno. Actualiza a lingua da interface preferida do usuario.
- visualeditor
- Interno. Devolve o código HTML5 para unha páxina do servizo Parsoid.
- visualeditoredit
- Interno. Gardar unha páxina HTML5 en MediaWiki (convertida en texto wiki mediante o servizo do Parsoid).
- wikimediaeventsblockededit
- Interno. Rexistrar a información sobre os intentos de edición bloqueados
- wikimediaeventshcaptchaeditattempt
- Interno. Rexistrar a diferenza de edición cando se mostra o desafío de hCaptcha pero a edición está incompleta
- Un valor dos seguintes valores: abusefiltercheckmatch, abusefilterchecksyntax, abusefilterevalexpression, abusefilterunblockautopromote, abuselogprivatedetails, acquiretempusername, antispoof, block, centralauthtoken, centralnoticecdncacheupdatebanner, centralnoticechoicedata, centralnoticequerycampaign, changeauthenticationdata, changecontentmodel, checktoken, clearhasmsg, clientlogin, communityconfigurationedit, compare, createaccount, createlocalaccount, delete, deleteglobalaccount, discussiontoolsedit, discussiontoolsfindcomment, discussiontoolsgetsubscriptions, discussiontoolssubscribe, discussiontoolsthank, echocreateevent, echomarkread, echomarkseen, echomute, edit, editmassmessagelist, emailuser, expandtemplates, featuredfeed, feedcontributions, feedrecentchanges, feedwatchlist, filerevert, globalblock, globalpreferenceoverrides, globalpreferences, globaluserrights, help, imagerotate, import, jsonconfig, languagesearch, linkaccount, login, logout, managetags, massmessage, mergehistory, move, opensearch, options, paraminfo, parse, patrol, protect, purge, query, removeauthenticationdata, resetpassword, revisiondelete, rollback, rsd, setglobalaccountstatus, setnotificationtimestamp, setpagelanguage, shortenurl, sitematrix, spamblacklist, streamconfigs, strikevote, tag, templatedata, thank, titleblacklist, torblock, transcodereset, unblock, undelete, unlinkaccount, upload, userrights, validatepassword, watch, webapp-manifest, webauthn, bouncehandler, categorytree, chartinfo, cirrus-check-sanity, cirrus-config-dump, cirrus-profiles-dump, cirrus-schema-dump, codemirror-validate, collection, cspreport, discussiontoolscompare, discussiontoolspageinfo, discussiontoolspreview, editcheckreferenceurl, fancycaptchareload, jsondata, jsontransform, parser-migration, readinglists, sanitize-mapdata, scribunto-console, securepollauth, stashedit, timedtext, ulslocalization, ulssetlang, visualeditor, visualeditoredit, wikimediaeventsblockededit, wikimediaeventshcaptchaeditattempt
- Por defecto: help
- format
O formato de saída.
- json
- Datos de saída en formato JSON.
- jsonfm
- Datos de saída en formato JSON (impresión en HTML).
- none
- Ningunha saída.
- rawfm
- Datos de saída, incluíndo os elementos de depuración, en formato JSON (impresión en HTML).
- xml
- Datos de saída en formato XML.
- xmlfm
- Datos de saída en formato XML (impresión en HTML).
- Un valor dos seguintes valores: json, jsonfm, none, rawfm, xml, xmlfm
- Por defecto: jsonfm
- maxlag
O retardo máximo pode usarse cando MediaWiki está instalada nun cluster de base de datos replicadas. Para gardar accións que causen calquera retardo máis de replicación do sitio, este parámetro pode facer que o cliente espere ata que o retardo de replicación sexa menor que o valor especificado. No caso de retardo excesivo, é devolto o código de erro maxlag cunha mensaxe como esperando por $host: $lag segundos de retardo.
Para máis información, ver Manual: Maxlag parameter.- Tipo: número enteiro
- smaxage
Fixar a cabeceira HTTP de control de caché
s-maxagea eses segundos. Os erros nunca se gardan na caché.- Tipo: número enteiro
- O valor non debe ser inferior a 0.
- Por defecto: 0
- maxage
Fixar a cabeceira HTTP de control de caché
max-agea eses segundos. Os erros nunca se gardan na caché.- Tipo: número enteiro
- O valor non debe ser inferior a 0.
- Por defecto: 0
- assert
Verificar que o usuario está conectado (incluíndo a posibilidade de que sexa unha conta temporal) se ten o valor user, non conectado se ten o valor anon ou ten dereitos de bot se ten o valor bot.
- Un valor dos seguintes valores: anon, bot, user
- assertuser
Verificar que o usuario actual é o usuario nomeado.
- Tipo: usuario, por calquera de nome de usuarioe Usuario temporal
- requestid
Calquera valor dado aquí será incluído na resposta. Pode usarse para distingir peticións.
- servedby
Incluír o nome do servidor que serviu a solicitude nos resultados.
- Tipo: booleano (detalles)
- curtimestamp
Incluír a marca de tempo actual no resultado.
- Tipo: booleano (detalles)
- responselanginfo
Incluír no resultado as linguas usada para uselang e errorlang.
- Tipo: booleano (detalles)
- origin
Cando se accede á API usando unha petición AJAX entre dominios (CORS), establecer o parámetro co dominio de orixe. Isto debe incluírse en calquera petición «pre-flight» e, polo tanto, debe ser parte do enderezo URL da petición (non do corpo POST).
Para peticións autenticadas, isto debe coincidir exactamente cunha das orixes na cabeceira
Origin, polo que ten que establecerse a algo como https://en.wikipedia.org ou https://meta.wikimedia.org. Se este parámetro non coincide coa cabeceiraOrigin, devolverase unha resposta 403. Se este parámetro coincide coa cabeceiraOrigine a orixe está permitida, as cabeceirasAccess-Control-Allow-OrigineAccess-Control-Allow-Credentialsquedarán fixadas.Para peticións non autenticadas, especificar o valor *. Isto fará que se fixe a cabeceira
Access-Control-Allow-Origin, peroAccess-Control-Allow-Credentialsseráfalsee todos os datos específicos dos usuarios quedarán ocultos.- crossorigin
Cando se accede á API usando unha petición AJAX entre dominios (CORS) usando un provedor de sesións seguro fronte a ataques de falsificación de petición en sitios cruzados (CSRF) (como OAuth), utilizar isto no canto de
origin=*para que a petición estea autenticada. Isto debe incluírse en calquera petición «pre-flight» e, polo tanto, debe ser parte do enderezo URL da petición (non do corpo POST).Nótese que a maioría dos provedores de sesións, incluídas as sesións estándar baseadas en cookies, non admiten as peticións CORS autenticadas e non se poden utilizar con este parámetro.
- Tipo: booleano (detalles)
- uselang
Lingua a usar para a tradución de mensaxes. action=query&meta=siteinfo&siprop=languages devolve unha lista de códigos de lingua. Podes especificar user para usar a preferencia de lingua do usuario actual ou content para usar a lingua do contido deste wiki.
- Por defecto: user
- variant
Variante da lingua. Só funciona se a lingua base admite a conversión de variantes.
- errorformat
Formato a usar para a saída de texto de avisos e de erros
- plaintext
- Texto wiki sen as etiquetas HTML e coas entidades substituídas.
- wikitext
- Texto wiki sen analizar.
- html
- HTML
- raw
- Clave e parámetros da mensaxe.
- none
- Sen saída de texto, só os códigos de erro.
- bc
- Formato utilizado antes de MediaWiki 1.29. errorlang e errorsuselocal non se teñen en conta.
- Un valor dos seguintes valores: bc, html, none, plaintext, raw, wikitext
- Por defecto: bc
- errorlang
Lingua a usar para as advertencias e os erros. action=query&meta=siteinfo&siprop=languages devolve unha lista de códigos de lingua. Podes especificar content para utilizar a lingua do contido deste wiki ou uselang para utilizar o mesmo valor có do parámetro uselang.
- Por defecto: uselang
- errorsuselocal
Se se indica, os textos de erro empregarán mensaxes adaptadas á lingua do espazo de nomes MediaWiki.
- Tipo: booleano (detalles)
- centralauthtoken
Cando se accede á API usando unha petición AJAX desde outro dominio (CORS), use isto para autenticarse como o usuario SUL actual. Use action=centralauthtoken neste wiki para obter o identificador, antes de facer a petición CORS. Cada identificador só pode usarse unha vez e caduca aos 60 segundos. Isto debe incluírse en calquera petición de esbozo, e por iso debe incluírse na URI da petición (non no corpo POST).
Neste wiki, o valor esperado é un token web JSON, que pode ser validado por servidores proxy fronte a MediaWiki. Se o token caducou ou non é válido por ningún outro motivo, pode recibir un erro HTTP dun proxy nun formato diferente ao dun erro de API normal.
- Axuda para o módulo principal
- api.php?action=help [abrir na zona de probas]
- Toda a axuda nunha páxina
- api.php?action=help&recursivesubmodules=1&toc [abrir na zona de probas]
Créditos
Desenvolvedores da API:
- Yuri Astrakhan (creador e desenvolvedor principal, set. 2006-set. 2007)
- Roan Kattouw (desenvolvedor principal, set. 2007-2009)
- Victor Vasiliev
- Bryan Tong Minh
- Sam Reed
- Brad Jorsch (desenvolvedor principal, 2013-2020)
Envía comentarios, suxestións e preguntas a [email protected] ou informa dun erro en https://phabricator.wikimedia.org/.