Opětovné použití stávajících robotů

Často je mnohem jednodušší požádat o úlohu robota od stávajícího robota. Pokud máte pouze pravidelné požadavky nebo je vám programování nepříjemné, je to obvykle nejlepší řešení. Některé wikiny mají vyhrazenou stránku, kde lze takové požadavky podávat. Kromě toho existuje řada nástrojů, které má kdokoli k dispozici. Většina z nich má podobu vylepšených webových prohlížečů s funkcemi specifickými pro MediaWiki. Nejoblíbenější z nich je Project:AutoWikiBrowser (AWB), prohlížeč speciálně navržený pro pomoc s úpravami na Wikipedii a dalších projektech Wikimedie. Úplnější seznam nástrojů lze nalézt na w:Wikipedia:Tools/Editing tools na anglické Wikipedii. Nástroje, jako je AWB, lze často ovládat s malou nebo žádnou znalostí programování.

Opětovné použití kódové základny

Pokud se rozhodnete, že potřebujete vlastního robota kvůli četnosti nebo novosti vašich požadavků, nemusíte ho psát od začátku. Mnoho robotů zveřejňuje svůj zdrojový kód, který lze někdy znovu použít s malým dodatečným vývojovým časem. Ke stažení je také řada standardních rámců robotů. Tyto rámce obsahují převážnou většinu kódu robota. Vzhledem k tomu, že tyto rámce botů se běžně používají a složité kódování provedli jiní a bylo důkladně testováno, je mnohem snazší získat pro použití roboty založené na těchto rámcích. Nejoblíbenějším a nejběžnějším z těchto frameworků je Pywikibot (PWB), robot framework napsaný v Pythonu. Je důkladně zdokumentován a otestován a je již k dispozici mnoho standardizovaných skriptů Pywikibotů (pokynů pro roboty). Další příklady frameworks robotů lze nalézt níže. Pro některé z těchto frameworks robotů, jako je PWB, je k úspěšnému spuštění robota nezbytná obecná znalost skriptů (je důležité tyto rámce pravidelně aktualizovat).

Důležité otázky

Psaní nového robota vyžaduje značné programátorské schopnosti. Zcela nový robot musí projít důkladným testováním, než bude schválen pro běžný provoz. Plánování je zásadní pro získání bezchybného, účinného a efektivního programu. Důležité jsou následující počáteční úvahy:

• Bude robot ručně asistovaný nebo plně automatizovaný?
• Vytvoříte robota sami, nebo s pomocí dalších programátorů?
• Jaký jazyk bude použit k implementaci robota?
• Budou protokolovány požadavky, úpravy nebo jiné akce robota? Pokud ano, budou protokoly uloženy na místních médiích nebo na wiki stránkách?
• Poběží robot uvnitř webového prohlížeče (například napsaný v JavaScriptu) nebo to bude samostatný program?
• Pokud je robot samostatný program, poběží na vašem místním počítači nebo na vzdáleném serveru, jako je Toolforge?
• Pokud robot běží na vzdáleném serveru, budou moci robota obsluhovat nebo spustit další editoři?

Přehled provozu

Stejně jako lidský editor čte robot MediaWiki wiki stránky a provádí změny tam, kde si myslí, že je třeba provést změny. Rozdíl je v tom, že ačkoli jsou roboti rychlejší a méně náchylní k únavě než lidé, nejsou zdaleka tak bystří jako my. Boti jsou dobří v opakujících se úlohách, které mají snadno definované vzorce, kde je třeba dělat jen málo rozhodnutí.

V nejtypičtějším případě se robot přihlásí ke svému účtu a požaduje stránky z wiki v podstatě stejným způsobem jako prohlížeč – i když stránku nezobrazí na obrazovce, ale pracuje na ní v paměti – a poté programově prozkoumá kód stránky, aby zjistil, zda není třeba provést nějaké změny. Poté provede a odešle jakékoli úpravy, pro které byl navržen, opět stejným způsobem, jakým by to udělal prohlížeč.

