MediaWiki API 說明
此頁為自動產生的 MediaWiki API 說明文件頁面。
說明文件與範例:https://www.mediawiki.org/wiki/API
主要模組
- 來源:MediaWiki
- 協定:GPL-2.0-or-later
狀態資訊:MediaWiki API 已是成熟、穩定,並積極支援以改善的介面。儘管我們儘可能避免,但仍偶有需要重大變更的情況,請訂閱mediawiki-api-announce 郵寄清單以便獲得更新通知。
錯誤的請求:當 API 收到錯誤的請求,會發出以「MediaWiki-API-Error」為鍵的 HTTP 標頭欄位,隨後標頭欄位的值,以及傳回的錯誤碼會設為相同值。詳細資訊請參閱 API: 錯誤與警告。
測試:要簡化 API 請求的測試過程,請見 Special:ApiSandbox。
- action
要執行的動作。
- block
- 封鎖使用者。
- changeauthenticationdata
- 為目前使用者變更身分核對資料。
- checktoken
- 檢查來自 action=query&meta=tokens 的密鑰有效性。
- clearhasmsg
- 清除目前使用者的
hasmsg
標記。 - clientlogin
- 使用交互式流登录wiki。
- compare
- 比較 2 個頁面間的差異。
- createaccount
- 建立新使用者帳號。
- cspreport
- 由浏览器使用以报告违反内容安全方针的内容。此模块应永不使用,除了在被CSP兼容的浏览器自动使用时。
- delete
- 刪除頁面。
- edit
- 建立與編輯頁面。
- emailuser
- 寄送電子郵件給使用者。
- expandtemplates
- 展開所有於 wikitext 中模板。
- feedcontributions
- 回傳使用者貢獻 Feed。
- feedrecentchanges
- 返回最近變更摘要。
- feedwatchlist
- 返回監視清單 feed。
- filerevert
- 回退檔案至舊的版本。
- help
- 顯示指定模組的說明。
- imagerotate
- 旋轉一張或多張圖片。
- import
- 從其它 wiki 或 XML 檔案來匯入頁面。
- linkaccount
- 将来自第三方提供商的账户链接至当前用户。
- login
- 登入並取得身分核對 cookies
- logout
- 登出並清除 session 資料。
- managetags
- 執行相關到更改標籤的管理任務。
- mergehistory
- 合併頁面歷史
- mobileview
- 回傳手機檢視需要的資料。
- move
- 移動頁面。
- opensearch
- 使用 OpenSearch 協定搜尋本 wiki。
- options
- 更改目前使用者的偏好設定。
- paraminfo
- 獲得有關 API 模組的資訊。
- parse
- 解析內容併回傳解析器輸出。
- patrol
- 巡查頁面或修訂。
- protect
- 變更頁面的保護層級。
- purge
- 為指定標題清除快取。
- query
- 擷取來自及有關MediaWiki的數據。
- removeauthenticationdata
- 為目前使用者移除身分核對資料。
- resetpassword
- 寄送重新設定密碼的電子郵件給使用者。
- revisiondelete
- 刪除和取消刪除修訂。
- rollback
- 復原頁面的最後一次編輯。
- rsd
- 匯出一個簡易探索(Really Simple Discovery、RSD)架構。
- scribunto-console
- 來自 Scribunto 主控台用於服務 XHR 請求的內部模組。
- setnotificationtimestamp
- 更新監視頁面的通知時間戳記。
- setpagelanguage
- 更改頁面的語言。
- stashedit
- 在分享快取裡預備編輯。
- tag
- 从个别修订或日志记录中添加或移除更改标签。
- unblock
- 解除封鎖一位使用者。
- undelete
- 恢復已刪除頁面的修訂。
- unlinkaccount
- 移除目前使用者所連結到的第三方帳號。
- upload
- 上傳檔案,或取得等待上傳的狀態。
- userrights
- 變更一位使用者的群組成員。
- validatepassword
- 驗證密碼是否符合 wiki 的密碼方針。
- watch
- 從目前使用者的監視清單添加或移除頁面。
- webapp-manifest
- 回傳 webapp manifest。
- tokens
- 已停用。 取得資料修改動作的密鑰。
- 單值:block、changeauthenticationdata、checktoken、clearhasmsg、clientlogin、compare、createaccount、cspreport、delete、edit、emailuser、expandtemplates、feedcontributions、feedrecentchanges、feedwatchlist、filerevert、help、imagerotate、import、linkaccount、login、logout、managetags、mergehistory、mobileview、move、opensearch、options、paraminfo、parse、patrol、protect、purge、query、removeauthenticationdata、resetpassword、revisiondelete、rollback、rsd、scribunto-console、setnotificationtimestamp、setpagelanguage、stashedit、tag、unblock、undelete、unlinkaccount、upload、userrights、validatepassword、watch、webapp-manifest、tokens
- 預設值:help
- format
輸出的格式。
- 單值:json、jsonfm、none、php、phpfm、rawfm、xml、xmlfm
- 預設值:jsonfm
- maxlag
最大延迟可被用于MediaWiki安装于数据库复制集中。要保存导致更多网站复制延迟的操作,此参数可使客户端等待直到复制延迟少于指定值时。万一发生过多延迟,错误代码maxlag会返回消息,例如等待$host中:延迟$lag秒。
参见手册:Maxlag参数以获取更多信息。- 類型:整數
- smaxage
將HTTP緩存控制頭欄位設為
s-maxage
秒。錯誤不會做緩存。- 類型:整數
- 預設值:0
- maxage
將HTTP緩存控制頭欄位設為
max-age
秒。錯誤不會做緩存。- 類型:整數
- 預設值:0
- assert
若設為user,會確認使用者是否已登入;若設為bot,會確認是否擁有機械人權限。
- 單值:user、bot
- assertuser
確認目前使用者就是指定的使用者。
- 類型:使用者名稱
- requestid
在此處提供的任何值都將包括在響應之中。可用於區分請求。
- servedby
在結果中包括提出請求的主機名。
- 類型:布林值(詳細資訊)
- curtimestamp
在結果中包括目前的時間戳。
- 類型:布林值(詳細資訊)
- responselanginfo
在結果中包括uselang和errorlang所用的語言。
- 類型:布林值(詳細資訊)
- origin
当通过跨域名AJAX请求(CORS)访问API时,设置此作为起始域名。这必须包括在任何pre-flight请求中,并因此必须是请求的URI的一部分(而不是POST正文)。
对于已验证的请求,这必须正确匹配
Origin
标头中的原点之一,因此它已经设置为像https://en.wikipedia.org或https://meta.wikimedia.org的东西。如果此参数不匹配Origin
页顶,就返回403错误响应。如果此参数匹配Origin
页顶并且起点被白名单,将设置Access-Control-Allow-Origin
和Access-Control-Allow-Credentials
开头。对于未验证的请求,会指定值*。这将导致
Access-Control-Allow-Origin
标头被设置,但Access-Control-Allow-Credentials
将为false
,且所有用户特定数据将受限制。- uselang
用于消息翻译的语言。action=query&meta=siteinfo与siprop=languages可返回语言代码列表,或指定user以使用当前用户的语言设置,或指定content以使用此wiki的内容语言。
- 預設值:user
- errorformat
用于警告和错误文本输出的格式。
- plaintext
- 已移除HTML标签,并被替换实体的Wiki文本。
- wikitext
- 未解析的wiki文本。
- html
- HTML。
- raw
- 消息关键词和参数。
- none
- 无文本输出,仅包含错误代码。
- bc
- 在MediaWiki 1.29以前版本使用的格式。errorlang和errorsuselocal会被忽略。
- 單值:plaintext、wikitext、html、raw、none、bc
- 預設值:bc
- errorlang
用于警告和错误的语言。action=query&meta=siteinfo带siprop=languages返回语言代码的列表,或指定content以使用此wiki的内容语言,或指定uselang以使用与uselang参数相同的值。
- 預設值:uselang
- errorsuselocal
如果指定,错误文本将使用来自MediaWiki名字空间的本地自定义消息。
- 類型:布林值(詳細資訊)
- 主模組使用說明
- api.php?action=help [在沙盒中開啟]
- 一個頁面中的所有說明。
- api.php?action=help&recursivesubmodules=1 [在沙盒中開啟]
資料類型
至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:00(GMT、+##或-##的選用時區會被忽略)
- 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|value2或param=value1%7Cvalue2。如果值必須包含垂直線符號,使用U+001F(單位分隔符號)作為分隔符號,並且在值前加前綴U+001F,例如param=%1Fvalue1%1Fvalue2。
模板參數
模板参数支持API模块需要为每个其他参数赋值的情况。例如如果有API模块请求水果,它会有参数水果指定请求的水果,以及模板参数{水果}-数量以指定每种水果请求多少。需要1个苹果、5个香蕉和20个草莓的API客户端可以做出类似水果=苹果|香蕉|草莓&苹果-数量=1&香蕉-数量=5&草莓-数量=20的请求。
製作群
API 開發人員:
- Roan Kattouw (首席開發者 Sep 2007–2009)
- Victor Vasiliev
- Bryan Tong Minh
- Sam Reed
- Yuri Astrakhan (創立者,首席開發者 Sep 2006–Sep 2007)
- Brad Jorsch (首席開發者 2013–present)
請傳送您的評論、建議以及問題至 [email protected] 或者回報問題至 https://phabricator.wikimedia.org/。