API:Extensions/zh

本文档介绍在扩展中创建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。
• 查看你的扩展的其他信息：

api.php?action=paraminfo&modules=myext [在Api沙盒中尝试]