MediaWiki API 說明
此頁為自動產生的 MediaWiki API 說明文件頁面。
說明文件與範例：https://www.mediawiki.org/wiki/Special:MyLanguage/API:Main_page
一般信息
狀態資訊：MediaWiki API已是成熟、穩定，並積極支援以改善的介面。儘管我們儘可能避免，但仍偶有需要重大變更的情況，請訂閱mediawiki-api-announce郵寄清單以便獲得更新通知。
錯誤的請求：當API收到錯誤的請求，會發出以「MediaWiki-API-Error」為鍵的 HTTP 標頭欄位，隨後標頭欄位的值，以及傳回的錯誤碼會設為相同值。詳細資訊請參閱 API:錯誤與警告。
測試：要簡化 API 請求的測試過程，請見 Special:ApiSandbox。
请求方法
Action API requests may use GET and POST methods. Prefer using the GET method, which allows requests to be routed to faster replica servers and responses to be cached, unless the length of the URL with parameters would exceed its length limit (commonly 8000 bytes), or a module only accepts POST requests.
Parameters for POST requests may be sent in the query part of the request URL (like in GET requests) and in the POST request body, and mixing both ways in one request is allowed. Certain parameters such as passwords must be sent in the request body. If the same parameter is sent as part of the URL and also in the request body, it must have the same value in both places.
資料類型
輸入到 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 能用來指定目前時刻的時間戳記。
限制
Most API modules can accept up to 50 inputs in multivalue parameters, and can return up to 500 results per query (50 results for slow queries).
For users with the apihighlimits right (Gĭ-ké-nè̤nggâe̤ngGuāng-lī-uòng), the limits are increased to 500 inputs and 5,000 results (500 results for slow queries).
模板參數
模板參數可支援當 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
要執行哪個操作。
- 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
- 強行建立本地帳號。中央帳號必須存在。
- cxdelete
- 刪除使用內容翻譯擴充套件所建立的草稿翻譯。
- 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 擴充套件的內部模組。
- chartinfo
- 內部。取得目前圖表頁面使用次數的不重複值。在同一頁面上同一圖表的多次使用僅計算成一次使用。
- cirrus-check-sanity
- 內部。搜尋索引中一段範圍頁面 ID 的正確性報告
- cirrus-config-dump
- 內部。匯出 CirrusSearch 設定。
- cirrus-profiles-dump
- 內部。用於此 wiki 的 CirrusSearch 匯出設定檔。
- cirrus-schema-dump
- 內部。此 wiki 的 CirrusSearch 架構（設定和映射）傾印。
- codemirror-validate
- 內部。檢查給予內容裡的驗證錯誤
- collection
- 內部。用於在 wiki 使用者收藏裡執行各種操作的 API 模組。
- cspreport
- 內部。由瀏覽器所使用來回報違反內容安全方針。此模組應永不使用，除了是在被由兼容內容安全方針的網路瀏覽器所使用情況下。
- cxcheckunreviewed
- 內部。對目前使用者檢查近期是否有發布任何快速、未經審閱的翻譯。
- cxfavoritesuggestions
- 內部。對目前使用者的清單新增或移除收藏建議
- cxpublish
- 內部。儲存使用內容翻譯擴充套件所建立的頁面。
- cxpublishsection
- 內部。儲存使用內容翻譯擴充的章節翻譯功能所建立的章節。
- cxsave
- 內部。此模組允許儲存按章節的草稿翻譯以節省網路頻寬，並收集並聯的語料庫。
- cxsplit
- 內部。為指定條目翻譯的各已翻譯章節，建立章節翻譯並儲存到資料庫
- discussiontoolscompare
- 內部。取得兩個頁面修訂之間關於留言更改的資訊。
- discussiontoolspageinfo
- 內部。回傳詮釋資料需要初始化討論工具。
- discussiontoolspreview
- 內部。在討論頁上預覽訊息。
- echopushsubscriptions
- 內部。管理目前使用者的推送訂閱。
- editcheckreferenceurl
- 內部。Check the status of a URL for use as a reference.
- fancycaptchareload
- 內部。取得新的 FancyCaptcha。
- growthinvalidateimagerecommendation
- 內部。作廢圖片推薦。
- growthinvalidatepersonalizedpraisesuggestion
- 內部。讓導師面板上個性化表揚模組的值得表揚學員建議無效
- growthinvalidaterevisetonerecommendation
- 內部。對特定頁面提出「修改語氣」的建議。
- helppanelquestionposter
- 內部。經由目前使用者的協助面板，來處理發佈的問題。
- jsondata
- 內部。索取在地化 JSON 資料。
- jsontransform
- 內部。檢索由 Lua 函式轉換的 JSON 資料。
- 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
- 內部。有關禁止編輯嘗試的日誌資訊
- wikimediaeventshcaptchaeditattempt
- 內部。當顯示 hCaptcha 挑戰但尚未完成編輯時，記錄編輯差異
- 單值：abusefiltercheckmatch、abusefilterchecksyntax、abusefilterevalexpression、abusefilterunblockautopromote、abuselogprivatedetails、acquiretempusername、antispoof、block、centralauthtoken、centralnoticecdncacheupdatebanner、centralnoticechoicedata、centralnoticequerycampaign、changeauthenticationdata、changecontentmodel、checktoken、clearhasmsg、clientlogin、communityconfigurationedit、compare、createaccount、createlocalaccount、cxdelete、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、chartinfo、cirrus-check-sanity、cirrus-config-dump、cirrus-profiles-dump、cirrus-schema-dump、codemirror-validate、collection、cspreport、cxcheckunreviewed、cxfavoritesuggestions、cxpublish、cxpublishsection、cxsave、cxsplit、discussiontoolscompare、discussiontoolspageinfo、discussiontoolspreview、echopushsubscriptions、editcheckreferenceurl、fancycaptchareload、growthinvalidateimagerecommendation、growthinvalidatepersonalizedpraisesuggestion、growthinvalidaterevisetonerecommendation、helppanelquestionposter、jsondata、jsontransform、parser-migration、readinglists、sanitize-mapdata、scribunto-console、securepollauth、stashedit、sxsave、timedtext、ulslocalization、ulssetlang、visualeditor、visualeditoredit、wikimediaeventsblockededit、wikimediaeventshcaptchaeditattempt
- 預設值：help
- format
輸出的格式。
- 單值：json、jsonfm、none、php、phpfm、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
確認目前使用者就是指定的使用者。
- 類型：使用者，按任何ê̤ṳng-hô-miànggâe̤ng臨時使用者
- requestid
在此處提供的任何值都將包括在響應之中。可用於區分請求。
- servedby
在結果中包括提出請求的主機名。
- 類型：布林值（詳細資訊）
- curtimestamp
在結果中包括目前的時間戳記。
- 類型：布林值（詳細資訊）
- responselanginfo
在結果中包括uselang和errorlang所用的語言。
- 類型：布林值（詳細資訊）
- 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-Origin與Access-Control-Allow-Credentials標頭。對於非認證請求，會指定值 *。這會產生
Access-Control-Allow-Origin標頭有被設定；但Access-Control-Allow-Credentials會是false值，且所有使用者指定資料會受限制。- crossorigin
當使用跨網域 AJAX 請求 (CORS) 存取 API，並且使用能防範跨站請求偽造 (CSRF) 攻擊的會話提供者（例如 OAuth）時，請使用此選項來進行已驗證的請求（即保持登入狀態），而不是使用
origin=*。此參數必須包含在任何預檢請求 (pre-flight request) 中，因此必須作為請求 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 主體）。
On this wiki the expected value is a JSON Web Token, which may be validated by proxy servers in front of MediaWiki. If the token has expired or is otherwise invalid, you may receive a HTTP error from a proxy in a different format than a normal API error.
- 主模組使用說明
- api.php?action=help [在沙盒中開啟]
- 一個頁面中的所有說明。
- api.php?action=help&recursivesubmodules=1&toc [在沙盒中開啟]
製作群
API 開發人員：
- Roan Kattouw (首席開發者 Sep 2007–2009)
- Victor Vasiliev
- Bryan Tong Minh
- Sam Reed
- Yuri Astrakhan (創立者，首席開發者 Sep 2006–Sep 2007)
- Brad Jorsch (首席開發者 2013–2020)
請傳送您的評論、建議以及問題至 mediawiki-api@lists.wikimedia.org 或者回報問題至 https://phabricator.wikimedia.org/。
