API:Query/de

From MediaWiki.org
Jump to: navigation, search
Tools clipart.png Diese Seite ist Teil der MediaWiki-API-Dokumentation.
Sprache: English  • Deutsch • español • فارسی • 日本語 • русский • 中文
MediaWiki API



Schnellübersicht:

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 | edit source]

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 | edit source]

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

api.php?action=query&titles=Project:articleA|article_B
Result 
<api>
  <query>
    <normalized>
      <n from="Project:articleA" to="Wikipedia:ArticleA" />
      <n from="article_B" to="Article B" />
    </normalized>
    <pages>
      <page ns="4" title="Wikipedia:ArticleA" missing="" />
      <page ns="0" title="Article B" missing="" />
    </pages>
  </query>
</api>

Fehlende Seiten und ungültige Titel[edit | edit source]

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

api.php?action=query&titles=Gibtsnicht|Wikipedia:Hauptseite|Diskussion:&format=jsonfm
Result 
{
	"query": {
		"pages": {
			"-2": {
				"ns": 0,
				"title": "Gibtsnicht",
				"missing": ""
			},
			"-1": {
				"title": "Diskussion:",
				"invalid": ""
			},
			"2929929": {
				"pageid": 2929929,
				"ns": 4,
				"title": "Wikipedia:Hauptseite"
			}
		}
	}
}

Weiterleitungen auflösen[edit | edit source]

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"

api.php?action=query&titles=Hauptseite&redirects
Result 
<?xml version="1.0"?>
<api>
  <query>
    <redirects>
      <r from="Hauptseite" to="Wikipedia:Hauptseite" />
    </redirects>
    <pages>
      <page pageid="2929929" ns="4" title="Wikipedia:Hauptseite" />
    </pages>
  </query>
</api>

Die gleiche Abfrage ohne den Parameter "redirects"

api.php?action=query&titles=Hauptseite
Result 
<?xml version="1.0"?>
<api>
  <query>
    <pages>
      <page pageid="3785030" ns="0" title="Hauptseite" />
    </pages>
  </query>
</api>

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

api.php?action=query&titles=Hauptseite&prop=info
Result 
<?xml version="1.0"?>
<api>
  <query>
    <pages>
      <page pageid="3785030" ns="0" title="Hauptseite" touched="2008-09-23T13:10:02Z" lastrevid="49852768" counter="0" length="34" redirect="" new="" />
    </pages>
  </query>
</api>

Zirkuläre Weiterleitungen[edit | edit source]

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

api.php?action=query&titles=seite1&redirects
Result 
<?xml version="1.0" encoding="utf-8"?>
<api>
  <query>
    <normalized>
      <n from="seite1" to="Seite1" />
    </normalized>
    <redirects>
      <r from="Seite1" to="Seite2" />
      <r from="Seite2" to="Seite3" />
      <r from="Seite3" to="Seite1" />
    </redirects>
  </query>
</api>

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

Begrenzungen[edit | edit source]

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 | edit source]

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 | edit source]

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

api.php?action=query&titles=Goethe&prop=revisions&rvlimit=max&rvprop=content&list=backlinks&bltitle=Goethe&bllimit=max
Result 
<?xml version="1.0" encoding="utf-8"?>
 
You are looking at the HTML representation of the XML format.
HTML is good for debugging, but probably is not suitable for your application.
See complete documentation, or API help for more information.
 
<?xml version="1.0"?>
<api>
  <query>
    <pages>
      <page pageid="2136366" ns="0" title="Goethe">
        <revisions>
          <rev>#REDIRECT [[Johann Wolfgang von Goethe]]</rev>
          <rev>#REDIRECT [[Goethe (Begriffsklärung)]]</rev>
          <rev>#REDIRECT [[Johann Wolfgang von Goethe]]</rev>
          <rev>#REDIRECT [[Goethe (Begriffsklärung)]]</rev>
          <rev>#REDIRECT [[Johann Wolfgang von Goethe]]</rev>
          <rev>#REDIRECT [[Goethe (Begriffsklärung)]]</rev>
        </revisions>
      </page>
    </pages>
    <backlinks>
      <bl pageid="1782" ns="0" title="Fremdwort" />
      <bl pageid="2497" ns="0" title="Johann Gottlieb Fichte" />
      <bl pageid="2648" ns="0" title="Köln" />
      <bl pageid="2792" ns="0" title="Kultur" />
      <bl pageid="2979" ns="0" title="Leonardo da Vinci" />
      <bl pageid="3062" ns="0" title="Ludwigshafen am Rhein" />
      <bl pageid="3187" ns="0" title="Melodram (Theater)" />
      <bl pageid="4359" ns="0" title="Richard Wagner" />
      <bl pageid="4700" ns="0" title="Sprache" />
      <!-- Gekürzt, hier standen 500 Backlinks -->
      <bl pageid="1790794" ns="5" title="Wikipedia Diskussion:WikiProjekt Kategorien/Einordnung von Kategorien" />
      <bl pageid="449913" ns="6" title="Bild:Goethe.GIF" />
      <bl pageid="679339" ns="6" title="Bild:Kupfer zu J. W. Goethe, Das römische Carneval.jpg" />
      <bl pageid="679351" ns="6" title="Bild:Die tote Ottilie, der Architekt und Nanny.jpg" />
      <bl pageid="679354" ns="6" title="Bild:Goethes Wohnhaus am Frauenplan, 1828.jpg" />
      <bl pageid="680308" ns="6" title="Bild:Goethe, Italienische Küstenlandschaft - Aquarellierte Federzeichnung.jpg" />
      <bl pageid="1447515" ns="100" title="Portal:Ilm-Kreis" />
    </backlinks>
  </query>
  <limits revisions="50" backlinks="500" />
  <query-continue>
    <backlinks blcontinue="0|Goethe|1838391" />
  </query-continue>
