MediaWiki API 說明

此頁為自動產生的 MediaWiki API 說明文件頁面。

說明文件與範例:https://www.mediawiki.org/wiki/API

主要模組

狀態資訊:MediaWiki API 已是成熟、穩定,並積極支援以改善的介面。儘管我們儘可能避免,但仍偶有需要重大變更的情況,請訂閱mediawiki-api-announce 郵寄清單以便獲得更新通知。

錯誤的請求:當 API 收到錯誤的請求,會發出以「MediaWiki-API-Error」為鍵的 HTTP 標頭欄位,隨後標頭欄位的值,以及傳回的錯誤碼會設為相同值。詳細資訊請參閱 API: 錯誤與警告

參數:
action

要執行的動作。

adddomainalias
Add a domain alias to wiki
annotatewikinotspam
將這個wiki標記為非垃圾內容
block
封鎖使用者。
categorytree
用於 CategoryTree 擴充套件的內部模組。
changeauthenticationdata
為目前使用者變更身分核對資料。
checktoken
檢查來自 action=query&meta=tokens 的權杖有效性。
checkwikistatus
查看建立新wiki過程是否已經完成並回到全部過程狀態或單獨步驟狀態。
clearhasmsg
清除目前使用者的 hasmsg 標記。
clearwikiconfigcache
為wiki清空配置緩存。
clientlogin
使用互動流程來登入 wiki。
compare
比較 2 個頁面間的差異。
createaccount
建立新使用者帳號。
createnewwiki
開始建立新wiki程序。
createwikiconfigvariabledefinition
建立配置變數。
cspreport
由瀏覽器所使用來回報違反內容安全方針。此模組應永不使用,除了是在被由兼容內容安全方針的網路瀏覽器所使用情況下。
delete
刪除頁面。
details
edit
建立與編輯頁面。
emailuser
寄送電子郵件給使用者。
embedvideo
Get generated video embed code for given parameters.
expandtemplates
展開所有於 wikitext 中模板。
feedcontributions
回傳使用者貢獻摘要。
feedrecentchanges
返回近期變更摘要。
feedwatchlist
返回監視清單摘要。
filerevert
回退檔案至舊的版本。
gettheme
help
顯示指定模組的說明。
imagerotate
旋轉一張或多張圖片。
imageserving
This module is used to return one image URL for the specified article given either the article ID or article title (with prefix if applicable).
import
從其它 wiki 或 XML 檔案來匯入頁面。
infobox
This module provides infobox parser
linkaccount
從第三方供應者來連結帳號至目前的使用者。
linksuggest
於編輯視圖上為編者建議連結
listusersnamesearch
listuserssearchuser
listwikiswithextension
取得開啟擴充功能的wiki表單。
listwikiswithvariable
取得給定變數的wiki表單。
login
登入並取得身分核對 cookies
logout
登出並清除 session 資料。
lookupcontribs
Lookup user contributions
managetags
執行相關到更改標籤的管理任務。
markwikiclosed
標記wiki為關閉(公開不可用)。
markwikiopen
標記wiki為開放(公開可用)。
markwikiprotected
對wiki標記為保護狀態,無法進行關閉。
masseditwikis
為一系列的wiki編輯配置變數。
mergehistory
合併頁面歷史
mobileview
回傳手機檢視需要的資料。
modifydomainalias
Modify a domain alias to wiki
move
移動頁面。
multidelete
notifications
检索当前用户的通知。
opensearch
使用 OpenSearch 協定搜尋本 wiki。
options
更改目前使用者的偏好設定。
paraminfo
獲得有關 API 模組的資訊。
parse
解析內容併回傳解析器輸出。
parsoid-batch
用於 Parsoid 的批次 API
patrol
巡查頁面或修訂。
protect
變更頁面的保護層級。
purge
為指定標題清除快取。
query
擷取來自及有關MediaWiki的數據。
removeauthenticationdata
為目前使用者移除身分核對資料。
removedomainalias
Remove a domain alias to wiki
removephalanxblock
removewikiconfigvariable
移除wiki上配置的變數。
reopenwiki
resetpassword
寄送重新設定密碼的電子郵件給使用者。
revisiondelete
刪除和取消刪除修訂。
rollback
復原頁面的最後一次編輯。
rsd
匯出一個簡易探索(Really Simple Discovery、RSD)架構。
savetheme
savewikiconfigvariable
給這個wiki設定配置變數。
schedulesearchindexupdate
scribunto-console
來自 Scribunto 主控台用於服務 XHR 請求的內部模組。
setnotificationtimestamp
更新監視頁面的通知時間戳記。
setpagelanguage
更改頁面的語言。
stashedit
在分享快取裡預備編輯。
suggestwiki
suggestwikis
取得網域含有搜尋詞語的wiki清單
tag
從各別修訂或日誌項目添加或移除變更標籤。
tagsreport
templatedata
提供類似TemplateData擴充功能的API,視覺化編輯器用此解析模板參數
titleblacklist
檢驗一個頁面的標題、檔案名稱或使用者名稱是否觸發標題黑名單。
transcodereset
具「transcode-reset」權限的使用者可以重新設定和重新執行轉碼任務。
unblock
解除封鎖一位使用者。
undelete
恢復已刪除頁面的修訂。
unlinkaccount
移除目前使用者所連結到的第三方帳號。
updateHubs
為這個wiki更新分類和主題
updateprimarydomain
Update primary domain of a wiki
updatewikiconfigvariabledefinition
更新已存在的配置變數屬性。
upload
上傳檔案,或取得等待上傳的狀態。
uploadimage
userrights
變更一位使用者的群組成員。
validatepassword
驗證密碼是否符合 wiki 的密碼方針。
variableinfo
取得給定配置變數的詳細訊息。
variableupdate
更新變數訊息
visualeditor
從 Parsoid 服務回傳一個頁面的 HTML5。
visualeditoredit
儲存一個 HTML5 頁面至 MediaWiki (透過 Parsoid 服務轉換爲 WikiText)。
watch
從目前使用者的監視清單添加或移除頁面。
webapp-manifest
回傳 webapp manifest。
tokens
已停用。 取得資料修改動作的權杖。
單值:adddomainaliasannotatewikinotspamblockcategorytreechangeauthenticationdatachecktokencheckwikistatusclearhasmsgclearwikiconfigcacheclientlogincomparecreateaccountcreatenewwikicreatewikiconfigvariabledefinitioncspreportdeletedetailseditemailuserembedvideoexpandtemplatesfeedcontributionsfeedrecentchangesfeedwatchlistfilerevertgetthemehelpimagerotateimageservingimportinfoboxlinkaccountlinksuggestlistusersnamesearchlistuserssearchuserlistwikiswithextensionlistwikiswithvariableloginlogoutlookupcontribsmanagetagsmarkwikiclosedmarkwikiopenmarkwikiprotectedmasseditwikismergehistorymobileviewmodifydomainaliasmovemultideletenotificationsopensearchoptionsparaminfoparseparsoid-batchpatrolprotectpurgequeryremoveauthenticationdataremovedomainaliasremovephalanxblockremovewikiconfigvariablereopenwikiresetpasswordrevisiondeleterollbackrsdsavethemesavewikiconfigvariableschedulesearchindexupdatescribunto-consolesetnotificationtimestampsetpagelanguagestasheditsuggestwikisuggestwikistagtagsreporttemplatedatatitleblacklisttranscoderesetunblockundeleteunlinkaccountupdateHubsupdateprimarydomainupdatewikiconfigvariabledefinitionuploaduploadimageuserrightsvalidatepasswordvariableinfovariableupdatevisualeditorvisualeditoreditwatchwebapp-manifesttokens
預設值:help
format

