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. See also the official guidelines about API usage on Wikimedia Foundation Governance wiki.
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, pokud je to možné, použít požadavky GET, nikoli POST, protože ty nelze uložit do mezipaměti.
In exceptional cases where you really need to use POST for a read request, such as calling action=parse with a long string of wikitext, consider setting the Promise-Non-Write-API-Action: true header.
This helps ensure that your POST request is processed by an application server in the closest data center, if appropriate.
There is no need to set this header for GET requests, and neither should it be set when making cross-wiki requests within a wiki family using CentralAuth; see úkol T91820.
Související odkazy
- Official guidelines about API usage on 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)