API:Tutorial/de

In diesem Tutorial lernst du die MediaWiki Action API kennen, wie du sie benutzt, das Anfragen-Format, eine einfache Abfrage und Beispiele von Projekten, welche die Action API verwenden.

Durchsuche Toolforge nach Demo-Apps

Übersicht über die MediaWiki Action API

Die MediaWiki Action API ist ein REST-Webservice, der es Benutzern ermöglicht, bestimmte Wiki-Aktivitäten wie Seitenerstellung, Authentifizierung, Parsing, Suchen, etc. auszuführen. API:Main page ist ein guter Ausgangspunkt, um die API zu verstehen.

Dein Programm sendet Abfragen an die API, um Zugriff auf Wiki-Funktionen zu erhalten. Zum Beispiel bei einem Wiki anmelden, eine Seite erstellen und bearbeiten, nach einem Titel suchen, nach Inhalt suchen oder Inhalt parsen. Die Action API ist für dritte Entwickler, Entwickler von Wikimedia-Erweiterungen und Administratoren von Wiki-Seiten verfügbar.

Auf der rechten Seitenleiste dieser Seite befinden sich viele Funktionen, die von der API unterstützt werden, nach Kategorien zusammengefasst. Bevor du Abfragen an einen Wiki-Server sendest, lese zunächst die Übersichtsseiten wie Datenformate, Fehler und Warnungen und die Action API FAQ.

Wie die MediaWiki Action API verwendet wird

Du kannst clientseitig über HTTP Daten vom Server anfordern und die Antwort in einem Standardformat erhalten (typischerweise JSON). Eine Abfrage besteht aus einem Endpunkt und einer Reihe von Parametern. Es können zwei Abfragetypen gestellt werden: GET und POST. Bei einer GET-Abfrage würde ein Parameter eine Abfrage-Zeichenkette in der URL enthalten. Für eine POST-Abfrage formatiere die Parameter im Format JSON.

Anfragen-Format

Request format

Alle Wikimedia-Wikis haben Endpunkte im Format http://example.org/w/api.php. Nutze den entsprechenden Endpunkt, um auf der Hauptseite von MediaWiki oder der englischsprachigen Wikipedia zu agieren. Zum Beispiel findet sich die englischsprachige Wikipedia auf $2. Nutze den Test-Wiki-Endpunkt $3, um neue Konten oder das Bearbeiten von Seiten zu testen. To operate on the MediaWiki main site or English Wikipedia, use the related endpoint. For example, the English Wikipedia is at https://en.wikipedia.org/w/api.php. For testing new accounts or test edits to pages, use the test wiki endpoint https://test.wikipedia.org/w/api.php.

