API:Query/de

From MediaWiki.org
Jump to: navigation, search
Tools clipart.png Diese Seite ist Teil der MediaWiki action API-Dokumentation.

MediaWiki action API

v · d · e

Das action=query-Modul erlaubt es dem Benutzer, die meisten Arten von Informationen aus der Datenbank abzurufen – es lehnt sich grob an die veraltete (und mittlerweile deaktivierte) query.php an. Zusätzlich kann man mit den Querys auch die für die Write-API notwendigen Token erhalten, welche zum Bearbeiten, Verschieben usw. von Artikeln gebraucht werden.

Das Query-Modul setzt sich wiederum aus mehreren Submodulen zusammen, von denen jedes eine eigene Funktion hat. Mehrere Querymodule lassen sich gemeinsam verwenden.

Prinzipiell gibt es 3 Arten von Submodulen:

  • Meta-Informationen - Informationen über das Wiki selbst und den angemeldeten Benutzer
  • Eigenschaften - Seiteninformationen und -inhalte abrufen
  • Listen - Seiten nach bestimmten Kriterien auflisten lassen

Unabhängig davon hat das Query-Modul auch ein paar eigene Funktionen.

Seiten auswählen[edit]

Es gibt zwei Arten, Seiten auszuwählen: Die Seiten direkt angeben oder Generatoren verwenden, um die Seitenliste dynamisch zu generieren.

Um eine Seite direkt anzugeben, gibt es drei Wege:

  • Den titles-Parameter, z.B. titles=Einstein|Goethe|Hauptseite
  • Den pageids-Parameter, z.B. pageids=123|456|75915
  • Den revids-Parameter, z.B. revids=478198|54872|54894545
    • Die meisten Module werden bei einer übergebenen Revisions-ID die dazugehörige Seiten-ID verwenden. Nur prop=revisions nutzt derzeit die RevisionsID direkt.

Man sollte beachten, dass die Titel-Liste eine "langsame Abfrage" im Sinne der #Begrenzungen darstellt, also auf 50 Titel pro Aufruf (oder 500 für Benutzer mit apihighlimits-Recht) begrenzt ist.

Mit dem Verwenden der Abfragen als Generator befasst sich ein eigener Absatz.

Seitentitel normalisieren[edit]

Einen Seitentitel zu normalisieren bedeutet, ihn in seine "Normalform" zu überführen, also den ersten Buchstaben groß schreiben, Unterstriche durch Leerzeichen ersetzen, Übersetzung von Namensräumen und dergleichen. Dies geschieht automatisch bei allen Query-Modulen. Normalisieren eines Seitentitels

Fehlende Seiten und ungültige Titel[edit]

Titel, deren Seiten nicht existieren oder die ungültig sind, erscheinen trotzdem in der Antwort im Abschnitt <pages>, aber ihnen wird der Parameter missing="" (fehlt) oder invalid="" (ungültig) angehängt. In Ausgabeformaten, die numerische Arrayschlüssel unterstützen (JSON oder PHP serialisiert), bekommen solcherlei ungültige oder fehlende Artikel negative Seiten-IDs. Query-Module ignorieren in der Regel ungültige/fehlende Seiten, da sich mit diesen keine sinnvolle Abfrage gestalten lässt. Ein fehlender, ein ungültiger und ein existierender Titel im Format JSON

Weiterleitungen auflösen[edit]

Weiterleitungen können automatisch aufgelöst werden, so dass das Ziel der Weiterleitung anstelle des gegebenen Titels zurückgegeben/ in der Abfrage genutzt wird. Das folgende Beispiel ist nicht wirklich sinnvoll, weil es keines der möglichen Abfrage-Module nutzt, aber es zeigt, wie der redirects-Parameter funktioniert. Sowohl die Normalisierung als auch die Weiterleitungsauflösung können auftreten. Bei doppelten Weiterleitungen wird bis zum "Ziel-Artikel" aufgelöst, zirkuläre Weiterleitungen (siehe nächster Absatz) können dazu führen, dass keine Seite im Antwort-Abschnitt <pages> zu finden sind.