</api>

Abfragen fortsetzen[edit | edit source]

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

api.php?action=query&list=allcategories&acprefix=Liste%20der
Result 
<?xml version="1.0"?>
<api>
  <query-continue>
    <allcategories acfrom="Liste der Kathedralen in Frankreich" />
  </query-continue>
  <query>
    <allcategories>
      <c>Liste der Berge im Altai</c>
      <c>Liste der Burgen, Schlösser und Festungen in Frankreich</c>
      <c>Liste der Entscheidungen des Obersten Gerichtshofs der Vereinigten Staaten</c>
      <c>Liste der Fernsehsender</c>
      <c>Liste der Fernsehsender (Schweiz)</c>
      <c>Liste der Fluggesellschaften</c>
      <c>Liste der Gemeinden im Département Loire-Atlantique</c>
      <c>Liste der Herrscher</c>
      <c>Liste der Herrscher (Namen)</c>
      <c>Liste der Kardinalskreierungen</c>
    </allcategories>
  </query>
</api>

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

api.php?action=query&list=allcategories&acprefix=Liste%20der&acfrom=Liste%20der%20Kathedralen%20in%20Frankreich
Result 
<?xml version="1.0"?>
<api>
  <query-continue>
    <allcategories acfrom="Liste der Söhne und Töchter der Stadt Mannheim" />
  </query-continue>
  <query>
    <allcategories>
      <c>Liste der Kathedralen in Frankreich</c>
      <c>Liste der Mitglieder des Bayerischen Landtages (15. Wahlperiode)</c>
      <c>Liste der Musikhochschulen und Konservatorien in Deutschland</c>
      <c>Liste der Naturdenkmäler im Landkreis Rhön-Grabfeld</c>
      <c>Liste der Nummer-Eins-Hits in Deutschland</c>
      <c>Liste der Olympiasieger im Handball</c>
      <c>Liste der Plattenlabels</c>
      <c>Liste der Reichstagsabgeordneten der Weimarer Republik</c>
      <c>Liste der Schwimmweltrekorde</c>
      <c>Liste der Sinfonien</c>
    </allcategories>
  </query>
</api>

Generatoren[edit | edit source]

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 | edit source]

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

api.php?action=query&generator=allpages&gaplimit=3&gapfrom=Ba&prop=links|categories
Result 
<?xml version="1.0"?>
<api>
  <query-continue>
    <allpages gapfrom="Ba&#039;al Shem Tov" />
  </query-continue>
  <query>
    <pages>
      <page pageid="43766" ns="0" title="Ba">
        <links>
          <pl ns="0" title="BA" />
        </links>
      </page>
      <page pageid="845878" ns="0" title="Ba&#039;Game">
        <links>
          <pl ns="0" title="Einwohner" />
          <pl ns="0" title="Kirkwall" />
          <pl ns="0" title="Norwegen" />
          <pl ns="0" title="Orkney" />
          <pl ns="0" title="Orkneyinga saga" />
          <pl ns="0" title="Perthshire" />
          <pl ns="0" title="Spiel" />
          <pl ns="0" title="Team" />
        </links>
        <categories>
          <cl ns="14" title="Kategorie:Orkneyinseln" />
          <cl ns="14" title="Kategorie:Religion (Vereinigtes Königreich)" />
          <cl ns="14" title="Kategorie:Sport (Schottland)" />
        </categories>
      </page>
      <page pageid="861615" ns="0" title="Ba&#039;al">
        <links>
          <pl ns="0" title="Baal (Gott)" />
        </links>
      </page>
    </pages>
  </query>
</api>

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

Retrieved from "http://www.mediawiki.org/w/index.php?title=API:Query/de&oldid=584072"