MediaWiki

API:扩展

This page is a translated version of the page API:Extensions and the translation is 100% complete.
Languages:
扩展：

本文档介绍在扩展中创建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→requireAtLeastOneParameter()。

但您還是會常常遇到需要自己主動提出自己的錯誤的情況。 這個的通常做法是呼叫$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开始，可以使用下列钩子拓展核心模块的功能：

具有API功能的扩展列表

有关添加到API或扩展API的扩展的示例，请参阅分类:API扩展 。

测试你的扩展

  • 访问api.php并转到为你的模块或查询子模块自动产生的帮助信息。 你的扩展的帮助信息应正确无误。
    • 您在getExamplesMessages()中提供的示例 URL 应出现在「示例」下，请尝试点击它们。
    • 在查询字符串中省略或混淆URL参数，检查扩展的响应。
  • 访问Special:ApiSandbox然後互動式地探索您的API。
  • 查看有关你的扩展的其他信息：
api.php?action=paraminfo&modules=myext [在Api沙盒中尝试]
Retrieved from "https://www.mediawiki.org/w/index.php?title=API:Extensions/zh&oldid=6935674"