API:Etiketa
| Tato stránka je součástí dokumentace k API Action MediaWiki. |
Tato stránka ve zkratce:
|
Tato stránka obsahuje osvědčené postupy, které je třeba dodržovat při používání rozhraní API. Viz také oficiální pokyny pro použití API na wiki Wikimedia Foundation Governance.
Chování
Limit požadavku
Neexistuje žádný pevný rychlostní limit pro požadavky na čtení, ale buďte ohleduplní a snažte se web nezrušit. Většina systémových administrátorů si vyhrazuje právo vás bez okolků zablokovat, pokud ohrozíte stabilitu jejich stránek.
Vytváření požadavků v sérii, nikoli paralelně, čekáním na dokončení jednoho požadavku před odesláním nového požadavku, by mělo vést k bezpečnému počtu požadavků. Také se doporučuje, abyste požádali o více položek v jedné žádosti:
- Kdykoli je to možné, použijte svislítko (
|), např.titles=PageA|PageB|PageC, místo toho, abyste pro každý titul zadali novou žádost. - Použití generátoru místo požadavku na každý výsledek z jiného požadavku.
- Použijte kompresi GZip při volání API nastavením
Accept-Encoding: gzippro snížení využití šířky pásma.
Požadavky, které provádějí úpravy, mění stav nebo jinak, nejsou požadavky pouze pro čtení a podléhají omezení rychlosti. Přesný limit sazby může záviset na typu akce, vašich uživatelských právech a konfiguraci webové stránky, na kterou zadáváte požadavek. Limity, které se na vás vztahují, lze určit přístupem ke koncovému bodu API action=query&meta=userinfo&uiprop=ratelimits.
Když dosáhnete limitu počtu požadavků, obdržíte chybovou odpověď API s kódem chyby ratelimited. Když narazíte na tuto chybu, můžete požadavek opakovat, měli byste však prodloužit dobu mezi následujícími požadavky. Běžnou strategií je Exponenciální ústup.
Analýza revizí
I když je možné dotazovat se na výsledky z konkrétního čísla revize pomocí parametru revid, je to pro servery nákladná operace.
Chcete-li získat konkrétní revizi, použijte parametr oldid. Například:
Parametr maxlag
Pokud vaše úloha není interaktivní, tj. uživatel nečeká na výsledek, měli byste použít parametr maxlag.
Hodnota parametru maxlag by měla být celé číslo v sekundách.
Například:
Tím zabráníte spuštění úlohy, když je zatížení serverů vysoké. Vyšší hodnoty znamenají agresivnější chování, nižší hodnoty jsou hezčí.
Další podrobnosti najdete na stránce Manual:Maxlag parameter.
Záhlaví User-Agent
Nejlepší je nastavit popisné záhlaví User Agent.
K tomu použijte User-Agent: clientname/version (kontaktní informace, např. uživatelské jméno, email) framework/version....
Například v PHP:
ini_set('user_agent', 'MyCoolTool/1.1 (https://example.org/MyCoolTool/; MyCoolTool@example.org) UsedBaseLibrary/1.4');
Nekopírujte jednoduše user-agent oblíbeného webového prohlížeče. To zajišťuje, že pokud se problém objeví, je snadné vysledovat, kde vznikl.
Pokud voláte API z JavaScriptu založeného na prohlížeči, možná nebudete moci ovlivnit hlavičku User-Agent, v závislosti na prohlížeči.
Chcete-li to obejít, použijte hlavičku Api-User-Agent.
Další podrobnosti naleznete v m:User-Agent_policy.
Formáty dat
Všichni noví uživatelé rozhraní API by měli používat JSON. Další podrobnosti viz API:Data_formats.
Výkon
Hromadné stahování dat není pomocí Action API vždy extrémně efektivní. Na wikinách Wikimedie existují rychlejší způsoby, jak získat data hromadně, viz m:Research:Data a wikitech:Portal:Data Services pro více podrobností.
Další poznámky
Pokud vaše požadavky získají data, která lze na chvíli uložit do mezipaměti, měli byste podniknout kroky k jejich uložení do mezipaměti, abyste nepožadovali stejná data znovu a znovu. Někteří klienti mohou být schopni ukládat data do mezipaměti sami, ale u jiných (zejména klientů JavaScriptu) to není možné.
Kdykoli čtete data z rozhraní API webové služby, měli byste se pokusit použít požadavky GET, pokud je to možné, nikoli POST, protože druhý nelze uložit do mezipaměti a v konfiguracích multi-datacenter (včetně stránek Wikimedie) může jít do vzdálenějšího datového centra.
Ve výjimečných případech, kdy opravdu potřebujete použít POST pro požadavek na čtení, jako je volání action=parse s dlouhým řetězcem wikitextu, zvažte nastavení hlavičky Promise-Non-Write-API-Action: true.
To pomáhá zajistit, aby byl váš požadavek POST zpracován aplikačním serverem v nejbližším datovém centru, je-li to vhodné.
Není potřeba nastavovat tuto hlavičku pro požadavky GET a ani by neměla být nastavena při vytváření cross-wiki požadavků v rámci rodiny wiki pomocí CentralAuth; viz T91820.
Související odkazy
- Oficiální pokyny pro používání API na Wikimedia Foundation Governance wiki
- API:Hlavní stránka - průvodce rychlým startem.
- API:Ratelimit & API:Ratelimit/Wikimedia sites
- Spravováno MediaWiki Interfaces Team.
- Živý chat (IRC): #mediawiki-core připojit se
- Nástroj pro sledování problémů: Phabricator MediaWiki-Action-API (nahlášení problému)