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 (機器人和管理員), 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
要執行哪個操作。
- acquiretempusername
- 啟用建立臨時帳號功能且目前使用者已登出時，取得臨時使用者的使用者名稱並將其儲存在目前連線階段中。如果已儲存名稱則回傳相同名稱。
- aggregategroups
- 管理集合訊息群組。
- block
- 封鎖使用者。
- changeauthenticationdata
- 為目前使用者變更身分核對資料。
- changecontentmodel
- 變更頁面的內容模型
- checktoken
- 檢查來自 action=query&meta=tokens 的權杖有效性。
- clearhasmsg
- 清除目前使用者的
hasmsg標記。 - clientlogin
- 使用互動流程來登入 wiki。
- compare
- 比較 2 個頁面間的差異。
- createaccount
- 建立新使用者帳號。
- delete
- 刪除頁面。
- edit
- 建立與編輯頁面。
- emailuser
- 寄送電子郵件給使用者。
- expandtemplates
- 展開所有於 wikitext 中模板。
- feedcontributions
- 回傳使用者貢獻摘要。
- feedrecentchanges
- 返回近期變更摘要。
- feedwatchlist
- 返回監視清單摘要。
- filerevert
- 回退檔案至舊的版本。
- groupreview
- 設定訊息群組的工作流狀態。
- help
- 顯示指定模組的說明。
- imagerotate
- 旋轉一張或多張圖片。
- import
- 從其它 wiki 或 XML 檔案來匯入頁面。
- languagesearch
- 在任何字母裡搜尋語言名稱。
- linkaccount
- 從第三方供應者來連結帳號至目前的使用者。
- login
- 登入並取得身分核對 cookies
- logout
- 登出並清除 session 資料。
- managetags
- 執行相關到更改標籤的管理任務。
- markfortranslation
- Mark a page for translation
- mergehistory
- 合併頁面歷史
- move
- 移動頁面。
- opensearch
- 使用 OpenSearch 協定搜尋本 wiki。
- options
- 更改目前使用者的偏好設定。
- paraminfo
- 獲得有關 API 模組的資訊。
- parse
- 解析內容併回傳解析器輸出。
- patrol
- 巡查頁面或修訂。
- protect
- 變更頁面的保護層級。
- purge
- 為指定標題清除快取。
- query
- 擷取來自及有關MediaWiki的數據。
- removeauthenticationdata
- 為目前使用者移除身分核對資料。
- resetpassword
- 寄送重新設定密碼的電子郵件給使用者。
- revisiondelete
- 刪除和取消刪除修訂。
- rollback
- 復原頁面的最後一次編輯。
- rsd
- 匯出一個簡易探索（Really Simple Discovery、RSD）架構。
- searchtranslations
- 搜尋譯文。
- setnotificationtimestamp
- 更新監視頁面的通知時間戳記。
- setpagelanguage
- 變更頁面的語言。
- tag
- 從各別修訂或日誌項目添加或移除變更標籤。
- translationaids
- 查詢所有譯文協助工具。
- translationreview
- 將譯文標記為已審核。
- translationstats
- 取得翻譯統計
- ttmserver
- 從翻譯記憶查詢建議。
- unblock
- 解除封鎖一位使用者。
- undelete
- 恢復已刪除頁面的修訂。
- unlinkaccount
- 移除目前使用者所連結到的第三方帳號。
- upload
- 上傳檔案，或取得等待上傳的狀態。
- userrights
- 變更一位使用者的群組成員。
- validatepassword
- 驗證密碼是否符合 wiki 的密碼方針。
- watch
- 從目前使用者的監視清單添加或移除頁面。
- categorytree
- 內部。用於 CategoryTree 擴充套件的內部模組。
- cspreport
- 內部。由瀏覽器所使用來回報違反內容安全方針。此模組應永不使用，除了是在被由兼容內容安全方針的網路瀏覽器所使用情況下。
- managegroupsynchronizationcache
- 內部。訊息群組同步快取。
- managemessagegroups
- 內部。在群組匯入期間，以新訊息或是現有訊息重新命名來添加
- messagegroupsubscription
- 內部。Message group subscription related operations
- stashedit
- 內部。在分享快取裡預備編輯。
- translationcheck
- 內部。驗證譯文。
- translationentitysearch
- 內部。搜尋訊息群組與訊息
- ulslocalization
- 內部。取得指定語言的在地化 ULS。
- ulssetlang
- 內部。更新使用者的偏好介面語言。
- 單值：acquiretempusername、aggregategroups、block、changeauthenticationdata、changecontentmodel、checktoken、clearhasmsg、clientlogin、compare、createaccount、delete、edit、emailuser、expandtemplates、feedcontributions、feedrecentchanges、feedwatchlist、filerevert、groupreview、help、imagerotate、import、languagesearch、linkaccount、login、logout、managetags、markfortranslation、mergehistory、move、opensearch、options、paraminfo、parse、patrol、protect、purge、query、removeauthenticationdata、resetpassword、revisiondelete、rollback、rsd、searchtranslations、setnotificationtimestamp、setpagelanguage、tag、translationaids、translationreview、translationstats、ttmserver、unblock、undelete、unlinkaccount、upload、userrights、validatepassword、watch、categorytree、cspreport、managegroupsynchronizationcache、managemessagegroups、messagegroupsubscription、stashedit、translationcheck、translationentitysearch、ulslocalization、ulssetlang
- 預設值：help
- format
輸出的格式。
- 單值：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
確認目前使用者就是指定的使用者。
- 類型：使用者，按任何使用者名稱和臨時使用者
- 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 命名空間的本地自定義訊息。
- 類型：布林值（詳細資訊）
- 主模組使用說明
- 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/。