輸出的格式。

json
使用 JSON 格式輸出資料。
jsonfm
使用 JSON 格式輸出資料 (使用 HTML 格式顯示)。
none
不輸出。
php
使用序列化 PHP 格式輸出資料。
phpfm
使用序列化 PHP 格式輸出資料 (使用 HTML 格式顯示)。
rawfm
使用 JSON 格式的除錯元素輸出資料 (使用 HTML 格式顯示)。
xml
使用 XML 格式輸出資料。
xmlfm
使用 XML 格式輸出資料 (使用 HTML 格式顯示)。
單值:jsonjsonfmnonephpphpfmrawfmxmlxmlfm
預設值:jsonfm
maxlag

最大延遲可在當 MediaWiki 安裝於資料庫複寫叢集時使用。為了保存引起更多站台複寫延遲的操作,此參數可讓客戶端等待至複寫延遲小於指定值為止。在過渡延遲的情況下,錯誤碼 maxlag 會帶有著像是 Waiting for $host: $lag seconds lagged 的訊息內容回傳。
請查看手冊:Maxlag 參數來獲取更多資訊。

類型:整數
smaxage

將HTTP暫存控制頭欄位設為s-maxage秒。錯誤不會做暫存。

類型:整數
預設值:0
maxage

將HTTP暫存控制頭欄位設為max-age秒。錯誤不會做暫存。

類型:整數
預設值:0
assert

若設為user,會確認使用者是否已登入;若設為bot,會確認是否擁有機械人權限。

單值:userbot
assertuser

確認目前使用者就是指定的使用者。

類型:使用者名稱
requestid

在此處提供的任何值都將包括在響應之中。可用於區分請求。

servedby

在結果中包括提出請求的主機名。