Protože roboti přistupují ke stránkám stejným způsobem jako lidé, mohou se roboti potýkat se stejnými potížemi jako lidští uživatelé. Mohou se dostat do konfliktů úprav, mít časový limit stránky nebo narazit na jiné neočekávané komplikace při vyžádání stránek nebo provádění úprav. Vzhledem k tomu, že objem práce provedené robotem je větší než objem práce provedené živou osobou, je pravděpodobnější, že se s těmito problémy setká robot. Proto je důležité při psaní robota tyto situace zvážit.

API pro roboty

Aby mohl robot provést změny na wiki stránkách, musí nutně načíst stránky z wiki a odeslat úpravy zpět. Pro tento účel je k dispozici několik aplikačních programovacích rozhraní (API).

• MediaWiki Action API (api.php). Tato webová služba byla speciálně napsána tak, aby umožňovala automatizovaným procesům, jako jsou roboti, provádět dotazy a odesílat změny. Data jsou vrácena ve formátu JSON (další podrobnosti viz výstupní formáty).

  Stav: Vestavěná funkce MediaWiki, dostupná na všech serverech Wikimedie. Jiné wikiny než Wikimedia mohou zakázat nebo omezit přístup pro zápis.

  Existuje také sandbox API pro ty, kteří chtějí testovat funkce api.php.

• Special:Export lze použít k získání hromadného exportu obsahu stránky ve formě XML. Viz Manual:Parameters to Special:Export[[:| ]] pro argumenty;

  Stav: Vestavěná funkce MediaWiki, dostupná na všech serverech Wikimedie.

• Nezpracované (wikitextové) zpracování stránky: Odeslání požadavku action=raw nebo action=raw&templates=expand GET na index.php poskytne nezpracovaný zdrojový kód wikitextu stránky. Například:
  https://en.wikipedia.org/w/index.php?title=Help:Creating_a_bot&action=raw.
  Dotaz API s:
  api.php?action=query&titles=Help:Creating_a_bot&prop=revisions&rvprop=content [zkuste v ApiSandbox]
  nebo
  api.php?action=query&titles=Help:Creating_a_bot&prop=revisions&rvprop=content&rvexpandtemplates=1 [zkuste v ApiSandbox]
  je zhruba ekvivalentní a umožňuje získat další informace.

  Stav: Vestavěná funkce MediaWiki, dostupná na všech serverech Wikimedie.

Některé webové servery jsou nakonfigurovány tak, aby udělovaly požadavky na komprimovaný obsah (gzip). To lze provést zahrnutím řádku "Accept-Encoding: gzip" do hlavičky požadavku HTTP. Pokud hlavička HTTP odpovědi obsahuje "Content-Encoding: gzip", dokument je ve formě gzip, jinak je v běžné nekomprimované podobě. Všimněte si, že toto je specifické pro webový server a ne pro software MediaWiki. Jiné stránky využívající MediaWiki tuto funkci nemusí mít. Pokud používáte existující botový framework, měl by zvládat nízkoúrovňové operace, jako je tato.

Přihlášení

