API:扩展
 | 本页是MediaWiki Action API帮助文档的一部份。 |
本文档介绍在扩展中创建API模块，以便与MediaWiki 1.30及更高版本一起使用。
模块的创建与注册
所有API模块都是ApiBase的子类，但某些类型的模块是使用衍生的基类。 注册方法也取决于模块类型。
- 动作模块
- 要提供一個值給主
action参数的這些模块应做一個子类ApiBase。 這些模块应使用APIModules這個鍵在extension.json中注册。 - 格式模块
- 要提供一個值給主
format参数的這些模块应做一個子类ApiFormatBase。 這些模块应使用APIFormatModules這個键在extension.json中注册。 需要添加格式模块到扩展中的情况實屬罕見。 - 查询子模块
- 要提供一個值給
prop、list或meta参数到action=query的這些模块应做一個子类ApiQueryBase(如果作為生成器是沒用的)或ApiQueryGeneratorBase(如果作為生成器是有用的)。 這些模块应在extension.json中使用APIPropModules、APIListModules或APIMetaModules這些键注册。
在所有情况下，注册鍵的值都是一个以模块的名（即参数的值）为键、以类別的名为值的物件。 也有条件地可以使用ApiMain::moduleManager（用于动作和格式模块）和 ApiQuery::moduleManager（用于查询子模块）钩子注册這些模块。
实现
前缀
在API模块的建構子中，当您调用parent::__construct()时，可以指定一个可选用的前缀給模块的那些参数。
(在为模块生成的文档中，如果有前缀，该前缀会出现在模块标题的括号中)。
如果模块是查询子模块，则需要前缀，因为客户端可以在一个请求中调用多个子模块，每个子模块都有自己的参数。
对於于动作和格式模块，其前缀是可选用的。
参数
大多數模組都需要參數。
這些參數都是透過实现getAllowedParams()來定義的。
返回值是一個關聯陣列，其中的鍵是(未加前綴的)參數名，其中的值若不是參數的純量預設值、那就是一個陣列，這個陣列使用由ApiBase所定義的PARAM_*常數來定義參數的各個屬性。
下面的範例說明了語法和一些較常見的PARAM_*常數。
protected function getAllowedParams() {
return [
// 某個具有預設值的可選用的參數
'simple' => 'value',
// 某個必需要有的参数
'required' => [
ApiBase::PARAM_TYPE => 'string',
ApiBase::PARAM_REQUIRED => true,
],
// 某個可從清單中選取多個值的參數
'variable' => [
// 值的預設集
ApiBase::PARAM_DFLT => 'foo|bar|baz',
// 所有可能的值
ApiBase::PARAM_TYPE => [ 'foo', 'bar', 'baz', 'quux', 'fred', 'blah' ],
// 表示可選用多個值
ApiBase::PARAM_ISMULTI => true,
// 使用標準的「per value」文件訊息
ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
],
// 標準的「限制」參數。一般而言，最好是不要違反這個標準。
'limit' => [
ApiBase::PARAM_DFLT => 10,
ApiBase::PARAM_TYPE => 'limit',
ApiBase::PARAM_MIN => 1,
ApiBase::PARAM_MAX => ApiBase::LIMIT_BIG1,
ApiBase::PARAM_MAX2 => ApiBase::LIMIT_BIG2,
],
];
}
參數是使用MediaWiki的i18n機制來記錄。詳情請參閱#Documentation 。
執行與輸出
實際執行模組的程式碼是放在方法execute()之中。 此程式碼一般是使用$this→extractRequestParams()取得輸入參數，且會使用$this→getResult()取得所要加入任何的輸出的ApiResult物件。
用於查詢屬性的子模組應該要使用用來存取所要操作的頁面集的$this→getPageSet()。
可用作產生器的查詢子模組也需要实现被傳送的executeGenerator()、以及應該被產生的頁面所填入的ApiPageSet。
在這種情況下，一般應該「不」使用ApiResult。
缓存
默认情况下，API的响应是被標示為不可缓存的('Cache-Control: private')！
對於動作模組，您可以透過呼叫$this→getMain()→setCacheMode()來允許快取。
這仍然需要客戶端傳遞maxage或smaxage參數才能實際啟用快取。
您也可以透過呼叫$this→getMain()→setCacheMaxAge()來強制快取。
對於查詢模組，「切勿」呼叫這些方法。 您可以改由透過實作getCacheMode()來允許快取。
無論是哪一種情況，都要確保私人資料不會外露。
符記的處理
如果您的操作模組想要以任何方式變更wiki，那它應該會需要某種形式的符記 。
要讓這件事能被自動處理，請實作needsToken()的方法，以便傳回您的模組所需的符記(可能是'csrf'，請參閱編輯符記)。
API基本程式碼就會自動去驗證這個由客戶端在API請求中以參數token所提供的符記。
如果您不想使用某個核心部分的符記，而寧願使用具有您自己權限檢查的自訂符記，請使用ApiQueryTokensRegisterTypes勾點註冊您的符記。
主資料庫存取
如果您的模組會存取主資料庫，那它應該實作isWriteMode()這個方法以便傳回true。
回傳错误
ApiBase包含有多個可以做各式各樣檢查的方法，例如：
- 如果您需要確認是只有提供參數集內的一個參數，請使用$this→requireOnlyOneParameter()。
- 如果您需要確認是最多提供參數集內的一個參數，請使用$this→requireMaxOneParameter()。
如果您需要確認是最多提供參數集內的一個參數，請使用$this→requireAtLeastOneParameter()。
- 如果您需要確認使用者是擁有某些特定的權限，請使用$this→checkUserRightsAny()。
- 如果您需要確認使用者在某個特定的頁面可以採取某個行動，請使用$this→checkTitleUserPermissions()。
- 如果使用者被封鎖 (而且這對您的模組至關重要)，請將物件
Block傳給$this→dieBlocked()。
但您還是會常常遇到需要自己主動提出自己的錯誤的情況。
這個的通常做法是呼叫$this→dieWithError()，雖然您可以將包含有錯誤資訊的StatusValue傳給$this→dieStatus()。
如果您需要發出的是警告而不是錯誤，請使用$this→addWarning()、若是用在某個被取代的警告，請使用$this→addDeprecation()。
帮助文档
API是使用MediaWiki的i18n機制來記錄的。 所需的訊息通常會根據模組的「路徑」做為預設名稱。 對於動作和格式模組，其路徑與註冊時所使用的模組名稱相同。 對於查詢子模組，它是以query+為前綴的名稱。
每個模組都需要一個apihelp-$path-summary訊息，這樣的訊息應該是模組的單行說明。
如果有需要額外的說明文字，你也可以建立apihelp-$path-extended-description。
每個參數都需要一個apihelp-$path-param-$name訊息，而使用PARAM_HELP_MSG_PER_VALUE的參數也需要一個針的每個值的apihelp-$path-paramvalue-$name-$value訊息。
有關API文件的更多詳細資訊，請參閱API:本地化。
某些扩展也可以為其在mediawiki.org上額外的API模組提供文件。
這應該是位於扩展的主頁面上，若是需要更多的空間的話，則應該是位於名為Extension:<ExtensionName>/API的頁面之上或是在其中的子頁面之上（例如，CentralAuth、MassMessage、或StructuredDiscussions）。
命名空間API是保留給MediaWiki核心的API用的。
拓展核心模块
从MediaWiki 1.14开始，可以使用下列钩子拓展核心模块的功能：
- APIGetAllowedParams - 新增或修改模組的參數清單
- APIGetParamDescriptionMessages - 新增或修改模組的參數說明
- APIAfterExecute - 在執行模組之後（但是在輸出結果之前）做某件事
- 針對
prop=、list=、和meta=模組，使用APIQueryAfterExecute- 如果模組是以產生器模式執行，則會改為呼叫APIQueryGeneratorAfterExecute
- 針對
具有API功能的扩展列表
有关添加到API或扩展API的扩展的示例，请参阅分类:API扩展。
测试你的扩展
- 访问api.php并转到为你的模块或查询子模块自动产生的帮助信息。 你的扩展的帮助信息应正确无误。
- 您在
getExamplesMessages()中提供的示例 URL 应出现在「示例」下，请尝试点击它们。 - 在查询字符串中省略或混淆URL参数，检查扩展的响应。
- 您在
- 访问Special:ApiSandbox然後互動式地探索您的API。
- 查看有关你的扩展的其他信息：