類型:布林值(詳細資訊
curtimestamp

在結果中包括目前的時間戳記。

類型:布林值(詳細資訊
responselanginfo

在結果中包括uselangerrorlang所用的語言。

類型:布林值(詳細資訊
origin

當使用跨網域 AJAX 請求(cross-domain AJAX request、CORS)來存取 API 時,設定此為起始網域。這必須包含在任何預檢請求裡,因此得是請求 URI 的一部份(不是 POST 主體)。

對於已認證請求,這必須準確地符合在 Origin 標頭裡其一的起始點,因此會被設定成像是 https://zh.wikipedia.org 或是 https://meta.wikimedia.org。如果此參數不符合 Origin 標頭,會回傳 403 錯誤回應。若此參數符合 Origin 標頭且起始點被列在白名單裡,將會設定 Access-Control-Allow-OriginAccess-Control-Allow-Credentials 標頭。

對於非認證請求,會指定值 *。這會產生 Access-Control-Allow-Origin 標頭有被設定;但 Access-Control-Allow-Credentials 會是 false 值,且所有使用者指定資料會受限制。

uselang

訊息翻譯採用的語言。使用 action=query&meta=siteinfosiprop=languages 會回傳語言代碼清單、或指定 user 來使用目前使用者的語言偏好設定、或是指定 content 來使用此 wiki 的內容語言。

預設值:user
errorformat

用於警告和錯誤文字輸出的格式。

plaintext:移除掉 HTML 標籤,且實體已替換的 wiki 文字。
wikitext:未解析的 wiki 文字。
html:HTML。
raw:訊息鍵值與參數。
none:無文字輸出,僅含有錯誤代碼。
bc:用於 MediaWiki 1.29 之前版本的格式。會忽略 errorlangerrorsuselocal
單值:plaintextwikitexthtmlrawnonebc
預設值:bc
errorlang

警告與錯誤採用的語言。使用 action=query&meta=siteinfosiprop=languages 會回傳語言代碼清單、或指定 content 來使用此 wiki 的內容語言、或是指定 uselang 來使用與 uselang 參數相同的值。

預設值:uselang
errorsuselocal

若有指定,錯誤文字會使用來自 MediaWiki 命名空間的本地自定義訊息。

類型:布林值(詳細資訊
權限:
writeapi
使用寫入 API
已授權給: all、user 和 bot
apihighlimits
在 API 查詢使用較高的限制(慢速查詢:500;快速查詢:5000)。慢速查詢的限制也適用於多值參數。
已授權給: bot、sysop、staff、helper、soap、wiki-representative 和 wiki-specialist

資料類型

至MediaWiki的輸入值應為NFC標準化的UTF-8。MediaWiki可以嘗試轉換其他輸入值,但這可能導致一些操作失敗(例如附帶MD5檢查的編輯)。

一些在API請求中的參數類型需要更進一步解釋:

boolean
布林參數產生作用就像HTML複選框一樣:如果參數被指定,無論何值都被視為真(true)。如果要假值(false),則必須省略參數。
timestamp
時間戳記可被指定為多種格式。推荐使用ISO 8601日期和時間標準。所有時間為UTC時間,包含的任何時區都會被忽略。
  • ISO 8601日期和時間,2001-01-15T14:56:00Z(標點和Z為選用)
  • 帶小數秒(會被忽略)的ISO 8601日期和時間,2001-01-15T14:56:00.00001Z(破折號、冒號和Z為選用)
  • MediaWiki格式,20010115145600
  • 一般數字格式,2001-01-15 14:56:00GMT+##-##的選用時區會被忽略)
  • EXIF格式,2001:01:15 14:56:00
  • RFC 2822格式(時區可省略),Mon, 15 Jan 2001 14:56:00
  • RFC 850格式(時區可省略),Monday, 15-Jan-2001 14:56:00
  • C ctime格式,Mon Jan 15 14:56:00 2001
  • 從1970-01-01T00:00:00Z開始的秒數,作為1到13位數的整數(除了0
  • 字串now
替代多值分隔符號
使用多個值的參數通常會與垂直線符號(|)分隔的值一起提交,例如param=value1|value2param=value1%7Cvalue2。如果值必須包含垂直線符號,使用U+001F(單位分隔符號)作為分隔符號,並且在值前加前綴U+001F,例如param=%1Fvalue1%1Fvalue2

模板參數

模板參數可支援當 API 模組需要替某些參數值給予值的情況。舉例來說,如果有個用來請求水果的 API 模組,可能會有一個用來指定水果的 fruits 參數,以及用來指定有多少顆水果的模板參數 {fruit}-quantity。若一個 API 客戶端想要 1 顆蘋果、5 條香蕉、以及 20 粒草莓時,可以做出像是 fruits=apples|bananas|strawberries&apples-quantity=1&bananas-quantity=5&strawberries-quantity=20 這樣的請求。

製作群

API 開發人員:

  • Roan Kattouw (首席開發者 Sep 2007–2009)
  • Victor Vasiliev
  • Bryan Tong Minh
  • Sam Reed
  • Yuri Astrakhan (創立者,首席開發者 Sep 2006–Sep 2007)
  • Brad Jorsch (首席開發者 2013–present)

請傳送您的評論、建議以及問題至 mediawiki-api@lists.wikimedia.org 或者回報問題至 https://phabricator.wikimedia.org/。