xscDevBlog – LastSharp & Co.

UPDATE 12.12.2008: Veränderungen in den Namespaces von LastFmLib.Net!

Ich habe mich in letzter Zeit viel mit Last.FM beschäftigt, nicht zuletzt wegen meinen beiden Programmen LastSharp und Lea. Aufgrund eines Problems mit letzterem (Tracks/Künstler mit Umlauten machen Schwierigkeiten) habe ich mich ein wenig umgesehen und bin auf eine (angeblich vollständige) Implementierung des Last.FM-APIs in .NET gestoßen: LastFmLib.Net.

Und weil diese Bibliothek wirklich einzigartig einfach zu verwenden ist (obwohl auch hier die Umlaute noch nicht extra betrachtet werden), möchte ich meine Erfahrungen gerne teilen und eine winzige, deutschsprachige Erklärung zu ihrer Verwendung bzw. Anwendung auf das API 2.0 schreiben.

Vorbereitung

Jeder, der den Last.FM-Webservice verwenden will, benötigt zuallererst einen öffentlichen und einen dazugehörigen geheimen API-Schlüssel, den man hier beantragen kann. Da LastFmLib.Net eine Klassenbibliothek für das .NET-Framework ist, wird eine entsprechende Entwicklungsumgebung (z.B. Visual C# Express Edition) benötigt, um damit arbeiten zu können.

Hat man einen öffentlichen und einen geheimen API-Schlüssel (Key und Secret) erhalten, so muss man LastFmLib.Net diese beiden mitteilen. Dies geschieht, indem man das LastFmLib.API20.Settings.AuthData-Objekt neu setzt, in C# beispielsweise:

LastFmLib.General.MD5Hash key
    = new LastFmLib.General.MD5Hash("APIKey", true, Encoding.UTF8);
LastFmLib.General.MD5Hash secret
    = new LastFmLib.General.MD5Hash("APISecret", true, Encoding.UTF8);
LastFmLib.API20.Settings20.AuthData
    = new LastFmLib.API20.Types.AuthData(key, secret, null);

Hat man das nun erledigt, kann man (nach der Authentifizierung) auf die einzelnen API-Methoden zugreifen.

Allgemein: Request schicken

In LastFmLib.Net sind alle Anfragen an das API in Klassen gekapselt. Für jede Art von Anfrage (Request) erstellt man also ein entsprechendes Objekt, startet die Verarbeitung, überprüft ob die Anfrage erfolgreich war und verarbeitet das Ergebnis. Alle Requests befinden sich im Namespace LastFmLib.API20.<Art>, wobei <Art> die entsprechende Obergruppe einer Anfrage ist, z.B. “Auth”, “User”, “Playlists”, etc… Diese Obergruppen sieht man auf der API-Seite fettgedruckt in der Spalte links.

In C# würde das also so aussehen:

LastFmLib.API20.<Art>.<Irgendeine Request> req
    = new LastFmLib.API20.<Art>.<Irgendeine Request>(<notwendige Parameter>);
req.Start();
if (req.Succeeded) {
    // Mach etwas mit dem Ergebnis
} else {
    // Mach etwas mit dem Fehler (req.ErrorMessage)
}

Authentifizierung

Alles beginnt mit der Anmeldung des Users. Bei Last.FM geht dies in drei Schritten vonstatten:

1. Holen des sog. “Tokens”, der sozusagen das Passwort für alle nun kommenden Anfragen darstellt und nur eine begrenzte Zeit gültig ist. Dies geschieht mit der API-Methode getToken():

   LastFmLib.API20.Auth.AuthGetToken req
       = new LastFmLib.API20.Auth.AuthGetToken();
   req.Start();
   if (req.Succeeded) {
       // Token speichern
       LastFmLib.API20.Settings20.AuthData.Token = req.Result;
   } else {
       // Mach etwas mit dem Fehler
   }

2. Zulassung des Programms für den eigenen Last.FM-Account. Hierfür wird der Browser geöffnet, sodass der User sich einloggen und die entsprechende Berechtigung vergeben kann. LastFmLib.Net stellt hierfür auch gleich eine Funktion bereit (1.Parameter: Anwendung unterbrechen, 2. Parameter: Timeout):

   LastFmLib.API20.Settings.AuthData.AskUserToGrantPermissions(false, 0);

3. Holen der Session-Informationen (Benutzername, Session-Key, Subscriber-Status) mit der Methode getSession(token). Achten Sie darauf, dass dieser Schritt auch wirklich erst nach der Bestätigung im Browser ausgeführt wird, ansonsten klappt das Holen der Informationen nämlich nicht.

   LastFmLib.API20.Auth.AuthGetSession sk =
       new LastFmLib.API20.Auth.AuthGetSession(LastFmLib.API20.Settings20.AuthData.Token, false);
   sk.Start();
   if (sk.Succeeded)
   {
       // Session speichern
       LastFmLib.API20.Settings20.AuthData.Session = sk.Result;
   }
   else {
       // Mach etwas mit dem Fehler
   }

Wenn diese drei Schritte erfolgreich ausgeführt wurden, kann man die eigentlichen Anfragen starten, immer nach dem oben genannten Muster.

Beispiel: Playlisten eines Users holen

LastFmLib.API20.User.UserGetPlaylists req =
    new LastFmLib.API20.User.UserGetPlaylists(LastFmLib.API20.Settings20.AuthData.Session.Username);
gp.Start();
if (gp.Succeeded)
{
    foreach (LastFmLib.API20.Types.SimplePlaylist pl in gp.Result) {
        // Playliste verarbeiten
    }
} else {
    // Mach etwas mit dem Fehler
}

Anmerkungen

Der Aktualität halber sollte man nicht die vorgefertigte DLL von der Website des Entwicklers laden, sondern die neuesten Quelldateien aus dem SVN-Verzeichnis, um daraus die letztendliche Bibliothek zu erstellen. Dies geht mithilfe von Subversion und dem Befehl:

svn co https://lastfmlibnet.svn.sourceforge.net/svnroot/lastfmlibnet lastfmlibnet

Eine entsprechende Dokumentation der Klassenbibliothek findet sich auch im SVN-Verzeichnis. Vor allem, wenn man keine Möglichkeit hat, über die Entwicklungsumgebung Informationen zu einzelnen Funktionen zu erhalten (Parametertypen/-anzahl, Rückgabetyp), sollte man sich darin vertiefen.

Mein Programm Lea (ab Version 1.2) ist dank LastFmLib.Net keine große Sache mehr, dafür (hoffentlich) um einiges stabiler und wartungsfreundlicher.

So, ich hoffe, dieses HowTo hat ein wenig geholfen. Weitere Informationen und natürlich auch Support gibt es auf der Website des Entwicklers.