MediaWiki API 說明

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

一般資訊

狀態：MediaWiki API是成熟且穩定的介面，並持續獲得支援與改進。雖然我們會盡量避免，但偶爾仍可能需要進行不相容變更；若要接收更新通知，請訂閱mediawiki-api-announce郵寄清單。

有誤的請求：向API傳送有誤的請求時，回應中會包含名稱為「MediaWiki-API-Error」的HTTP標頭，其值與回傳的錯誤代碼會設為相同值。詳細資訊請參閱 API:錯誤與警告。

測試：為方便測試API請求，請參閱Special:ApiSandbox。

請求方法

Action API請求可使用GET或POST方法。除非加入參數後的URL會超過長度限制（通常為8000位元組），或模組僅接受POST請求，否則建議優先使用GET。使用GET時，系統可將請求導向速度較快的副本伺服器，並對回應進行快取。

POST請求的參數可以放在請求URL的查詢部分中（與GET請求相同），也可以放在POST請求主體中；同一個請求可以同時使用這兩種方式。某些參數（例如密碼）必須放在請求主體中。若同一參數同時出現在URL與請求主體中，兩處的值必須相同。

資料類型

輸入到 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上的Timestamp函式庫輸入格式說明。建議使用ISO 8601日期與時間格式：2001-01-15T14:56:00Z。若要指定目前時間，可使用字串now。

限制

大多數API模組的多值參數最多可接受50個輸入值，每次查詢最多可回傳500個結果；慢速查詢則最多可回傳50個結果。

具有apihighlimits權限的使用者（機器人 kap管理員），上限會提高至500個輸入值和5,000個結果；慢速查詢則為500個結果。

模板參數

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

主要模組

來源：MediaWiki
授權條款：GPL-2.0-or-later

Specify the action to perform, the format of the response, and options that apply to all API modules.

具體參數：

action

要執行的操作。為了方便測試、分析以及請求路由或過濾，此參數應作為請求URL的一部分發送（而不是POST請求主體）。

abusefiltercheckmatch: 檢查防濫用過濾器是否符合變數集、編輯、或是所記錄的防濫用過濾器事件。
abusefilterchecksyntax: 檢查一個防濫用過濾器的語法。
abusefilterevalexpression: 評估防濫用過濾器的表達式。
abusefilterunblockautopromote: 從由防濫用過濾器結果所接收到的自動調整來解封使用者。
abuselogprivatedetails: 檢視 AbuseLog 項目的非公開詳細資料。
acquiretempusername: 啟用建立臨時帳號功能且目前使用者已登出時，取得臨時使用者的使用者名稱並將其儲存在目前連線階段中。如果已儲存名稱則回傳相同名稱。
antispoof: 檢查使用者名稱是否違反 AntiSpoof 的常態檢查。
block: 封鎖使用者。
centralauthtoken: 取得中央驗證令牌來對已連結的 wiki 做已授權的請求。
centralnoticecdncacheupdatebanner: 在請求橫幅與語言中，為匿名使用者請求清除儲存在 CDN（前端）快取的橫幅內容
centralnoticechoicedata: 取得用來在指名專案與語言裡挑選橫幅的資料
centralnoticequerycampaign: 取得活動的所有設置設定。
changeauthenticationdata: 為目前使用者變更身分核對資料。
changecontentmodel: 變更頁面的內容模型
checktoken: 檢查來自 action=query&meta=tokens 的權杖有效性。
clearhasmsg: 清除目前使用者的 hasmsg 標記。
clientlogin: 使用互動流程來登入 wiki。
communityconfigurationedit: Change the content of a configuration provider in Community configuration
compare: 比較 2 個頁面間的差異。
createaccount: 建立新使用者帳號。
createlocalaccount: 強行建立本地帳號。中央帳號必須存在。
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: 加入/移除一位使用者至/從全域群組。
help: 顯示指定模組的說明。
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: 允許管理員作廢或取消作廢投票。
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模組。
wikifunctions_run: 运行函数调用
wikilambda_fetch: 取得 ZObjects 的 JSON 模組。
abstractwiki_fetch_section: 內部。Request the currently available Abstract Wikipedia rendered fragments for the given topic Qid (Wikidata Item Id), section Qid, language Zid and date. Alternatively (and only with special rights), request the currently available rendered output of an array of fragments passed in the request, which can be different from the currently persisted version.