Aby mohli provádět úpravy, musí být schválení roboti přihlášeni. Přestože robot může zadávat požadavky na čtení bez přihlášení, roboti, kteří dokončili testování, by se měli přihlásit ke všem aktivitám. Roboti přihlášení z účtu s příznakem robota (viz #Příznak robota níže) mohou získat více výsledků na dotaz z Mediawiki API (api.php). Většina rámců botů by měla zpracovávat přihlášení a soubory cookie automaticky, ale pokud nepoužíváte existující rámec, budete muset postupovat podle těchto kroků.

Z bezpečnostních důvodů musí být přihlašovací údaje předány pomocí metody HTTP POST. Protože parametry požadavků HTTP GET jsou snadno viditelné v URL, přihlášení přes GET je zakázáno.

K přihlášení robota pomocí MediaWiki API jsou potřeba 2 požadavky:

Požadavek 1 – toto je požadavek GET na získání přihlašovacího tokenu

• URL: https://en.wikipedia.org/w/api.php?action=query&format=json&meta=tokens&type=login

To vrátí parametr "logintoken" ve formě JSON, jak je zdokumentováno na API:Přihlášení . K dispozici jsou další výstupní formáty. Vrátí také soubory cookie HTTP, jak je popsáno níže.

Požadavek 2 – toto je POST pro dokončení přihlášení

• URL: https://en.wikipedia.org/w/api.php?action=login&format=json
• Parametry POST:
  • lgname=BOTUSERNAME
  • lgpassword=BOTPASSWORD
  • lgtoken=TOKEN

kde TOKEN je token z předchozího výsledku. Soubory cookie HTTP z předchozího požadavku musí být také předány s druhým požadavkem.

Úspěšný pokus o přihlášení povede k tomu, že server Wikimedie nastaví několik HTTP cookie. Bot musí uložit tyto soubory cookie a odeslat je zpět pokaždé, když zadá požadavek (to je zvláště důležité pro úpravy). Na anglické Wikipedii by se měly používat následující soubory cookie: enwikiUserID, enwikiToken a enwikiUserName. Soubor cookie enwikisession je nutný ke skutečnému odeslání úpravy nebo potvrzení nějaké změny, jinak bude vrácena chybová zpráva MediaWiki:Session fail preview.

Přihlášení k hlavnímu účtu přes action=login je zastaralé a může přestat fungovat bez varování. Chcete-li nadále používat kód robota, který se přihlašuje pomocí action=login, viz Special:BotPasswords.

Editace; upravit tokeny

MediaWiki používá systém edit tokenů pro provádění úprav stránek MediaWiki a také pro další operace, které upravují stávající obsah, jako je například vrácení zpět. Token vypadá jako dlouhé hexadecimální číslo následované '+\', například:

d41d8cd98f00b204e9800998ecf8427e+\

Úlohou tokenů úprav je zabránit "únosu úprav", kdy jsou uživatelé oklamáni, aby provedli úpravy kliknutím na jediný odkaz.

Proces úprav zahrnuje dva požadavky HTTP. Nejprve je třeba podat žádost o token pro úpravy. Poté je třeba provést druhý požadavek HTTP, který odešle nový obsah stránky spolu s právě získaným tokenem úprav. Není možné provést úpravu v jednom požadavku HTTP. Token úprav zůstává stejný po dobu trvání relace přihlášeného uživatele, takže token pro úpravy je třeba načíst pouze jednou a lze jej použít pro všechny následující úpravy.

Chcete-li získat token pro úpravy, postupujte takto:

• MediaWiki API (api.php). Zadejte požadavek s následujícími parametry (viz Special:MyLanguage/API:Edit - Create&Edit pages).
  • action=query
  • meta=tokens

  Token bude vrácen v atributu edittoken odpovědi.

Pokud token úprav, který robot obdrží, nemá hexadecimální řetězec (tj., token pro úpravy je pouze '+\'), pak robot s největší pravděpodobností není přihlášen. To může být způsobeno řadou faktorů: Selháním ověřování se serverem, přerušením připojení, určitým časovým limitem nebo chybou při ukládání nebo vracení správných souborů cookie. Pokud se nejedná o chybu v programování, přihlaste se znovu a obnovte soubory cookie pro přihlášení. Roboti musí použít tvrzení, aby se ujistili, že jsou přihlášeni.

Úprava konfliktů

Ke konfliktům úprav dochází, když je na stejné stránce provedeno více překrývajících se pokusů o úpravy. Téměř každý robot bude nakonec chycen v konfliktu úprav toho či onoho druhu a měl by obsahovat nějaký mechanismus pro testování a přizpůsobení se těmto problémům.

Boti, kteří používají Mediawiki API (api.php), by měli získat token pro úpravy spolu s starttimestamp a "základním" časovým razítkem poslední revize před načtením textu stránky v rámci přípravy na úpravu. prop=info|revisions lze použít k načtení tokenu i obsahu stránky v jednom dotazu. Příklad:

Při odesílání úprav nastavte atributy starttimestamp a basetimestamp a zkontrolujte odpovědi serveru, zda neobsahují chyby. Další podrobnosti viz API:Edit - Create&Edit pages .

Obecně řečeno, pokud se úprava nepodaří dokončit, robot by měl stránku znovu zkontrolovat, než se pokusí provést novou úpravu, aby se ujistil, že je úprava stále vhodná. Dále, pokud robot znovu zkontroluje stránku, aby znovu odeslal změnu, měl by být opatrný, aby se vyhnul jakémukoli chování, které by mohlo vést k nekonečné smyčce, a jakémukoli chování, které by se dokonce mohlo podobat úpravě warring.

Specifikace

• Specifikace je úkolem přesně popsat software, který má být napsán, pokud možno důsledným způsobem. Měli byste přijít s podrobným návrhem toho, co chcete, aby dělal. Zkuste tento návrh prodiskutovat s některými redaktory a na základě zpětné vazby jej upřesnit. I skvělý nápad lze vylepšit začleněním nápadů od jiných editorů.
• V nejzákladnější formě musí váš určený robot splňovat následující kritéria:

• Robot je neškodný (nesmí provádět úpravy, které by mohly být považovány za narušující hladký chod wiki)
• Robot je užitečný (poskytuje užitečnou službu efektivněji, než by mohl lidský editor)
• Robot neplýtvá prostředky serveru.

Architektura softwaru

• Přemýšlejte o tom, jak byste jej mohli vytvořit a jaké programovací jazyky a nástroje byste použili. Architektura se zabývá zajištěním toho, aby softwarový systém splňoval požadavky produktu, a také zajištěním toho, že budoucí požadavky lze řešit. Některé programovací jazyky jsou pro některé úlohy vhodnější než jiné, další podrobnosti viz část o programovacích jazycích níže.

Implementace

Implementace (neboli kódování) zahrnuje přeměnu návrhu a plánování kódu. Může to být nejzřejmější část práce softwarového inženýrství, ale není to nutně ta největší část. Ve fázi implementace byste měli:

• Vytvořte účet pro svého robota. Po přihlášení přejděte na registrační stránku a vytvořte si účet a propojte jej se svým. (Pokud si nevytvoříte účet robota, když jste přihlášeni, může být na některých wikinách zablokován podle jejich zásad)
• Vytvořte uživatelskou stránku pro svého robota. Úpravy vašeho robota nesmí být prováděny pod vaším vlastním účtem. Váš robot bude potřebovat svůj vlastní účet s vlastním uživatelským jménem a heslem.
• Přidejte stejné informace na uživatelskou stránku robota. Pro každou funkci by bylo dobré přidat odkaz na schvalovací stránku (ať už schválenou nebo ne).
• Kódujte svého robota ve vámi zvoleném programovacím jazyce.

Testování

Dobrým způsobem, jak otestovat svého robota při vývoji, je nechat jej ukázat změny (pokud nějaké), které by provedl na stránce, spíše než ve skutečnosti upravovat živou wiki. Některé rámce botů (jako například pywikibot) mají předkódované metody pro zobrazení rozdílů.

Dokumentace

Důležitým (a často přehlíženým) úkolem je dokumentace interního návrhu vašeho robota za účelem budoucí údržby a vylepšení. To je zvláště důležité, pokud se chystáte povolit klony vašeho robota. V ideálním případě byste měli zveřejnit zdrojový kód svého robota na jeho uživatelské stránce nebo v systému kontroly revizí (viz #Robot s otevřeným zdrojovým kódem), pokud chcete, aby ostatní mohli spouštět jeho klony. Tento kód by měl, pro snadné použití, být dobře zdokumentován (obvykle pomocí komentářů).

Dotazy/stížnosti

Měli byste být připraveni reagovat na dotazy nebo námitky vůči vašemu robotovi na vaší uživatelské diskusní stránce, zejména pokud působí v potenciálně citlivé oblasti.

Údržba

Údržba a vylepšení vašeho robota, aby se vyrovnal s nově objevenými chybami nebo novými požadavky, může trvat mnohem déle než počáteční vývoj softwaru. Nejen, že může být nutné přidat kód, který neodpovídá původnímu návrhu, ale pouhé určení toho, jak software funguje v určitém okamžiku po jeho dokončení, může vyžadovat značné úsilí (to je další důvod, proč dokumentovat svůj kód za pochodu).

Osvědčené postupy pro roboty

• Nastavte pro svého robota vlastní hlavičku User-Agent (podle zásad Wikimedie pro User-Agent, pokud bude váš robot pracovat na wikinách Wikimedie). Pokud tak neučiníte, váš robot může narazit na chyby a může být zablokován na úrovni serveru.
• Použijte parametr maxlag s maximálním zpožděním 5 sekund. To umožní botovi běžet rychle, když je zatížení serveru nízké, a přibrzdit robota, když je zatížení serveru vysoké.
  • Pokud píšete bota v rámci, který nepodporuje maxlag, omezte celkový počet požadavků (požadavky na čtení a zápis dohromady) na maximálně 10/minutu.
• Kdykoli je to možné, používejte MediaWiki API a nastavte limity dotazů na nejvyšší hodnoty, které server povoluje, abyste minimalizovali celkový počet požadavků, které je třeba provést.
• Požadavky na úpravy (zápis) jsou z hlediska času serveru dražší než požadavky na čtení. Buďte nenároční na úpravy a navrhněte svůj kód tak, aby bylo co nejméně úprav.
  • Pokuste se sjednotit úpravy. Jedna velká úprava je lepší než 10 menších.
• Pokud je to možné, povolte trvalé připojení HTTP a kompresi ve vaší knihovně klienta HTTP.
• Nevytvářejte vícevláknové požadavky. Před zahájením dalšího počkejte na dokončení jednoho požadavku serveru
• Po obdržení chyb ze serveru ustupte. Chyby, jako jsou časové limity, jsou často známkou velkého zatížení serveru. Použijte sekvenci stále delších prodlev mezi opakovanými požadavky.
• Použijte assertion k zajištění přihlášení vašeho robota.
• Před provedením velkých automatických běhů svůj kód důkladně otestujte. Individuálně prozkoumejte všechny úpravy ve zkušebních provozech a ověřte, zda jsou dokonalé.

Běžné funkce botů, které byste měli zvážit k implementaci

PageObject.edit(text=pagetext, bot=True, summary=pagesummary)

Awk

• Framework a knihovny: BotWikiAwk
• Příklady robotů na účtu GitHub User:GreenC na GitHub

Perl

Pokud se nacházíte na webovém serveru, můžete spustit svůj program a komunikovat s ním, když běží, prostřednictvím w:Common Gateway Interface z vašeho prohlížeče. Pokud vám váš poskytovatel internetových služeb poskytuje webový prostor, je velká šance, že máte přístup k Perlu postavenému na webovém serveru, ze kterého můžete spouštět své programy v Perlu.

Knihovny:

• MediaWiki::API – Základní rozhraní API, které umožňuje skriptům automatizovat úpravy a extrakci dat z webů řízených MediaWiki.
• MediaWiki::Bot – Poměrně kompletní MediaWiki bot framework napsaný v Perlu. Poskytuje vyšší úroveň abstrakce než MediaWiki::API. Pluginy poskytují funkce administrátora a správce. Momentálně nepodporováno.

PHP

PHP lze také použít pro programování robotů. Vývojáři MediaWiki již znají PHP, protože to je jazyk MediaWiki a jeho rozšíření jsou napsána. PHP je zvláště dobrá volba, pokud chcete svému botovi poskytnout rozhraní založené na webovém formuláři. Předpokládejme například, že chcete vytvořit robota pro přejmenování kategorií. Můžete vytvořit HTML formulář, do kterého zadáte aktuální a požadované názvy kategorie. Když je formulář odeslán, váš robot může číst tyto vstupy, poté upravit všechny články v aktuální kategorii a přesunout je do požadované kategorie. (Je zřejmé, že každý robot s rozhraním formuláře by musel být nějak zabezpečen před náhodnými webovými surfaři.)

Tabulka Funkce botů PHP na anglické Wikipedii může poskytnout určitý pohled na možnosti hlavních rámců botů.

Python

Python je populární interpretovaný jazyk s objektově orientovanými funkcemi.

Knihovny

Prosím, pomozte aktualizovat tuto tabulku.

Microsoft .NET

Microsoft .NET je sada jazyků včetně C#, C++/CLI, Visual Basic .NET, J#, JScript .NET, IronPython a Windows PowerShell. Často se používá Microsoft Visual Studio integrované vývojové prostředí nebo bezplatné Microsoft Visual Studio Express verze. Pomocí Mono Project mohou programy .NET běžet také na Linux, Unix, BSD, Solaris a Mac OS X pod Windows stejně jako na Mac OS X.

Knihovny:

• DotNetWikiBot Framework – plnohodnotný klient API na .NET, který umožňuje snadno vytvářet programy a webové roboty pro správu informací na stránkách založených na MediaWiki. Nyní přeloženo do několika jazyků. Podrobná kompilovaná dokumentace je k dispozici v angličtině.
• Knihovna WikiFunctions .NET – Součástí AWB je knihovna věcí užitečných pro roboty, jako je generování seznamů, načítání/úpravy článků, připojení ke kanálu IRC s posledními změnami a další.

Java

Java programy jsou obecně vyvíjeny s IDE, jako je Eclipse nebo NetBeans. Vývoj pomocí konzoly příkazového řádku (s programy javac a java) je také možností.

Knihovny:

• Java Wiki Bot Framework – framework bota wiki Java
• wiki-java – framework wiki bota Java, který je pouze jedním souborem
• WPCleaner – knihovna používaná nástrojem WPCleaner
• jwiki – jednoduchý a snadno použitelný framework wiki bota Java

JavaScript (Node.js)

JavaScript je skriptovací jazyk používaný hlavně na webových stránkách, například pro uživatelské skripty přidané na stránky vašeho vector.js nebo monobook.js. Pomocí Node.js je možné použít JavaScript na straně serveru, například pro vývoj botů.

Prosím, pomozte aktualizovat tuto tabulku.

Ruby

Ruby je populární dynamický, objektově orientovaný programovací jazyk.

Knihovny:

• MediaWiki::Butt - Ruby framework pro API v aktivním vývoji. Testováno s verzemi tak aktuálními, jako je CurseGamepedia.
• mediawiki/ruby/api, Ruby API klientská knihovna. Poslední aktualizace z prosince 2017, již není udržována, ale stále funguje.
• MediaWiki::Gateway – Ruby framework pro API. Poslední aktualizace v lednu 2016. Již není v aktivním vývoji, testováno až do MediaWiki 1.22, kompatibilní s wikinami Wikimedie. Není známo, zda stále funguje.
• wikipedia-client - Ruby framework využívající API. Poslední aktualizace v březnu 2018. Není známo, zda stále funguje.

Common Lisp

• CL-MediaWiki implementuje MediaWiki API jako balíček Common Lisp. Plánuje se použití JSON jako datového formátu dotazu. Podporuje maxlag a assertion.

Haskell

• https://hackage.haskell.org/package/mediawiki

VBScript

VBScript je skriptovací jazyk založený na programovacím jazyce Visual Basic. Neexistují žádné publikované rámce botů pro VBScript, ale některé příklady botů, které jej používají, lze vidět níže:

Příklady:

• w:User:Smallman12q/Scripts/cleanuplistingtowiki (2013) - přihlaste se a poskytněte náhled úprav
• w:User:Smallman12q/VBS/Savewatchlist (2012) - přihlaste se, získejte nezpracovaný seznam sledovaných položek, uložte do souboru, odhlaste se, zavřete IE
• w:Commons:User:Smallbot#Sources - několik skriptů ukazujících použití VBScriptu (JavaScript, XMLHTTP, MSHTML, XMLDOM, COM) pro dávkové nahrávání.

Bash

Bash je Unix shell.

• Podívejte se na stránku API:Client_code/Bash . Vyžaduje balíček cURL.