XML-Schnittstelle

Aus SamsWiki
Zur Navigation springen Zur Suche springen

Um eine Bereitstellung aktueller Spielbetriebsdaten für Presse und Vereine zu ermöglichen, wurde für SAMS eine XML-Schnittstelle entwickelt.

Zugriffsschlüssel

Um die Schnittstelle zu verwenden, ist ein individueller Zugriffsschlüssel (API-Key) nötig, der vom jeweiligen Verband vergeben wird. Fordern Sie den Key bitte von der zentralen Support-Adresse Ihres Verbandes ab.

Abfrage-Limit

HINWEIS - UPDATE: Um den Service der XML-Schnittstelle zu gewährleisten unterliegt das Abfragen der Schnittstelle einem allgemeinen Rate-Limit. Dieses Limit gilt für alle Clients und alle Schnittstellen und liegt bei 5 Anfragen pro Sekunde. Das heißt, dass zwischen den Abfragen jeweils 200ms verstreichen müssen. Wird diese Spanne unterschritten, werden die Anfragen abgelehnt.

Die Anzahl der Zugriffe pro Tag und Schlüssel ist begrenzt, um den Server vor versehentlicher Überlastung zu schützen. Um Tabellendaten beispielsweise auf einer eigenen Vereinsseite einzublenden, müssen diese zwischengespeichert werden, anstatt sie bei jedem Seitenaufruf neu über die Schnittstelle zu laden. Wird die Anzahl der Zugriffe pro Tag überschritten, ist der Schlüssel bis zum nächsten Tag gesperrt.

Damit dennoch ein zeitnahes Abrufen von aktuellen Spielergebnissen ermöglicht werden kann, enthält die Spielrundenübersicht für jede Liga die Parameter <structureUpdated> und <resultsUpdated>, die den Zeitpunkt der letzten Änderung an der Struktur (Spielpan, Termine, etc.) beziehungsweise an den Ergebnissen enthalten. Erst wenn sich dieser Zeitpunkt ändert, sollten die entsprechenden Abfragen durchgeführt und lokal zur weiteren Verwendung abgespeichert werden.

Abfragen

Sämtliche Abfragen sind über das Schema https://<verbandsadresse>/xml/<abfrage>.xhtml?apiKey=<API-Key>&parameter1=wert1&... erreichbar. Die Adressen lauten:

-- Bundesliga --

-- DVV Ligen --

-- Landesverbände --

-- International --


Beispielsweise also https://www.volleyball-bundesliga.de/xml/rankings.xhtml?apiKey=XXXXXXXXXXXXXXXXXXXXXX&matchSeriesId=12345 zum Abrufen der Tabellen der Spielrunde mit ID 12345.

Der Paramter "apiKey" ist für alle Anfragen nötig. Weitere Parameter sind von der Abfrageart abhängig und werden weiter unten erläutert.

Achtung: Der Internet-Explorer zeigt den Inhalt der XML-Dateien nicht an! Um die Abfragen zu testen, sollte ein anderer Browser verwendet werden.

Saisonübersicht

Zeigt eine Liste aller verfügbaren Saisons an. Die ID der Saison kann in der Spielrundenübersicht verwendet werden, um Zugriff auf historische Daten zu erhalten.

URL: https://<verbandsadresse>/xml/seasons.xhtml
Beispiel-URL: https://www.volleyball-bundesliga.de/xml/seasons.xhtml?apiKey=XXXXXXXXXXXXXXXXXXXXXX

Keine Parameter.

Spielrundenübersicht

Zeigt eine Liste alle aktuell verfügbaren Ligen und Wettbewerbe an. Hier finden sich auch die IDs (matchSeriesId) der Spielrunden (intern "match series"), die für die weiteren Abfragen relevant sind. Die Spielrunden-ID ist saisonabhängig, um den Abruf von Daten aus alten Saisons zu ermöglichen. Seit Januar 2016 ist zudem eine allSeasonMatchSeriesId verfügbar, die saisonübergreifend ist. Wird diese ID zum Abruf der Schnittstellen verwendet, werden immer Daten der Spielrunde aus der jeweils aktuellen Saison zurückgegeben. Die saisonübergreifenden IDs sind als UUID hinterlegt und somit über alle SAMS-Datenbanken hinweg eindeutig.