This request is never blocking. When any of the requested fragments is not ready, the returned value for that fragment will have a "pending" flag set to true.

The response is always guaranteed to return as many results as requested. For example, if the "fragments" param is empty and the requested section has N fragments, all N will be returned; similarly, if M fragments are requested in the "fragments" parameter, the respond will return M items.

abstractwiki_run_fragment: 內部。Render an Abstract Wikipedia content fragment for the given Wikidata Item Id, language Zid and date
bouncehandler: 內部。接收退回的電子郵件並以受領失敗來處理。
categorytree: 內部。用於 CategoryTree 擴充套件的內部模組。
chartinfo: 內部。取得目前圖表頁面使用次數的不重複值。在同一頁面上同一圖表的多次使用僅計算成一次使用。
cirrus-check-sanity: 內部。搜尋索引中一段範圍頁面 ID 的正確性報告
cirrus-config-dump: 內部。匯出 CirrusSearch 設定。
cirrus-profiles-dump: 內部。用於此 wiki 的 CirrusSearch 匯出設定檔。
cirrus-schema-dump: 內部。此 wiki 的 CirrusSearch 架構（設定和映射）傾印。
codemirror-validate: 內部。檢查給予內容裡的驗證錯誤
cspreport: 內部。由瀏覽器所使用來回報違反內容安全方針。此模組應永不使用，除了是在被由兼容內容安全方針的網路瀏覽器所使用情況下。
discussiontoolscompare: 內部。取得兩個頁面修訂之間關於留言更改的資訊。
discussiontoolspageinfo: 內部。回傳詮釋資料需要初始化討論工具。
discussiontoolspreview: 內部。在討論頁上預覽訊息。
editcheckreferenceurl: 內部。Check the status of a URL for use as a reference.
fancycaptchareload: 內部。取得新的 FancyCaptcha。
jsondata: 內部。索取在地化 JSON 資料。
jsontransform: 內部。檢索由 Lua 函式轉換的 JSON 資料。
parser-migration: 內部。使用兩種不同的解析器組態解析頁面。
readinglists: 內部。閱讀清單寫入操作。
sanitize-mapdata: 內部。替 Kartographer 擴充功能執行資料驗證
scribunto-console: 內部。來自 Scribunto 主控台用於服務 XHR 請求的內部模組。
securepollauth: 內部。允許遠端 wiki 在授予選舉投票權限之前，對使用者進行驗證。
stashedit: 內部。在分享快取裡預備編輯。
timedtext: 內部。提供由 <track> 元素使用的字幕內容
ulslocalization: 內部。取得指定語言的在地化 ULS。
ulssetlang: 內部。更新使用者的偏好介面語言。
visualeditor: 內部。從 Parsoid 服務回傳一個頁面的 HTML5。
visualeditoredit: 內部。儲存一個 HTML5 頁面至 MediaWiki (透過 Parsoid 服務轉換爲 WikiText)。
wikifunctions_html_sanitiser: 內部。API to sanitise a string of HTML for user-facing display on Wikifunctions.org and client Wikimedia wikis.
wikilambda_edit: 內部。建立或編輯 ZObject。
wikilambda_function_call: 內部。Invoke a function by calling the function-orchestrator
wikilambda_perform_test: 內部。Endpoint to query test results for a ZFunction. Accepts a ZFunction, a list of ZImplementations, and a list of ZTesters. Accepts either a list of ZIDs or the full ZObject for the function, implementations, or testers. Also accepts a key to utilize a back end cache or not.
wikilambda_supported_programming_languages: 內部。Retrieve the programming languages supported by the evaluator
wikimediaeventsblockededit: 內部。有關禁止編輯嘗試的日誌資訊
wikimediaeventshcaptchaeditattempt: 內部。當顯示 hCaptcha 挑戰但尚未完成編輯時，記錄編輯差異