Benutzung des "redirects"-Parameter. "Hauptseite" ist eine Weiterleitung nach "Wikipedia:Hauptseite"

Die gleiche Abfrage ohne den Parameter "redirects"

Ohne "redirects" kann man auch "prop=info" benutzen, um Weiterleitungen zu erkennen

Zirkuläre Weiterleitungen[edit]

Für das folgende Beispiel wird angenommen, es existieren die Weiterleitungen Seite1 → Seite2 → Seite3 → Seite1, also ein Ringschluss. Weiterhin verwenden wir mit Absicht einen nicht-normalisierten Seitennamen "seite1": Circular redirect behavior

Man beachte besonders das Fehlen eines Antwort-Abschnitts <pages>.

Begrenzungen[edit]

Alle Abfragen (insbesondere die Listen) liefern nur eine begrenzte Anzahl an Ergebnissen in einer Antwort. Die Grenze liegt standardmäßig bei 10 Ergebnissen, und kann bei den meisten Abfragen auf 500 für "normale" Benutzer bzw. 5000 für Bots und Administratoren (bzw. Benutzer mit dem apihighlimits-Recht) gesetzt werden. Weiterhin können einzelne Module die erlaubte Anzahl an Ergebnissen noch weiter einschränken.

Falls nicht klar ist, welches Limit grade für eine Abfrage gilt bzw. möglich ist, kann man auch als Wert max einsetzen. In diesem Fall wird zusätzlich ein Abfrage-Abschnitt <limits> mit zurückgegeben, in welchem das verwendete Limit spezifiziert wird.

Fehler[edit]

Wenn man den limit-Wert in einer Abfrage zu hoch setzt, wird ein Fehler wie der folgende zurückgegeben:

  • code: aplimit
    • info: aplimit may not be over 500 (set to 1000) for users
    • Deutsch: aplimit darf bei Benutzern nicht höher sein als 500 (gegeben: 1000) (Der Präfix ap wird in der Fehlermeldung durch den Präfix des meldenden Moduls ausgetauscht).

Beispiel[edit]

Frage die maximale Anzahl von Versionen (mit Inhalt) und die Backlinks für de:Goethe ab

Abfragen fortsetzen[edit]

Häufig muss man Abfragen fortsetzen, weil (auch wegen der erwähnten Begrenzungen) nicht alle möglichen Ergebnisse bereits geliefert wurden. Hierzu gibt es bei unvollständigen Abfragen den Abschnitt query-continue. Unvollständige Abfrage

Hier kann man dann den Parameter acfrom=Liste der Kathedralen in Frankreich benutzen, um den nächsten Block an Ergebnissen zu bekommen: Unvollständige Abfrage mit Fortsetzung

Generatoren[edit]

Einige Query-Module lassen sich als Generatoren (oder Titellisten-Erzeuger) einsetzen (dies ist bei den entsprechenden Modulen extra vermerkt). Mit diesen Generatoren kann man andere Query-Module ansteuern, wobei die Ausgabe des Generators den Parameter titles=, revids= oder pageids= ersetzt. Es ist nur ein Generator je Abfrage erlaubt (eine Verschachtelung von Generatoren ist also nicht möglich).

Parameter, die an den verwendeten Generator weitergeleitet werden sollen, muss ein 'g' vorangestellt werden, also zum Beispiel bei generator=backlinks statt bltitle dann gbltitle.

Es ist weiterhin zu beachten, dass Generatoren selber keine Ausgabe erzeugen, sondern lediglich die Seitenliste für die "übergeordnete" Abfrage festlegen - Parameter wie gcmprop bleiben ohne Effekt.

Beispiel[edit]

Als Beispiel die Nutzung von generator=allpages: Frage Links und Kategorien für die ersten drei Seiten ab, die mit Ba beginnen

Weitere Beispiele für Generatoren finden sich bei den einzelnen Listen-Abfragen.