NAME

Prty::MediaWiki::Api - Clientseitiger Zugriff auf MediaWiki API

BASE CLASS

Prty::Hash

DESCRIPTION

Diese Klasse implementiert verschiedene clientseitige Methoden für den Zugriff auf die serverseitige MediaWiki-API.

Die MediaWiki-API wird über api.php (statt index.php) angesprochen. Die Doku der API wird angezeigt, wenn api.php ohne Parameter oder mit "action=help&recursivesubmodules=1" (alles auf einer Seite) aufgerufen wird.

Die MediaWiki-API empfängt und liefert die Daten in UTF-8.

METHODS

Konstruktor

new() - Instantiiere MediaWiki-API Client

Synopsis

    $mwa = $class->new($url,@opt);
    $mwa = $class->new($url,$user,$password,@opt);

Arguments

$url

API-URL des MediaWiki, z.B. https://en.wikipedia.org/w/api.php.

$user

Benutzername (für automatisches Login statt explizites Login).

$password

Passwort (für automatisches Login statt explizites Login).

Options

-color => $bool (Default: 1)

Gib die Laufzeitinformation (wenn -debug => 1) in Farbe aus.

-debug => $bool (Default: 0)

Gib Laufzeit-Information wie den Kommunikationsverlauf auf STDERR aus.

Returns

Client-Objekt

Description

Instantiiere einen Client für die MediaWiki-API $url und liefere eine Referenz auf dieses Objekt zurück. Sind Benutzername $user und Passwort $password angegeben, wird der Benutzer mit dem ersten Request automatisch eingeloggt. Alternativ kann die Methode $mwa->login() genutzt werden, um den Benutzer zu einem beliebigen Zeitpunkt einzuloggen.

Examples

  • https://www.mediawiki.org/w/api.php

  • http://lxv0103.ruv.de:8080/api.php

Meta-Operationen

login() - Logge Nutzer ein

Synopsis

    $res = $mw->login($user,$password);

Arguments

$user

Name des Nutzers

$password

Passwort des Nutzers

Description

Logge den Benutzer $user mit Passwort $password auf dem MediaWiki-Server ein. Alternativ ist ein automatisches Login möglich, siehe Konstruktor.

Example

    $ perl -MPrty::MediaWiki::Api -E 'Prty::MediaWiki::Api->new("http://lxv0103.ruv.de:8080/api.php",-debug=>1)->login("XV882JS","<PASSWORD>")'

getToken() - Besorge Token für Operation

Synopsis

    $token = $mwa->getToken($action);

Arguments

$action

Operation, für die das Token benötigt wird.

Description

Besorge vom Server ein Token zum Ausführen von Operation $action und liefere dieses zurück. Da das Token je Session für alle Seiten identisch ist, cachen wir die Tokens, so dass nur eine Serveranfrage je Operationstyp nötig ist.

Seiten-Operationen

getPage() - Liefere Seite

Synopsis

    $pag = $mwa->getPage($pageId,@opt);
    $pag = $mwa->getPage($title,@opt);

Arguments

$pageId

Page-Id der Seite.

$title

Titel der Seite.

Options

-sloppy => $bool (Default: 0)

Wirf keine Exception, wenn die Seite nicht gefunden wird.

Returns

Page-Objekt (Hash)

Description

Ermittele die Seite mit der PageId $pageId bzw. dem Titel $title und liefere diese zurück.

editPage() - Erzeuge/bearbeite Seite

Synopsis

    $res = $mwa->editPage($title,$text);
    $res = $mwa->editPage($pageId,$text);

Arguments

$title

Titel der Seite.

$pageId

Page-Id der Seite.

$text

Text der Seite

Returns

Response

Description

Setze den Inhalt der Seite mit dem Titel $title auf Text $text. Drei Fälle lassen sich unterscheiden:

  1. Existiert die Seite nicht, wird sie angelegt.

  2. Existiert die Seite und der Text ist verschieden, wird der bestehende Text ersetzt.

  3. Existiert die Seite und der Text ist identisch, wird der Aufruf vom Wiki ignoriert.

Example

  • Response nach Neuanlage einer Seite

        $mwa->editPage("XV882JS - API Testseite 8","Ein Text")';

    produziert (Log)

        ---JSON---
        \ {
            edit   {
                contentmodel   "wikitext",
                new            "",
                newrevid       13318,
                newtimestamp   "2018-12-27T11:54:51Z",
                oldrevid       0,
                pageid         2446,
                result         "Success",
                title          "XV882JS - API Testseite 8"
            }
        }

movePage() - Benenne Seite um

Synopsis

    $res = $mwa->movePage($oldTitle,$newTitle,@opt);
    $res = $mwa->movePage($pageId,$newTitle,@opt);

Arguments

$oldTitle

Titel der Seite.

$pageId

Page-Id der Seite.

$newTitle

Zukünftiger Titel der Seite.

Options

-reason => $text

Grund für die Umbenennung.

-redirect => $bool (Default: 1)

Erzeuge ein Redirekt von der alten zur neuen Seite.

Description

Benenne die Seite mit dem Titel $oldTitle bzw. der Page-Id $pageId in $newTitle um. Die alte Seite existiert weiterhin. Das Wiki richtet automatisch eine Umleitung von der alten zur neuen Seite ein.

Kommunikation

send() - Sende HTTP-Anfrage, empfange HTTP-Antwort

Synopsis

    $res = $mwa->send($method,$action,@keyVal);

Arguments

$method

Die HTTP Request-Methode: 'GET' oder 'POST'.

$action

Die Aktion, die ausgeführt werden soll, z.B. 'query'.

@keyVal

Die Liste der Schlüssel/Wert-Paare, die an den Server übermittelt werden, entweder als URL-Parameter im Falle von GET oder im Body des Requests im Falle von POST.

Returns

Dekodiertes JSON in UTF-8 als Perl-Hash

Description

Grundlegende Methode, über die sämtliche Interaktion mit dem MediaWiki-Server läuft. Die Interaktion besteht in einem Austausch von Schlüssel/Wert-Paaren via HTTP mittels GET oder POST. Der Client sendet mit einem Request eine Menge von Schlüssel/Wert-Paaren und erhält vom Server in der Response eine Menge von Schlüssel/Wert-Paaren zurück. In beide Richtungen wird UTF-8 Encoding vorausgesetzt. D.h. die @keyVal-Elemente müssen UTF-8 kodiert sein, die Elemente in der Response $res sind es ebenfalls.

Response Handling

reduceToPage() - Reduziere Seitenliste auf Einzelseite

Synopsis

    $pag = $mwa->reduceToPage($res);
    $pag = $mwa->reduceToPage($res,$sloppy);

Arguments

$res

Response vom Server mit Seitenliste.

$sloppy

Wirf keine Exception, wenn keine Seite existiert.

Returns

Reduzierte Response

Description

Reduziere die Server-Response $res mit einer Seitenliste der Art

    {
        query => {
            pages => {
                $pageId => {
                     @keyVal
                },
                ...
            },
        }
    }

auf

    {
        @keyVal
    }

also auf ein Element und liefere dieses zurück.

Enthält die Seitenliste mehr als ein Element, oder handelt es sich um ein ungültiges (als "missing" gekennzeichnetes) Element, wird eine Exception geworfen.

Logging

log() - Schreibe Debug Log

Synopsis

    $mwa->log($title,$text);

Description

Schreibe den Text $text unter der Überschrift $title nach STDERR.

VERSION

1.127

SEE ALSO

AUTHOR

Frank Seitz, http://fseitz.de/

COPYRIGHT

Copyright (C) 2019 Frank Seitz

LICENSE

This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself.