Reporting API und Tokens

Von | 7. August 2012

Daten aus SiteCatalyst kann man auf verschiedenen Wegen analysieren, z.B. in Excel (mittels Excel Client und ReportBuilder), per Data Extract, per Email oder natürlich im normalen Interface. Ein Weg ist anders als die anderen: Die Reporting API erlaubt das Abfragen von SiteCatalyst Daten per Software.

Warum Reporting API?

Generell benutzt man APIs, wenn man mit den Daten hinterher noch was vor hat.

Die überwiegende Mehrheit der Anwendungen fällt in zwei Gruppen:

  1. „Top 10“ Listen auf einer Website und
  2. Dashboards auf großen Bildschirmen.

Erstere werden gerne auf Nachrichtenportalen eingesetzt: SiteCatalyst liefert z.B. alle 30 Minuten eine Liste der 10 beliebtesten Artikel und die Site zeigt diese Liste an. Letzteres sieht man manchmal am Empfang größerer Firmen und oft in Redaktionen oder Entwicklungsabteilungen.

Natürlich kann man auch „kleinere“ Dashboards damit bauen, z.B. ein Icon für den Systray, das je nach aktuellem Traffic grün, gelb oder rot zeigt. Der Clou bei einer API ist, daß man die Daten nicht in einem festgelegten Format bekommt und dann durch ETL jagen muß. Stattdessen stehen die Daten innerhalb eines Programms zur Verfügung und man kann damit prinzipiell tun, was man will.

Der Nachteil: Wenn man die Reporting API nutzen will, muß man programmieren.

Was sind Tokens?

Der Zugriff auf die Daten wird über sogenannte Tokens abgerechnet. Die meisten Methoden der API „kosten“ ein Token beim Aufruf. Einige kosten mehr als ein Token (einige Methoden der Datawarehouse API), andere gar keins.

Der häufigste Anwendungsfall (einen Report ziehen) kostet 2 Token: 1 für die Anforderung und 1 beim eigentlichen Laden der Daten.

Als Teil des normalen SiteCatalyst Vertrages hat jeder Account 10000 Token pro Kalendermonat, jeder Kunde kann also etwa 5000 Reports pro Monat aus der API herunterladen, ohne daß weitere Kosten entstehen. Wer mehr braucht, kann sich an seinen Account Manager oder Account Exec wenden.

Seit Adobe Analytics gibt es keine Token mehr und daher praktsich keine Limits. Falls die Server höher ausgelastet sein sollten, reduzieren sie die Bandbreite, Reports würden dann also länger benötigen.

Die neue Vorgabe ist daher auch: Lieber viele, kleinere Abfragen als eine große.

Einstiegshürden

Wer Daten aus der Reporting API laden möchte, muß vier Schritte programieren:

  1. In die Reporting API einloggen
  2. Eine Reportdefinition anlegen und der API senden
  3. Warten bis der Report fertig ist
  4. Daten des Reports laden

Meiner Erfahrung nach sind die ersten zwei Schritte aus Sicht eines Programmierers am schwierigsten, das Einloggen wegen der komplexen Security und das Anlegen der Reportdefinition weil kaum ein Programmierer SiteCatalyst kennt.

Einloggen in die Reporting API

Die Reporting API benutzt zur Authentifizierung ein Verfahren namens „UsernameToken“ (Spec als PDF).

Dieses Verfahren läßt sich am einfachsten in PHP nutzen. Ich persönlich benutze Java (und ein Dutzend JARs). Auch mit C# und WSE 3.0 sollte man sich einloggen können (siehe MSDN), und natürlich mit aktuellen Technologien aus dem Hause Microsoft.

Wer mit Java nicht weiterkommt kann sich mal How to Access a Report Suite using Java and Web Services ansehen.

Reportdefinition

Die Reporting API stellt im Prinzip genau die Daten zur Verfügung, die man auch in SiteCatalyst sieht. Ausnahmen sind z.B. Pathing und grafische Reports wie die Geo-Reports, die es nur in SiteCatalyst gibt, nicht jedoch in der Reporting API.

Welche Daten genau man per Reporting API herunterlädt bestimmt man über die Reportdefinition, die man dem System übergibt.

Aus Sicht des Programmierers ist die Frage: Wie genau muß die Reportdefinition aussehen? Was bedeuten die einzelnen Attribute? Welche Metriken und Elemente muß ich benutzen und soll der Report „ranked“, „trended“ oder „overtime“ sein?

Tip: Für die Definition sollten Programmierer und Webanalyst zusammenarbeiten. Ideal ist, wenn der Webanalyst die gewünschten Daten direkt in einem Report in SiteCatalyst zeigen kann. Die Reportdefinition läßt sich dann relativ einfach herleiten.

Komplizierter wird es, wenn man Classifications oder Filter nutzen möchte, das soll aber heute nicht Thema sein.

Nehmen wir uns als Beispiel einfach mal den schon erwähnten „Top 10 Artikel“ Report vor. In SiteCatalyst findet man den z.B. unter Site Content > Pages. Als Metrik kommen Page Views in Frage oder auch Visits oder Visitors.

In der Reporting API Dokumentation finden wir „pageViews“, „visits“ oder „visitors“ für die Metriken und „pages“ für die Elements, die Dimensionen.

Dann müssen wir noch ein Datum oder einen Zeitraum angeben und natürlich die
Report Suite ID!

Wenn wirklich nur die „Top 10“ gebraucht werden, können wir noch das Attribut „top“ auf 10 setzen.

Ein „Top 10“ Report nennt sich im Englischen auch „Top 10 Ranking“, wir wollen also einen „ranked“ Report und nutzen daher die Report.QueueRanked Methode um die Reportdefinition an die Reporting API zu übergeben.

Die Reporting API beginnt nun mit der Bearbeitung des Reports und das Programm muß daher warten. Sinnvollerweise läßt man den Thread ein wenig schlafen und testet dann mit der Report.GetStatus Methode, ob der Report fertig ist, noch berechnet wird, oder ob vielleicht ein Fehler aufgetreten ist.

Als nächstes lädt man dann die Daten mithilfe der Report.GetReport Methode herunter und kann sie dann beliebig weiterbearbeiten.

Hier ist es wieder hilfreich, wenn man die empfangenen Daten mit dem gewünschten Report in SiteCatalyst vergleichen kann, damit man als Programmierer weiß, welche Daten genau wo in der Struktur zu finden sind. Bei Reports mit mehreren Elementen oder Metriken ist das nicht immer einfach zu erkennen.

[Screenshot]

Beispiel: Report in SiteCatalyst

[Screenshot]

Beispiel: Report im Debugger

 

Notizen

Die Reporting API greift exakt auf die selben Daten zu wie SiteCatalyst selber. Ein Report, den man gleichzeitig per API und im Interface aufruft, zeigt also identische Zahlen.

Das bedeutet auch, daß alle Eigenschaften von SiteCatalyst auch für die Reporting API gelten, z.B. betrifft eine Migration von SiteCatalyst 14 nach 15 eben auch die Daten, die per Reporting API geladen werden.

Im Falle der oben genannten „Top 10“ Funktionalität ist es unbedingt sinnvoll, die Resultate zu buffern. Man ruft also nicht bei jedem Seitenaufbau die 10 Berichte aus der Reporting API ab, sondern tut das einmal pro Stunde oder halbe Stunde und speichert sie in einer Datenbank zwischen.

3 Gedanken zu „Reporting API und Tokens

  1. Pingback: SiteCatalyst 15 – Latency « Webanalyse auf Deutsch

  2. Pingback: Pathing « Webanalyse auf Deutsch

  3. Pingback: IP Adressen Nicht Tracken | Webanalyse auf Deutsch

Kommentar verfassen

Diese Website verwendet Akismet, um Spam zu reduzieren. Erfahre mehr darüber, wie deine Kommentardaten verarbeitet werden.