/ 
Quiq-1.218
River stage zero No dependents
/ Quiq::MediaWiki::Client

NAME

Quiq::MediaWiki::Client - Clientseitiger Zugriff auf ein MediaWiki

BASE CLASS

Quiq::Hash

DESCRIPTION

Diese Klasse implementiert Methoden zur Kommunikation mit einem MediaWiki über die sogenannte 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 alle Daten in UTF-8.

Insbesondere implementiert die Klasse die Methode $mw->load(), mit welcher sowohl Seiten als auch Mediendateien (z.B. Bilder) "intelligent" geladen werden können.

Bei Angabe der Option -debug => 1 bei Aufruf des Konstruktors wird die gesamte Kommunikation auf STDERR protokolliert.

SEE ALSO

EXAMPLES

Beispiele für MediaWiki URLs:

METHODS

Konstruktor

new() - Instantiiere MediaWiki-API Client

Synopsis

$mw = $class->new($url,@opt);
$mw = $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 (wird mit -debug=>1 eingeschaltet) in Farbe aus.

-debug => $bool (Default: 0)

Gib Laufzeit-Information wie den Kommunikationsverlauf auf STDERR aus.

Returns

Client-Objekt (Referenz)

Description

Instantiiere einen Client für die MediaWiki-API $url und liefere eine Referenz auf dieses Objekt zurück.

Der Konstruktor-Aufruf löst keinen Server-Request aus. Sind $user und $password angegeben, wird der Benutzer erst mit dem ersten Token-Request eingeloggt. Er wird also nur eingeloggt, wenn es nötig ist. Vorteil: Ein Client, bei dem sich erst im Laufe der Ausführung herausstellt, ob er Requests ausführt, muss nicht vorab einen - ggf. unnötigen - Login-Request ausführen. (De facto besteht ein Login-Request aus zwei Requests, da mit dem ersten Aufruf lediglich der Login-Token geliefert wird.) Solange der Client Requests ausführt, die kein Login benötigen, werden diese beiden Requests ebenfalls gespart.

Bei Angabe der Option -debug => 1 bei Aufruf des Konstruktors wird die gesamte Kommunikation auf STDERR protokolliert.

Grundlegende Operationen

login() - Logge Nutzer ein

Synopsis

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

Arguments

$user

Name des Nutzers

$password

Passwort des Nutzers

Returns

Response (Hash-Referenz)

Description

Melde den Benutzer $user mit Passwort $password auf dem MediaWiki-Server an. Alternativ ist ein automatisches Login möglich, was eleganter ist. Siehe Konstruktor.

Example

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

getToken() - Besorge Token für Operation

Synopsis

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

Arguments

$action

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

Returns

Token (String)

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 nötig ist.

editPage() - Speichere Seite

Synopsis

$res = $mw->editPage($pageId,$text); # [1]
$res = $mw->editPage($title,$text);  # [2]

Arguments

$pageId

Page-Id der Seite.

$title

Titel der Seite.

$text

Text der Seite

Returns

Response (Hash-Referenz)

Description

Dies ist die Lowlevel-Methode zum Speichern einer Seite oder des Contents einer Seite. Eine weitergehende Logik, die auch Titelnderungen erlaubt, implementiert die Methode $mw->load().

In Fassung [1] wird der Content der Seite mit der Page-Id $pageId auf Text $text gesetzt. Die Seite muss existieren.

In Fassung [2] muss die Seite nicht existieren. Der MediaWiki-Server implementiert folgende Logik:

  • Existiert die Seite nicht, wird sie angelegt.

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

  • Existiert die Seite und ist der Text identisch, wird der Aufruf vom Wiki-Server ignoriert.

getPage() - Liefere Seite

Synopsis

$pag = $mw->getPage($pageId,@opt);
$pag = $mw->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, sondern liefere undef.

Returns

Page-Objekt (Hash-Referenz)

Description

Ermittele die Seite mit der Page-Id $pageId bzw. dem Titel $title und liefere diese zurück. Die Methode erkennt eine Page-Id daran, dass der Wert ausschließlich aus Ziffern besteht. Alles andere wird als Seitentitel interpretiert.

Der geliefere Hash besitzt folgende Komponenten, die auch per Accessor-Methode abgefragt werden können:

    • (= Inhalt der Seite)

  • comment

  • contentformat

  • contentmodel

  • ns

  • pageid

  • parentid

  • revid

  • size

  • timestamp

  • title

  • user

movePage() - Benenne Seite um

Synopsis

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

Arguments

$pageId

Page-Id der Seite.

$oldTitle

Titel 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. Wird -redirect => 0 gesetzt, unterbleibt dies.

Returns

Response (Hash-Referenz)

Description

Benenne die Seite mit Page-Id $pageId oder dem Titel $oldTitle in $newTitle um. Die alte Seite existiert weiterhin. Das Wiki richtet automatisch eine Umleitung von der alten zur neuen Seite ein, sofern beim Aufruf nicht -redirect => 0 angegeben wird.

