Jump to content

API:Rozšíření

From mediawiki.org
This page is a translated version of the page API:Extensions and the translation is 100% complete.
Languages:
Rozšíření:

Tento dokument popisuje vytvoření modulu API v rozšíření pro použití s MediaWiki 1.30 a novějšími.

Vytvoření a registrace modulu

Všechny moduly API jsou podtřídy ApiBase , ale některé typy modulů používají odvozenou základní třídu. Způsob registrace závisí také na typu modulu.

akční moduly
Moduly, které poskytují hodnotu pro hlavní parametr action, by měly podtřídu ApiBase . Měli by být registrováni v extension.json pomocí klíče APIModules.
moduly formátů
Moduly, které poskytují hodnotu pro hlavní parametr format, by měly mít podtřídu ApiFormatBase. Měly by být registrovány v extension.json pomocí klíče APIFormatModules. Je velmi neobvyklé, že rozšíření potřebuje přidat modul formátu.
dotazovací podmoduly
Moduly, které poskytují hodnotu pro parametry prop, list nebo meta až action=query, by měly podtřídu ApiQueryBase (pokud nejsou použitelné jako generátor) nebo ApiQueryGeneratorBase (pokud jsou použitelné jako generátor). Měly by být registrovány v extension.json pomocí klíče APIPropModules, APIListModules nebo APIMetaModules.

Ve všech případech je hodnotou registračního klíče objekt s názvem modulu (tj. hodnotou parametru) jako klíčem a názvem třídy jako hodnotou. Moduly lze také registrovat podmíněně pomocí háčků ApiMain::moduleManager (pro moduly akcí a formátů) a ApiQuery::moduleManager (pro podmoduly dotazů).

Zavádění

Předpona

V konstruktoru vašeho modulu API můžete při volání parent::__construct() zadat volitelnou předponu pro parametry vašeho modulu. (Ve vygenerované dokumentaci modulu je tato předpona, pokud existuje, uvedena v závorkách v záhlaví modulu.) Pokud je váš modul podmodulem dotazu, je vyžadována předpona, protože klient může vyvolat více podmodulů, z nichž každý má své vlastní parametry v jednom požadavku. U modulů akcí a formátů je předpona volitelná.

Parametry

Většina modulů vyžaduje parametry. Ty jsou definovány implementací getAllowedParams(). Vrácená hodnota je asociativní pole, kde klíče jsou (bez předpony) názvy parametrů a hodnoty jsou buď skalární výchozí hodnota parametru, nebo pole definující vlastnosti parametru pomocí konstant PARAM_* definovaných pomocí ApiBase.

Příklad ilustruje syntaxi a některé běžnější konstanty PARAM_*. 

	protected function getAllowedParams() {
		return [
			// Volitelný parametr s výchozí hodnotou
			'simple' => 'value',

			// Povinný parametr
			'required' => [
				ApiBase::PARAM_TYPE => 'string',
				ApiBase::PARAM_REQUIRED => true,
			],

			// Parametr přijímající více hodnot ze seznamu
			'variable' => [
				// Výchozí sada hodnot
				ApiBase::PARAM_DFLT => 'foo|bar|baz',
				// Všechny možné hodnoty
				ApiBase::PARAM_TYPE => [ 'foo', 'bar', 'baz', 'quux', 'fred', 'blah' ],
				// Označte, že je akceptováno více hodnot
				ApiBase::PARAM_ISMULTI => true,
				// Použijte standardní dokumentační zprávy "pro hodnotu".
				ApiBase::PARAM_HELP_MSG_PER_VALUE => [],
			],

			// Standardní "limitní" parametr. Obecně je nejlepší se od tohoto standardu nelišit.
			'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,
			],
		];
	}

Parametry jsou dokumentovány pomocí mechanismu MediaWiki i18n. Podrobnosti viz #Dokumentace.

Provedení a výstup

Kód ve skutečnosti implementující modul jde metodou execute(). Tento kód bude obecně používat $this→extractRequestParams() k získání vstupních parametrů a použije $this→getResult() k získání objektu ApiResult, do kterého lze přidat jakýkoli výstup.

Podmoduly Query prop by měly používat $this→getPageSet() pro přístup k sadě stránek, na kterých se má pracovat.

Podmoduly dotazů, které lze použít jako generátory, budou také muset implementovat executeGenerator(), který je předán, a ApiPageSet, který by měl být vyplněn vygenerovanými stránkami. V tomto případě by ApiResult neměl být obecně použit.