Weiterhin hervorzuheben sind die Parameter <structureUpdated> und <resultsUpdated>, die den Zeitpunkt der letzten Änderung an der Struktur (Spielpan, Termine, etc.) beziehungsweise an den Ergebnissen enthalten. Erst wenn sich dieser Zeitpunkt ändert, sollten die entsprechenden Abfragen durchgeführt und lokal zur weiteren Verwendung abgespeichert werden. Um diese Vorgehensweise zu fördern, gibt es kein Aufruflimit bei der Abfrage der Spielrundenübersicht.

In dieser Schnittstelle wird zusätzlich die hierarchische Struktur jeder Liga ausgegeben. Jede Spielrunde ist einer Hierarchie zugeordnet; jede Hierarchie kann mehrere Spielrunden sowie weitere untergeordnete Hierarchien enthalten. Die Hierarchien werden von jedem Verband frei definiert und dienen der organisatorischen Strukturierung der Spielrunden. Im direkt zugeordneten Element <hierarchy> ist die direkte Hierarchie der Liga hinterlegt. Im Element <fullHierarchy> finden sich alle Hierarchien, denen diese Liga untergeordnet ist. Jedes <hierarchy>-Element besitzt einen <hierarchyLevel>, der die Anzahl der übergeordneten Hierarchien angibt. Hierarchien mit <hierarchyLevel>0</hierarchyLevel> besitzen keine weiteren übergeordneten Hierarchien.

URL: https://<verbandsadresse>/xml/matchSeries.xhtml
Beispiel: https://www.volleyball-bundesliga.de/xml/matchSeries.xhtml?apiKey=XXXXXXXXXXXXXXXXXXXXXX

optionale Parameter:

  • seasonId - Zeigt alle Spielrunden einer bestimmten Saison (Bsp.: seasonId=12345)

Mannschaftsliste

Erzeugt eine Liste alle Mannschaften einer Liga. Achtung: Die Mannschafts-ID ist saisonabhängig!

URL: https://<verbandsadresse>/xml/teams.xhtml
Beispiel: https://www.volleyball-bundesliga.de/xml/teams.xhtml?apiKey=XXXXXXXXXXXXXXXXXXXXXX&matchSeriesId=12345

nötige Parameter:

  • matchSeriesId - Begrenzt die Liste der Mannschaften auf eine bestimmte Spielrunde (Bsp.: matchSeriesId=12345)
    • alternativ: allSeasonMatchSeriesId - saisonübergreifende Spielrunden-ID (Bsp.: allSeasonMatchSeriesId=012bfd2f-ad4a-40f5-8cef-a88e6a27a3aa)

Spielplan und Ergebnisse

Erzeugt eine Liste aller Spiele für eine Spielrunde, Mannschaft und/oder in einem bestimmten Zeitraum.

URL: https://<verbandsadresse>/xml/matches.xhtml
Beispiel: https://www.volleyball-bundesliga.de/xml/matches.xhtml?apiKey=XXXXXXXXXXXXXXXXXXXXXX&before=2012-03-01&after=2012-02-01

optionale Parameter:

  • matchSeriesId - Id einer Spielrunde (Bsp.: matchSeriesId=12345)
    • alternativ: allSeasonMatchSeriesId - saisonübergreifende Spielrunden-ID (Bsp.: allSeasonMatchSeriesId=012bfd2f-ad4a-40f5-8cef-a88e6a27a3aa)
  • teamId - Id einer Mannschaft (Bsp.: teamId=12345)
  • before - Datum im Format tt.mm.jjjj oder jjjj-mm-tt, vor dem die Spiele liegen sollen (Bsp.: before=31.01.2012)
  • after - Datum im Format tt.mm.jjjj oder jjjj-mm-tt, nach dem die Spiele liegen sollen, Standardwert ist Saisonbeginn (Bsp.: after=2011-12-01)
  • past - Überschreibt before und zeigt alle Spiele aus der Vergangenheit, wenn der Parameter "true" ist. (Bsp.: past=true)
  • future=true - diesen Parameter nutzen Sie für die Anzeige zukünftiger Spiele und in Verbindung mit dem Parameter limit=nummerischer Wert begrenzen Sie die Anzahl der Ausgabe (Bsp.: future=true&limit=3, weist die nächsten 3 Spiele aus)