單值：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、wikifunctions_run、wikilambda_fetch、abstractwiki_fetch_section、abstractwiki_run_fragment、bouncehandler、categorytree、chartinfo、cirrus-check-sanity、cirrus-config-dump、cirrus-profiles-dump、cirrus-schema-dump、codemirror-validate、cspreport、discussiontoolscompare、discussiontoolspageinfo、discussiontoolspreview、editcheckreferenceurl、fancycaptchareload、jsondata、jsontransform、parser-migration、readinglists、sanitize-mapdata、scribunto-console、securepollauth、stashedit、timedtext、ulslocalization、ulssetlang、visualeditor、visualeditoredit、wikifunctions_html_sanitiser、wikilambda_edit、wikilambda_function_call、wikilambda_perform_test、wikilambda_supported_programming_languages、wikimediaeventsblockededit、wikimediaeventshcaptchaeditattempt

預設值：help

format

輸出的格式。

json: 使用 JSON 格式輸出資料。
jsonfm: 使用 JSON 格式輸出資料（使用HTML格式顯示）。
none: 不輸出。
rawfm: 使用 JSON 格式的除錯元素輸出資料 (使用 HTML 格式顯示)。
xml: 使用 XML 格式輸出資料。
xmlfm: 使用 XML 格式輸出資料 (使用 HTML 格式顯示)。

單值：json、jsonfm、none、rawfm、xml、xmlfm

預設值：jsonfm

maxlag

當MediaWiki安裝於資料庫複製叢集時，可使用最大延遲。為避免任何可能導致網站複製延遲的action，此參數可讓用戶端等待，直至複製叢集的延遲小於某個指定值為止。在延遲過久的情況下，會回傳錯誤碼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請求（CORS）存取API時，請將此參數設為發出請求的來源。預檢請求也必須包含此參數，因此請將它放在請求URL中，而不要放在POST主體內。

對於已驗證身分的請求，此參數必須與Origin標頭中的來源完全相符，例如https://en.wikipedia.org或https://meta.wikimedia.org。如果此參數與Origin標頭不符，伺服器會回傳403回應。如果兩者相符，且該來源獲允許，伺服器便會設定Access-Control-Allow-Origin與Access-Control-Allow-Credentials標頭。

對於未驗證身分的請求，請將此參數設為*。如此會設定Access-Control-Allow-Origin標頭，但Access-Control-Allow-Credentials會設為false，並限制存取所有使用者特定資料。

crossorigin

使用跨來源AJAX請求（CORS）存取API時，如果採用能防範跨站請求偽造（CSRF）攻擊的工作階段提供者（例如 OAuth），請使用此參數取代origin=*，讓請求保有登入身分。預檢請求也必須包含此參數，因此請將它放在請求URL中，而不要放在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請求"（CORS）來存取API時，使用此來認證目前的SUL使用者。在建立CORS請求前，於此wiki使用 action=centralauthtoken 來索取權杖。任一權杖每次只可使用一次，並且會在60秒後逾期。此僅可包含在任何預先請求，並也應該包含所請求的URI裡（而不是POST主體）。

此wiki的预期值为JSON Web令牌，该令牌可由位于MediaWiki之前的代理服务器验证。如果令牌已过期或无效，您会从代理收到HTTP错误，其格式与通常的API错误不同。

範例：

主模組使用說明: api.php?action=help [在沙盒中開啟]
一個頁面中的所有說明。: api.php?action=help&recursivesubmodules=1&toc [在沙盒中開啟]

製作群

API 開發人員：

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

請將您的評論、建議、問題發送至mediawiki-api@lists.wikimedia.org 或者在https://phabricator.wikimedia.org/ 提交錯誤報告。