Ukládání do mezipaměti

Ve výchozím nastavení jsou odpovědi API označeny jako neuložitelné do mezipaměti ('Cache-Control: private')! U akčních modulů můžete povolit ukládání do mezipaměti voláním $this→getMain()→setCacheMode(). To stále vyžaduje, aby klienti předali parametry maxage nebo smaxage, aby skutečně umožnili ukládání do mezipaměti. Ukládání do mezipaměti můžete vynutit také voláním $this→getMain()→setCacheMaxAge().

U modulů dotazů nevolat tyto metody. Ukládání do mezipaměti můžete povolit implementací getCacheMode().

V obou případech se ujistěte, že nejsou vystavena soukromá data.

Manipulace s tokeny

Pokud váš akční modul nějakým způsobem změní wiki, měl by vyžadovat nějaký token. Chcete-li to provést automaticky, implementujte metodu needsToken(), která vrátí token, který váš modul vyžaduje (pravděpodobně 'csrf' token úprav). Základní kód API pak automaticky ověří token, který klienti poskytují v požadavcích API v parametru token.

Pokud nechcete používat token, který je součástí jádra, ale spíše vlastní token s vlastní kontrolou oprávnění, použijte k registraci tokenu háček ApiQueryTokensRegisterTypes .

Přístup k hlavní databázi

Pokud váš modul přistupuje k hlavní databázi, měl by implementovat metodu isWriteMode() pro návrat true.

Vracející se chyby

ApiBase zahrnuje několik metod pro provádění různých kontrol, např.

Často se ale setkáte s případy, kdy potřebujete upozornit na chybu sami. Obvyklý způsob, jak to udělat, je zavolat $this→dieWithError(), ačkoli pokud máte StatusValue s chybovými informacemi, můžete je místo toho předat $this→dieStatus().

Pokud potřebujete místo chyby vydat upozornění, použijte $this→addWarning() nebo $this→addDeprecation(), pokud se jedná o upozornění na ukončení podpory.

Dokumentace

API je zdokumentováno pomocí mechanismu MediaWiki i18n. Potřebné zprávy mají obecně výchozí názvy podle "cesty" modulu. U modulů akcí a formátů je cesta stejná jako název modulu použitý při registraci. U submodulů dotazů je to název s předponou query+.

Každý modul bude potřebovat zprávu apihelp-$path-summary, což by měl být jednořádkový popis modulu. Pokud je potřeba další text nápovědy, může být vytvořen také apihelp-$path-extended-description. Každý parametr bude potřebovat zprávu apihelp-$path-param-$name a parametry používající PARAM_HELP_MSG_PER_VALUE budou také potřebovat apihelp-$path-paramvalue-$name-$value pro každou hodnotu.

Další podrobnosti o dokumentaci API jsou k dispozici na API:Lokalizace .

Rozšíření mohou také dokumentovat své další moduly API na mediawiki.org. Toto by mělo být umístěno na hlavní stránce rozšíření nebo, pokud je potřeba více místa, na stránkách s názvem Extension:<ExtensionName>/API nebo jejich podstránkách (např. CentralAuth , MassMessage nebo StructuredDiscussions ). Jmenný prostor API je vyhrazen pro API jádra MediaWiki.

Rozšíření základních modulů

Od MediaWiki 1.14 je možné rozšířit funkčnost základních modulů pomocí následujících háčků:

Seznam rozšíření s funkcí API

Viz Kategorie:Rozšíření API pro příklady rozšíření, která přidávají nebo rozšiřují API.

Testování vašeho rozšíření

  • Navštivte api.php a přejděte na vygenerovanou nápovědu pro váš modul nebo podmodul dotazu. Informace nápovědy vašeho rozšíření by měly být správné.
    • Vzorové adresy URL, které jste uvedli v getExamplesMessages(), by se měly objevit v části "Příklady", zkuste na ně kliknout.
    • Vynechejte a změňte parametry adresy URL v řetězci dotazu, zkontrolujte odpověď svého rozšíření.
  • Navštivte Special:ApiSandbox a interaktivně prozkoumejte své API.
  • Chcete-li zobrazit další informace o svém rozšíření:
api.php?action=paraminfo&modules=myext [zkuste v ApiSandbox]
Retrieved from "https://www.mediawiki.org/w/index.php?title=API:Extensions/cs&oldid=6653185"