Sind weder matchSeriesId noch teamId gegeben, dürfen before und after nicht weiter als 31 Tage auseinander liegen.

Tabellen

Gibt die aktuelle Tabelle einer Liga oder eines Wettbewerbs aus.

URL: https://<verbandsadresse>/xml/rankings.xhtml
Beispiel: https://www.volleyball-bundesliga.de/xml/rankings.xhtml?apiKey=XXXXXXXXXXXXXXXXXXXXXX&matchSeriesId=12345

benötiger Parameter:

  • matchSeriesId - Id einer Spielrunde (Bsp.: matchSeriesId=12345)
    • alternativ: allSeasonMatchSeriesId - saisonübergreifende Spielrunden-ID (Bsp.: allSeasonMatchSeriesId=012bfd2f-ad4a-40f5-8cef-a88e6a27a3aa)

Vereine

Gibt eine Übersicht aller Vereine mit wichtigen Informationen aus.

URL: https://<verbandsadresse>/xml/sportsclubList.xhtml
Beispiel: https://www.volleyball-bundesliga.de/xml/sportsclubList.xhtml?apiKey=XXXXXXXXXXXXXXXXXXXXXX

benötiger Parameter:

  • keine

Verein (detailliert)

Gibt detaillierte Informationen zu einem bestimmten Verein aus.

URL: https://<verbandsadresse>/xml/sportsclub.xhtml
Beispiel: https://www.volleyball-bundesliga.de/xml/sportsclub.xhtml?apiKey=XXXXXXXXXXXXXXXXXXXXXX&sportsclubId=12345

benötiger Parameter:

  • sportsclubId - Id eines vorhandenen Vereins (Bsp.: sportsclubId=12345)

Anwendungsbeispiele

Download per Cronjob (Linux)

Folgender Eintrag in der /etc/crontab bewirkt einen Download der Spieltabellen der Spielrunde mit Id 123456 der DVL nach '/tmp/matches.xml' alle zwei Stunden: 

 10 */2    * * *   root    curl -s 'https://www.volleyball-bundesliga.de/xml/matches.xhtml?apiKey=XXXXXXXX&matchSeriesId=123456' >/tmp/matches.xml

Steht kein Zugang zum Erstellen von Cronjobs zur Verfügung, können diese auch über externe Anbieter wie https://www.cronjob.de/ realisiert werden. In diesem Fall wird von dem Anbieter ein eigenes Script aufgerufen, was wiederum die XML-Schnittstelle von SAMS abfragt.

Einlesen und Ausgabe in PHP

Die heruntergeladene Datei lässt sich auf folgende einfache Weise in PHP zur Ausgabe verwenden: 

$matches = simplexml_load_file("/tmp/matches.xml");
foreach ( $matches->match as $match) {
  print("<li>" . $match->date . ": " . $match->team[0]->name . " vs " . $match->team[1]->name . "</li>");
}

Hiermit wird zu jedem Spiel Datum und Spielpaarung ausgegeben. Die Bezeichnung der jeweiligen Variablen entsprechen denen in der XML-Datei.

Download und Transformation in das alte DVL-Format (Linux)

Mit Hilfe des Programms xsltproc lässt sich die Transformation bequem beim Abrufen der Schnittstelle durchführen und das umgewandelte Ergebnis lokal speichern. Die Methode wird jedoch nicht mehr aktiv unterstützt und wir bei Schnittstellenänderungen unter Umständen nicht mehr funktionieren. 

 xsltproc 'https://www.volleyball-bundesliga.de/xml/matches_dvl.xslt' 'https://www.volleyball-bundesliga.de/xml/matches.xhtml?apiKey=XXXXXXXX&matchSeriesId=123456' > /tmp/ergebnisse.xml

Per Cron-Job kann das analog zum ersten Beispiel auch periodisch ausgeführt werden.

Abgerufen von „http://wiki.sams-server.de/w/index.php?title=XML-Schnittstelle&oldid=13457“