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
要執行的動作。
- block
- 封鎖使用者。
- changeauthenticationdata
- 為目前使用者變更身分核對資料。
- changecontentmodel
- 變更頁面的內容模型
- checktoken
- 檢查來自 action=query&meta=tokens 的權杖有效性。
- clearhasmsg
- 清除目前使用者的
hasmsg標記。 - clientlogin
- 使用互動流程來登入 wiki。
- compare
- 比較 2 個頁面間的差異。
- createaccount
- 建立新使用者帳號。
- delete
- 刪除頁面。
- edit
- 建立與編輯頁面。
- emailuser
- 寄送電子郵件給使用者。
- expandtemplates
- 展開所有於 wikitext 中模板。
- feedcontributions
- 回傳使用者貢獻摘要。
- feedrecentchanges
- 返回近期變更摘要。
- feedwatchlist
- 返回監視清單摘要。
- filerevert
- 回退檔案至舊的版本。
- help
- 顯示指定模組的說明。
- imagerotate
- 旋轉一張或多張圖片。
- import
- 從其它 wiki 或 XML 檔案來匯入頁面。
- linkaccount
- 從第三方供應者來連結帳號至目前的使用者。
- login
- 登入並取得身分核對 cookies
- logout
- 登出並清除 session 資料。
- managetags
- 執行相關到更改標籤的管理任務。
- mergehistory
- 合併頁面歷史
- move
- 移動頁面。
- opensearch
- 使用 OpenSearch 協定搜尋本 wiki。
- options
- 更改目前使用者的偏好設定。
- paraminfo
- 獲得有關 API 模組的資訊。
- parse
- 解析內容併回傳解析器輸出。
- patrol
- 巡查頁面或修訂。
- protect
- 變更頁面的保護層級。
- purge
- 為指定標題清除快取。
- query
- 擷取來自及有關MediaWiki的數據。
- removeauthenticationdata
- 為目前使用者移除身分核對資料。
- resetpassword
- 寄送重新設定密碼的電子郵件給使用者。
- revisiondelete
- 刪除和取消刪除修訂。
- rollback
- 復原頁面的最後一次編輯。
- rsd
- 匯出一個簡易探索（Really Simple Discovery、RSD）架構。
- setnotificationtimestamp
- 更新監視頁面的通知時間戳記。
- setpagelanguage
- 更改頁面的語言。
- spamblacklist
- 驗證一個或多個URL是否觸發垃圾連結黑名單。
- tag
- 從各別修訂或日誌項目添加或移除變更標籤。
- titleblacklist
- 檢驗一個頁面的標題、檔案名稱或使用者名稱是否觸發標題黑名單。
- unblock
- 解除封鎖一位使用者。
- undelete
- 恢復已刪除頁面的修訂。
- unlinkaccount
- 移除目前使用者所連結到的第三方帳號。
- upload
- 上傳檔案，或取得等待上傳的狀態。
- userrights
- 變更一位使用者的群組成員。
- validatepassword
- 驗證密碼是否符合 wiki 的密碼方針。
- watch
- 從目前使用者的監視清單添加或移除頁面。
- cspreport
- 內部。由瀏覽器所使用來回報違反內容安全方針。此模組應永不使用，除了是在被由兼容內容安全方針的網路瀏覽器所使用情況下。
- oathvalidate
- 內部。驗證雙因素驗證（OATH）權杖。
- stashedit
- 內部。在分享快取裡預備編輯。
- 單值：block、changeauthenticationdata、changecontentmodel、checktoken、clearhasmsg、clientlogin、compare、createaccount、delete、edit、emailuser、expandtemplates、feedcontributions、feedrecentchanges、feedwatchlist、filerevert、help、imagerotate、import、linkaccount、login、logout、managetags、mergehistory、move、opensearch、options、paraminfo、parse、patrol、protect、purge、query、removeauthenticationdata、resetpassword、revisiondelete、rollback、rsd、setnotificationtimestamp、setpagelanguage、spamblacklist、tag、titleblacklist、unblock、undelete、unlinkaccount、upload、userrights、validatepassword、watch、cspreport、oathvalidate、stashedit
- 預設值：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
- maxage
將HTTP暫存控制頭欄位設為
max-age秒。錯誤不會做暫存。- 類型：整數
- 預設值：0
- assert
若設成 user，會確認使用者是否已登入；若設成 anon，會確認是否沒有登入；若設成 bot，會確認是否為機械人使用者。
- 單值：anon、bot、user
- assertuser
確認目前使用者就是指定的使用者。
- 類型：使用者，按使用者名稱
- 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值，且所有使用者指定資料會受限制。- uselang
訊息翻譯採用的語言。使用 action=query&meta=siteinfo 與 siprop=languages 會回傳語言代碼清單、或指定 user 來使用目前使用者的語言偏好設定、或是指定 content 來使用此 wiki 的內容語言。
- 預設值：user
- 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 命名空間的本地自定義訊息。
- 類型：布林值（詳細資訊）
- 主模組使用說明
- 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–present)
請傳送您的評論、建議以及問題至 [email protected] 或者回報問題至 https://phabricator.wikimedia.org/。