MediaWiki API 說明
此頁為自動產生的 MediaWiki API 說明文件頁面。
說明文件與範例：https://www.mediawiki.org/wiki/Special:MyLanguage/API:Main_page
主要模組
- 來源：MediaWiki
- 授權條款：GPL-2.0-or-later
狀態資訊：MediaWiki API 已是成熟、穩定，並積極支援以改善的介面。儘管我們儘可能避免，但仍偶有需要重大變更的情況，請訂閱mediawiki-api-announce 郵寄清單以便獲得更新通知。
錯誤的請求：當 API 收到錯誤的請求，會發出以「MediaWiki-API-Error」為鍵的 HTTP 標頭欄位，隨後標頭欄位的值，以及傳回的錯誤碼會設為相同值。詳細資訊請參閱 API: 錯誤與警告。
測試：要簡化 API 請求的測試過程，請見 Special:ApiSandbox。
- action
要執行的動作。
- abusefiltercheckmatch
- 檢查防濫用過濾器是否符合變數集、編輯、或是所記錄的防濫用過濾器事件。
- abusefilterchecksyntax
- 檢查一個防濫用過濾器的語法。
- abusefilterevalexpression
- 評估防濫用過濾器的表達式。
- abusefilterunblockautopromote
- 從由防濫用過濾器結果所接收到的自動調整來解封使用者。
- abuselogprivatedetails
- 檢視 AbuseLog 項目的非公開詳細資料。
- acquiretempusername
- 啟用建立臨時帳號功能且目前使用者已登出時，取得臨時使用者的使用者名稱並將其儲存在目前連線階段中。如果已儲存名稱則回傳相同名稱。
- antispoof
- 檢查使用者名稱是否違反 AntiSpoof 的常態檢查。
- block
- 封鎖使用者。
- centralauthtoken
- 取得中央驗證令牌來對已連結的 wiki 做已授權的請求。
- centralnoticecdncacheupdatebanner
- 在請求橫幅與語言中，為匿名使用者請求清除儲存在 CDN（前端）快取的橫幅內容
- centralnoticechoicedata
- 取得用來在指名專案與語言裡挑選橫幅的資料
- centralnoticequerycampaign
- 取得活動的所有設置設定。
- changeauthenticationdata
- 為目前使用者變更身分核對資料。
- changecontentmodel
- 變更頁面的內容模型
- checktoken
- 檢查來自 action=query&meta=tokens 的權杖有效性。
- cirrus-config-dump
- 匯出 CirrusSearch 設定。
- cirrus-mapping-dump
- 用於此 wiki 的 CirrusSearch 匯出對應。
- cirrus-profiles-dump
- 用於此 wiki 的 CirrusSearch 匯出設定檔。
- cirrus-settings-dump
- 用於此 wiki 的 CirrusSearch 匯出設定。
- clearhasmsg
- 清除目前使用者的
hasmsg標記。 - clientlogin
- 使用互動流程來登入 wiki。
- communityconfigurationedit
- Change the content of a configuration provider in Community configuration
- compare
- 比較 2 個頁面間的差異。
- createaccount
- 建立新使用者帳號。
- createlocalaccount
- 強行建立本地帳號。中央帳號必須存在。
- cxdelete
- 刪除使用內容翻譯擴充套件所建立的草稿翻譯。
- cxsuggestionlist
- 管理建議清單。可做出添加建議至清單裡以及從清單裡移除。
- cxtoken
- 以 cxserver 取得 JWT 令牌來驗證。
- delete
- 刪除頁面。
- deleteglobalaccount
- 刪除一位全域使用者。
- discussiontoolsedit
- 於討論頁發布留言。
- discussiontoolsfindcomment
- 按 ID 或名稱查找留言。
- discussiontoolsgetsubscriptions
- 取得指定話題的訂閱狀態。
- discussiontoolssubscribe
- 訂閱（或取消訂閱）來接收有關話題的通知。
- discussiontoolsthank
- 傳送對留言的公開感謝通知。
- echocreateevent
- 手動觸發給使用者的通知
- echomarkread
- 把目前使用者的通知標記為已讀。
- echomarkseen
- 把目前使用者的通知標記為已看過
- echomute
- 取消或是恢復來自某些使用者或頁面的通知。
- edit
- 建立與編輯頁面。
- editmassmessagelist
- 編輯大量訊息傳遞清單。
- emailuser
- 寄送電子郵件給使用者。
- expandtemplates
- 展開所有於 wikitext 中模板。
- featuredfeed
- 回傳特色內容摘要。
- feedcontributions
- 回傳使用者貢獻摘要。
- feedrecentchanges
- 返回近期變更摘要。
- feedwatchlist
- 返回監視清單摘要。
- filerevert
- 回退檔案至舊的版本。
- globalblock
- 全域封鎖或解封一名使用者。
- globalpreferenceoverrides
- 替目前使用者的全域偏好設定變更本地覆蓋內容。
- globalpreferences
- 更改當前使用者的全域偏好設定。
- globaluserrights
- 加入/移除一位使用者至/從全域群組。
- growthmanagementorlist
- 管理在結構化導師清單中的資訊（通常存放在 MediaWiki:GrowthMentors.json 中）。此模組可被目前與往後的導師（新增他們自己或是變更他們的詳細資訊）以及管理員（適用於所有使用者）來使用。
- growthmentordashboardupdatedata
- 安排導師控制面版中學員總覽的特別更新。由於性能原因您每兩個小時只能安排一次更新。
- growthsetmenteestatus
- 設定學員的狀態（允許學員啟用/停用導師計畫模組或完全退出以刪除學員和導師的關係）
- growthsetmentor
- 設定使用者的導師。變更會公開記錄。
- growthstarmentee
- 由目前使用者將學員標記或取消標記星號（私密存儲且不記錄）
- help
- 顯示指定模組的說明。
- homepagequestionstore
- 取得透過首頁模組所發佈的格式化問題
- imagerotate
- 已停用此模組。
- import
- 從其它 wiki 或 XML 檔案來匯入頁面。
- jsonconfig
- 允許直接存取 JsonConfig 子系統。
- languagesearch
- 在任何字母裡搜尋語言名稱。
- linkaccount
- 從第三方供應者來連結帳號至目前的使用者。
- login
- 登入並取得身分核對 cookies
- logout
- 登出並清除 session 資料。
- managetags
- 執行相關到更改標籤的管理任務。
- massmessage
- 向頁面清單傳送訊息。
- mergehistory
- 合併頁面歷史
- move
- 移動頁面。
- opensearch
- 使用 OpenSearch 協定搜尋本 wiki。
- options
- 更改目前使用者的偏好設定。
- paraminfo
- 獲得有關 API 模組的資訊。
- parse
- 解析內容併回傳解析器輸出。
- patrol
- 巡查頁面或修訂。
- protect
- 變更頁面的保護層級。
- purge
- 為指定標題清除快取。
- query
- 擷取來自及有關MediaWiki的數據。
- removeauthenticationdata
- 為目前使用者移除身分核對資料。
- resetpassword
- 寄送重新設定密碼的電子郵件給使用者。
- revisiondelete
- 刪除和取消刪除修訂。
- rollback
- 復原頁面的最後一次編輯。
- rsd
- 匯出一個簡易探索（Really Simple Discovery、RSD）架構。
- setglobalaccountstatus
- 隱藏/鎖定（以及解除隱藏/鎖定）全域使用者帳號。
- setnotificationtimestamp
- 更新監視頁面的通知時間戳記。
- setpagelanguage
- 變更頁面的語言。
- shortenurl
- 將長的 URL 給縮短。
- sitematrix
- 取得維基媒體網站清單。
- spamblacklist
- 驗證一個或多個URL是否觸發垃圾連結黑名單。
- streamconfigs
- 公開事件串流設置。僅回傳帶有 formatversion=2 的 format=json 。
- strikevote
- 允許管理員作廢或取消作廢投票。
- sxdelete
- 從資料庫中刪除草稿章節翻譯以及其平行語料。
- tag
- 從各別修訂或日誌項目添加或移除變更標籤。
- templatedata
- 取得由 TemplateData 擴充套件儲存的資料。
- thank
- 向一名編輯者傳送感謝通知。
- titleblacklist
- 檢驗一個頁面的標題、檔案名稱或使用者名稱是否觸發標題黑名單。
- torblock
- 檢查 IP 位址是否被禁止作為 Tor 出口節點。
- transcodereset
- 具「transcode-reset」權限的使用者可以重新設定和重新執行轉碼任務。
- unblock
- 解除封鎖一位使用者。
- undelete
- 恢復已刪除頁面的修訂。
- unlinkaccount
- 移除目前使用者所連結到的第三方帳號。
- upload
- 上傳檔案，或取得等待上傳的狀態。
- userrights
- 變更一位使用者的群組成員。
- validatepassword
- 驗證密碼是否符合 wiki 的密碼方針。
- watch
- 從目前使用者的監視清單添加或移除頁面。
- webapp-manifest
- 回傳 webapp manifest。
- webauthn
- 在註冊/驗證程序期間，用來溝通伺服器與客戶端兩方的API模組。
- bouncehandler
- 內部。接收退回的電子郵件並以受領失敗來處理。
- categorytree
- 內部。用於 CategoryTree 擴充套件的內部模組。
- cirrus-check-sanity
- 內部。搜尋索引中一段範圍頁面 ID 的正確性報告
- cspreport
- 內部。由瀏覽器所使用來回報違反內容安全方針。此模組應永不使用，除了是在被由兼容內容安全方針的網路瀏覽器所使用情況下。
- cxcheckunreviewed
- 內部。對目前使用者檢查近期是否有發布任何快速、未經審閱的翻譯。
- cxpublish
- 內部。儲存使用內容翻譯擴充套件所建立的頁面。
- cxpublishsection
- 內部。儲存使用內容翻譯擴充的章節翻譯功能所建立的章節。
- cxsave
- 內部。此模組允許儲存按章節的草稿翻譯以節省網路頻寬，並收集並聯的語料庫。
- cxsplit
- 內部。為指定條目翻譯的各已翻譯章節，建立章節翻譯並儲存到資料庫
- discussiontoolscompare
- 內部。取得兩個頁面修訂之間關於留言更改的資訊。
- discussiontoolspageinfo
- 內部。回傳詮釋資料需要初始化討論工具。
- discussiontoolspreview
- 內部。在討論頁上預覽訊息。
- echopushsubscriptions
- 內部。管理目前使用者的推送訂閱。
- editcheckreferenceurl
- 內部。Check the status of a URL for use as a reference.
- fancycaptchareload
- 內部。取得新的 FancyCaptcha。
- growthinvalidateimagerecommendation
- 內部。作廢圖片推薦。
- growthinvalidatepersonalizedpraisesuggestion
- 內部。讓導師面板上個性化表揚模組的值得表揚學員建議無效
- helppanelquestionposter
- 內部。經由目前使用者的協助面板，來處理發佈的問題。
- jsondata
- 內部。索取在地化 JSON 資料。
- oathvalidate
- 內部。驗證雙因素驗證（OATH）權杖。
- parser-migration
- 內部。使用兩種不同的解析器組態解析頁面。
- readinglists
- 內部。閱讀清單寫入操作。
- sanitize-mapdata
- 內部。替 Kartographer 擴充功能執行資料驗證
- scribunto-console
- 內部。來自 Scribunto 主控台用於服務 XHR 請求的內部模組。
- securepollauth
- 內部。允許遠端 wiki 在授予選舉投票權限之前，對使用者進行驗證。
- stashedit
- 內部。在分享快取裡預備編輯。
- sxsave
- 內部。保存草稿章節翻譯，並存儲平行語料庫
- timedtext
- 內部。提供由 <track> 元素使用的字幕內容
- ulslocalization
- 內部。取得指定語言的在地化 ULS。
- ulssetlang
- 內部。更新使用者的偏好介面語言。
- visualeditor
- 內部。從 Parsoid 服務回傳一個頁面的 HTML5。
- visualeditoredit
- 內部。儲存一個 HTML5 頁面至 MediaWiki (透過 Parsoid 服務轉換爲 WikiText)。
- wikimediaeventsblockededit
- 內部。有關禁止編輯嘗試的日誌資訊
- 單值：abusefiltercheckmatch, abusefilterchecksyntax, abusefilterevalexpression, abusefilterunblockautopromote, abuselogprivatedetails, acquiretempusername, antispoof, block, centralauthtoken, centralnoticecdncacheupdatebanner, centralnoticechoicedata, centralnoticequerycampaign, changeauthenticationdata, changecontentmodel, checktoken, cirrus-config-dump, cirrus-mapping-dump, cirrus-profiles-dump, cirrus-settings-dump, clearhasmsg, clientlogin, communityconfigurationedit, compare, createaccount, createlocalaccount, cxdelete, cxsuggestionlist, cxtoken, delete, deleteglobalaccount, discussiontoolsedit, discussiontoolsfindcomment, discussiontoolsgetsubscriptions, discussiontoolssubscribe, discussiontoolsthank, echocreateevent, echomarkread, echomarkseen, echomute, edit, editmassmessagelist, emailuser, expandtemplates, featuredfeed, feedcontributions, feedrecentchanges, feedwatchlist, filerevert, globalblock, globalpreferenceoverrides, globalpreferences, globaluserrights, growthmanagementorlist, growthmentordashboardupdatedata, growthsetmenteestatus, growthsetmentor, growthstarmentee, help, homepagequestionstore, 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, sxdelete, tag, templatedata, thank, titleblacklist, torblock, transcodereset, unblock, undelete, unlinkaccount, upload, userrights, validatepassword, watch, webapp-manifest, webauthn, bouncehandler, categorytree, cirrus-check-sanity, cspreport, cxcheckunreviewed, cxpublish, cxpublishsection, cxsave, cxsplit, discussiontoolscompare, discussiontoolspageinfo, discussiontoolspreview, echopushsubscriptions, editcheckreferenceurl, fancycaptchareload, growthinvalidateimagerecommendation, growthinvalidatepersonalizedpraisesuggestion, helppanelquestionposter, jsondata, oathvalidate, parser-migration, readinglists, sanitize-mapdata, scribunto-console, securepollauth, stashedit, sxsave, timedtext, ulslocalization, ulssetlang, visualeditor, visualeditoredit, wikimediaeventsblockededit
- 預設值：help
- format
輸出的格式。
- 單值：json, jsonfm, none, php, phpfm, rawfm, xml, xmlfm
- 預設值：jsonfm
- maxlag
最大延遲可在當 MediaWiki 安裝於資料庫複寫叢集時使用。為了保存引起更多站台複寫延遲的操作，此參數可讓客戶端等待至複寫延遲小於指定值為止。在過渡延遲的情況下，錯誤碼 maxlag 會帶有著像是 Waiting for $host: $lag seconds lagged 的訊息內容回傳。
請查看手冊：Maxlag 參數來獲取更多資訊。- 類型：整數
- smaxage
將HTTP暫存控制頭欄位設為
s-maxage秒。錯誤不會做暫存。- 類型：整數
- 數值不可小於 0。
- 預設值：0
- maxage
將HTTP暫存控制頭欄位設為
max-age秒。錯誤不會做暫存。- 類型：整數
- 數值不可小於 0。
- 預設值：0
- assert
如果設定為user，則驗證使用者是否已登入（包括以臨時使用者身分登入）；如果設定為anon，則驗證使用者是否未登入；如果設定為bot，則驗證使用者是否擁有機器人使用者權限。
- 單值：anon, bot, user
- assertuser
確認目前使用者就是指定的使用者。
- 類型：使用者，按任何用者名kap臨時使用者
- requestid
在此處提供的任何值都將包括在響應之中。可用於區分請求。
- servedby
在結果中包括提出請求的主機名。
- 類型：布林值（詳細資訊）
- curtimestamp
在結果中包括目前的時間戳記。
- 類型：布林值（詳細資訊）
- responselanginfo
在結果中包括uselang和errorlang所用的語言。
- 類型：布林值（詳細資訊）
- origin
當使用跨網域 AJAX 請求（cross-domain AJAX request、CORS）來存取 API 時，設定此為起始網域。這必須包含在任何預檢請求裡，因此得是請求 URI 的一部份（不是 POST 主體）。
對於已認證請求，這必須準確地符合在
Origin標頭裡其一的起始點，因此會被設定成像是 https://meta.wikimedia.org。如果此參數不符合Origin標頭，會回傳 403 錯誤回應。若此參數符合Origin標頭且起始點被列為允許，將會設定Access-Control-Allow-Origin與Access-Control-Allow-Credentials標頭。對於非認證請求，會指定值 *。這會產生
Access-Control-Allow-Origin標頭有被設定；但Access-Control-Allow-Credentials會是false值，且所有使用者指定資料會受限制。- crossorigin
使用跨域AJAX请求(CORS)访问API时，如果使用的是可以抵御跨站点请求伪造(CSRF)攻击的会话提供程序（例如OAuth），则请使用此参数而非
origin=*以保持请求处于已通过身份验证的状态（即不是已退出未登录的状态）。此参数必须包含在任何预检请求中，因此必须是请求URI（而不是POST正文）的一部分。请注意，大多数会话提供程序（包括标准的基于cookie的会话）不支持经过身份验证的CORS，因此不能使用此参数。
- 類型：布林值（詳細資訊）
- uselang
訊息翻譯採用的語言。使用 action=query&meta=siteinfo&siprop=languages 會回傳語言代碼清單。您可以指定 user 來使用目前使用者的語言偏好設定，或是指定 content 來使用此 wiki 的內容語言。
- 預設值：user
- variant
語言變種。僅當基礎語言支持變種轉換時起作用。
- errorformat
用於警告和錯誤文字輸出的格式
- plaintext
- 包括HTML標籤的wikitext被移除並且實體被替換。
- wikitext
- 未解析的 wikitext。
- html
- HTML
- raw
- 訊息鍵與參數。
- none
- 沒有文字輸出，僅有錯誤代碼。
- bc
- MediaWiki 1.29 之前使用的格式。會忽略 errorlang 與 errorsuselocal。
- 單值：bc, html, none, plaintext, raw, wikitext
- 預設值：bc
- errorlang
警告與錯誤採用的語言。使用 action=query&meta=siteinfo&siprop=languages 會回傳語言代碼清單。指定 content 可以使用此 wiki 的內容語言，或是指定 uselang 來使用與 uselang 參數相同的值。
- 預設值：uselang
- errorsuselocal
若有指定，錯誤文字會使用來自 MediaWiki 命名空間的本地自定義訊息。
- 類型：布林值（詳細資訊）
- centralauthtoken
當使用跨網域 AJAX 請求（cross-domain AJAX request、CORS）來存取 API 時，使用此來認證目前的 SUL 使用者。在建立 CORS 請求前，於此 wiki 使用 action=centralauthtoken 來索取權杖。任一令牌每次只可使用一次，並且會在 10 秒後逾期。此僅可包含在任何預先請求，並也應該包含所請求的 URI 裡（而不是 POST 主體）。
- 主模組使用說明
- api.php?action=help [在沙盒中開啟]
- 一個頁面中的所有說明。
- api.php?action=help&recursivesubmodules=1 [在沙盒中開啟]
資料類型
輸入到 MediaWiki 應為 NFC-標準化的 UTF-8。雖然 MediaWiki 會嘗試轉換成其它輸入，但這可能會引發一些操作上錯誤（例如像以 MD5 核對的編輯）。
帶有多項值的參數通常是以豎線字元做區分來提交，例如：param=value1|value2 或是 param=value1%7Cvalue2。如果值的內容必須包含豎線字元，請使用 U+001F（單位分隔）來做為區分，並且讓值的字首加上 U+001F，例如：param=%1Fvalue1%1Fvalue2。
在 API 請求中的某些參數需要進一步解釋：
- boolean
布林值參數運作上就像 HTML 的勾選框：若有指定參數，不論值的內容為何都視為 true。對於 false 值，則是將參數整個省略。
- expiry
到期時間可以是相對時間（例如：5 months 或 2 weeks）或是絕對時間（例如：2014-09-18T12:34:56Z）。如果要無期限，請使用 infinite、indefinite、infinity、或 never。
- timestamp
時間戳記能以數種格式指定，請查看在 mediawiki.org 上的時間戳記函式庫輸入格式文件來獲得更多資訊。推薦採用 ISO 8601 日期與時間格式：2001-01-15T14:56:00Z。另外，字串 now 能用來指定目前時刻的時間戳記。
模板參數
模板參數可支援當 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–2020)
請傳送您的評論、建議以及問題至 [email protected] 或者回報問題至 https://phabricator.wikimedia.org/。