siteInfo() - Liefere Information über Server

Synopsis

$res = $mw->siteInfo;
$res = $mw->siteInfo(@properties);

Arguments

@properties

Liste der Sysinfo-Properties, die abgefragt werden sollen.

Returns

Response (Hash-Referenz)

Description

Ermittele die Server-Eigenschaften (genauer: Eigenschaften-Gruppen) @properties und liefere das Resultat zurück. Sind keine Properties angegeben, werden alle (zur Zeit der Implementierung bekannten) Properties abgefragt.

Example

$ quiq-mediawiki ruv statistics --debug

uploadFile() - Lade Mediendatei hoch

Synopsis

$res = $mw->uploadFile($file);

Arguments

$file

Pfad der Datei.

Options

-force => $bool (Default: 0)

Lade die Datei auch im Falle von Warnungen hoch, z.B. dass die Datei im Wiki bereits existiert.

Returns

Response

Description

Lade die lokale Mediendatei $file über die Upload-Schnittstelle ins MediaWiki hoch. Dies ist typischerweise eine Bilddatei.

See Also

# Datei hochladen (wir lesen $file selbst)

my $p = Quiq::Path->new;
my $data = $p->read($file);

# Datei hochladen

my $filename = $p->filename($file);
return $self->send('POST','upload',
    token => $token,
    filename => $filename,
    file => [undef,$filename,Content=>$data],
);

version() - Versionsnummer des Servers

Synopsis

$version = $mw->version;

Description

Ermittele die Versionsnummer des MediaWiki-Servers und liefere diese zurück. Die Information wird im Objekt gecached.

Höhere Operationen

load() - Lade Seite oder Mediendatei ins Wiki

Synopsis

$mw->load($cacheDir,$file,@opt);

Arguments

$cacheDir

Pfad zum Spiegel-Verzeichnis. Der Inhalt des Spiegel-Verzeichnisses wird von der Methode verwaltet. Es enthält Kopien der geladenen Dateien.

$file

Pfad der Datei, die geladen werden soll. Dies kann eine Seitendatei (*.mw) oder eine sonstige Datei sein (*.png, *.jpg, *.gif, ...), die über die Upload-Schnittstelle des MediaWiki geladen werden kann.

Options

-force => $bool (Default: 0)

Lade die Datei ins Wiki, auch wenn sie sich nicht geändert hat (gegenüber dem Cache).

Returns

nichts

Description

Lade Seite oder Mediendatei $file ins Wiki. Hierbei wird ein "intelligentes" Verfahren angewendet, das verschiedene Sonderfälle berücksichtigt (siehe unten). Eine Kopie der hochgeladenen Datei wird im Cache-Verzeichnis $cacheDir abgelegt. Ist die Cache-Version eines früheren Aufrufs identisch zu zur aktuellen Version $file, kehrt der Aufruf sofort zurück (außer bei Option -force => 1). Den Schlüssel stellt der Dateiname dar. Dieser muss über allen Dateien eindeutig sein und darf sich extern nicht ändern.

Die Datei einer Seite muss die Endung *.mw besitzen und sowohl den Titel als auch den Inhalt der Seite als Record (siehe Quiq::Record) enthalten. Eine Mediendatei (*.png, *.jpg, ...) wird wie sie ist an die Methode übergeben.

In der Cache-Datei einer Seite speichert die Methode die Page-Id der Seite. Dadurch kann die Methode auch bei Titeländerungen die Seite im Wiki ermitteln und vor dem Speichern eine move-Operation ausführen. Die Fälle im Einzelnen:

Aufruf wird ignoriert

Die Datei existiert im Cache und ist identisch zu dieser und -force ist nicht gesetzt.

Seite oder Mediendatei wird im Wiki gespeichert

  • Die Datei existiert nicht im Cache

  • Die Datei existiert im Cache und ist gegenüber der externen Datei verschieden

  • Option -force ist gesetzt

Aufruf wird mit Fehlermeldung zurückgewiesen

Die Datei ist eine Seite und soll gespeichert werden, wobei ein Unterschied zwischen Cache- und Wiki-Datei festgestellt wird. Das bedeutet, im Wiki wurde die Datei seit dem letzten Speichern geändert. Der Aufruf ist nur durch Setzen der Option -force möglich, denn die Änderung muss händisch in die externe Datei eingepflegt werden.

Seite wird vor dem Speichern umbenannt

Die Datei ist eine Seite und der Titel der Seite ist zwischen Cachedatei und externer Datei unterschiedlich. Die Seite wird automatisch im Wiki umbenannt.

Kommunikation

send() - Sende Request, empfange Response

Synopsis

$res = $mw->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 Antwort auf Einzelseite

Synopsis

$pag = $mw->reduceToPage($res);
$pag = $mw->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 einelementigen 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

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

Description

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

VERSION

1.218

AUTHOR

Frank Seitz, http://fseitz.de/

COPYRIGHT

Copyright (C) 2024 Frank Seitz

LICENSE

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