Füge den Parameter action zur Abfrage-Zeichenkette in der URL hinzu. Er sagt der API, welche Aktion sie ausführen soll. Die bekannteste Aktion ist $2 (die URL würde $3 enthalten, was es ermöglicht, Daten aus einem Wiki zu erhalten. Gib nach dem Parameter $4 einen anderen Parameter an, um anzugeben, welchen der drei Abfragemodul-Typen nutzen möchtest: It tells the API which action to perform. The most popular action is query (the URL would contain action=query), which allows fetching data from a wiki. Following the action parameter, add another parameter to indicate which one of the three query module types you want to perform:

• prop – Eigenschaften von Seiten erhalten  
• list – Liste von Seiten erhalten, die ein bestimmtes Kriterium erfüllen
• meta – Metainformationen über das Wiki und seine Benutzer erhalten

Schließe dann noch den Parameter format ein, der der API sagt, in welchem Format die Ergebnisse erhalten werden sollen. Das empfohlene Format ist JSON. Die API hat in der Vergangenheit andere Ausgabeformate unterstützt, die jedoch nicht allgemein empfohlen werden. The recommended format is JSON. The API has supported other output formats in the past, but they are not generally recommended.

Eine einfache Abfrage

Lass uns eine einfache Abfrage als Beispiel nehmen, um zu verstehen, wie eine typische GET-Abfrage und die Antwort im Kontext der Action API aussehen würden.

Lass uns nach einem Titel in einem Wiki suchen. Wir werden das auf API:Suche dokumentierte Modul search nutzen.

GET-Anfrage

Um nach einem Seitentitel oder Inhalt, der mit Craig Noone übereinstimmt, zu suchen, würde die URL für die HTTP-GET-Abfrage so aussehen:

api.php?action=query&list=search&srsearch=Craig%20Noone&format=json [In der ApiSandbox ausprobieren]

Erklärung von jedem Teil der URL:

• http://en.wikipedia.org/w/api.php – $1 ist der Haupt-Endpunkt. In diesem Fall ist es die englischsprachige Wikipedia.
• action=query – $1 steht für den Erhalt von Daten aus einem Wiki.
• list=search – $1 steht dafür, eine Liste von Seiten, die ein Kriterium erfüllen, zu erhalten.
• srsearch=Craig%20Noone – $1 gibt den Seitentitel oder Inhalt an, nach dem gesucht wird. Das $2 steht für ein Leerzeichen in einer URL. The %20 indicates a space character in a URL.
• format=json – $1 gibt JSON-Ausgabe vor, was das empfohlene Ausgabeformat ist.

Antwort

Die Antwort ist ein Dokument im Format JSON mit einer Liste von Seitentiteln, die mit Craig Noone übereinstimmen:

{
    "batchcomplete": "",
    "continue": {
        "sroffset": 10,
        "continue": "-||"
    },
    "query": {
        "searchinfo": {
            "totalhits": 210
        },
        "search": [
            {
                "ns": 0,
                "title": "Craig Noone",
                "pageid": 18846922,
                "size": 22548,
                "wordcount": 1771,
                "snippet": "<span class=\"searchmatch\">Craig</span> Stephen <span class=\"searchmatch\">Noone</span> (born 17 November 1987) is an English professional footballer who plays as a winger for Bolton Wanderers. Born in Kirkby, he has also",
                "timestamp": "2018-11-02T22:25:45Z"
            },
            {
                "ns": 0,
                "title": "Noone",
                "pageid": 32906333,
                "size": 553,
                "wordcount": 64,
                "snippet": "<span class=\"searchmatch\">Noone</span> is a surname that may refer to:  <span class=\"searchmatch\">Craig</span> <span class=\"searchmatch\">Noone</span> (born 1987), English football midfielder Jimmie <span class=\"searchmatch\">Noone</span> (1895–1944), American jazz clarinetist Kathleen",
                "timestamp": "2015-08-16T05:16:17Z"
            }
            ...
        ]
    }
}

Beispiele von Projekten, die die Action API nutzen

Einige Beispiele von Projekten in Wikimedia, die die Action API nutzen:

• Wikipedia iOS-App, die eine Funktion enthält, um nach Wiki-Seiten in deiner Nähe zu suchen.
• Bots, die auf einem Wiki laufen. Pywikibot ist ein Bot-Framework in Python, das mit der MediaWiki API interagiert und von vielen Bot-Entwicklern genutzt wird.
• API-Nutzung zur Visualisierung von Daten, die aus einem Wiki erhalten werden. Dazu gehört Neat Visualization, das Bearbeitungen auf Wikipedia in Echtzeit anzeigt.

Zusätzliche Anmerkungen

• Viele Seiten nutzen MediaWiki. Sie können alle unterschiedliche Versionen von MediaWiki und somit auch der API nutzen. Manche Modul-Parameter, die in einer Version unterstützt werden, können in anderen Versionen missbilligt oder entfernt worden sein. Darüber kannst du in der jeweiligen Modul-Dokumentation über das [$2 API-Hilfe-Modul] mehr erfahren. They might all be running a different version of MediaWiki and in turn the API. Some module parameters supported in one version might be deprecated or removed in others. You could learn about that in each module's documentation via API help module.
• Wenn du viele API-Abfragen stellen möchtest und vielleicht sehr aufwendige und aktive Bots betreibst, sprich mit den Wiki-Admins, damit sie dich nicht sperren. Siehe die Liste von Administratoren von Wikimedia-Projekten. Lese mehr zu diesem Thema auf $2. See list of Administrators of Wikimedia projects. Read more about this topic on API:Etikette .
• Alle Aktionen, die Daten verändern, wie Logbücher, Bearbeitungen oder Verschiebungen einer Seite, sowie das Beobachten oder Kontrollieren von Änderungen erfordern Tokens. Du musst Tokens über API:Tokens erhalten, ehe du fortfahren kannst.

Ressourcen

• Nutze Special:APISandbox, um die Action API auszuprobieren. Du kannst mit unterstützten Aktionen spielen, einen Wert für Parameter angeben und Abfragen an die API senden, um das Ergebnis auf der gleichen Seite zu sehen.
• Wikimedia-Dumps, mit denen du lokal arbeiten kannst.
• Lese dir Anleitungen durch: An Introduction to API's und What is REST — A Simple Explanation for Beginners.
• MediaWiki-API-Hilfe bietet eine automatisch generierte Dokumentation aller unterstützten Module.
• API:Main page bietet einen Überblick der Action API.
• Introduction to the MediaWiki API von User:Roan Kattouw (WMF) auf dem San Francisco Hackathon 2012. Diese Anleitung wird durch ein Video begleitet.
• GitHub: MediaWiki-API-Demos