Java-Clientbibliothek verwenden

In diesem Dokument wird beschrieben, wie Sie die Java-Clientbibliothek verwenden, um Google Data API-Anfragen („GData“) zu senden und zurückgegebene Antworten zu interpretieren.

Google stellt eine Reihe von Clientbibliotheken in verschiedenen Programmiersprachen für die Interaktion mit Diensten mit Daten-APIs bereit. Mit diesen Bibliotheken können Sie GData-Anfragen erstellen, an einen Dienst senden und Antworten empfangen.

Dieses Dokument enthält allgemeine Informationen zur Verwendung der Java-Clientbibliothek sowie eine Reihe von Beispielen für gängige Anwendungsfälle.

Für die Verwendung dieser Clientbibliothek ist Java 1.5 erforderlich.

Java-Clientbibliothek herunterladen

In den Beispielen in dieser Anleitung wird auf die Google Calendar API verwiesen. Diese Anleitung ist jedoch keine genaue oder aktuelle Anleitung zur Verwendung der Calendar API. Informationen zur Verwendung der Java-Clientbibliothek mit der Data API eines bestimmten Dienstes finden Sie in der dienstspezifischen Dokumentation. Wenn Sie beispielsweise mit dem Kalender arbeiten, lesen Sie den Entwicklerleitfaden für die Calendar Data API.

Inhalt

  1. Zielgruppe
  2. Übersicht über das Datenmodell
  3. Anleitung und Beispiele
    1. Client erstellen und ausführen
    2. Feed anfordern
    3. Neues Element einfügen
    4. Einen bestimmten Eintrag anfordern
    5. Einträge durchsuchen
    6. Abfrage nach Kategorie
    7. Element aktualisieren
    8. Element löschen
  4. Referenz

Zielgruppe

Dieses Dokument richtet sich an Java-Programmierer, die Clientanwendungen schreiben möchten, die mit GData-Diensten interagieren können.

In diesem Dokument wird davon ausgegangen, dass Sie mit den allgemeinen Konzepten des Google Data APIs-Protokolls vertraut sind. Außerdem wird davon ausgegangen, dass Sie Java-Kenntnisse haben.

Referenzinformationen zu den von der Clientbibliothek bereitgestellten Klassen und Methoden finden Sie in der API-Referenz zur Java-Clientbibliothek (im Javadoc-Format).

Dieses Dokument sollte in der angegebenen Reihenfolge gelesen werden, da jedes Beispiel auf den vorherigen Beispielen aufbaut.

Übersicht über das Datenmodell

In der Java-Clientbibliothek wird eine Reihe von Klassen verwendet, um die von den Google Data APIs verwendeten Elemente darzustellen. Es gibt beispielsweise eine Feed-Klasse, die dem <atom:feed>-Element entspricht. Sie enthält Methoden zum Erstellen eines Eintrags, zum Abrufen und Festlegen der Werte verschiedener untergeordneter Elemente usw. Es gibt auch eine Entry-Klasse, die dem <atom:entry>-Element entspricht. Nicht jedes in den Google Data APIs definierte Element hat eine eigene Klasse. Weitere Informationen finden Sie in der Referenzdokumentation.

Die Bibliothek kann Atom-Inhalte automatisch parsen und die Werte der Atom-Elemente in entsprechende Objekte einfügen. Die Methode getFeed ruft beispielsweise einen Feed ab, parst ihn und gibt ein Feed-Objekt mit den resultierenden Werten zurück.

Wenn Sie einen Feed oder Eintrag an einen Dienst senden möchten, erstellen Sie ein Feed- oder Eintragsobjekt und rufen dann eine Bibliotheksmethode (z. B. die Methode insert) auf, um das Objekt automatisch in XML zu übersetzen und zu senden.

Sie können XML selbst parsen und/oder generieren. Am einfachsten geht das mit einer geeigneten Drittanbieterbibliothek wie Rome.

So wie die XML-Syntax der Google Data API erweiterbar ist, ist auch das entsprechende Objektmodell erweiterbar. Die Clientbibliothek enthält beispielsweise Klassen, die den im Google Data-Namespace definierten Elementen entsprechen.

Anleitung und Beispiele

Die folgenden Beispiele zeigen, wie Sie verschiedene Data API-Anfragen mit der Java-Clientbibliothek senden.

Um sie konkreter zu machen, zeigen diese Beispiele, wie Sie mit einem bestimmten Dienst interagieren: Google Kalender. Wir weisen auf Stellen hin, an denen sich Google Kalender von anderen Google-Diensten unterscheidet, damit Sie diese Beispiele für die Verwendung mit anderen Diensten anpassen können. Weitere Informationen zu Google Kalender finden Sie in der Dokumentation zur Google Calendar Data API.

Client erstellen und ausführen

Zum Kompilieren der Beispiele in diesem Dokument benötigen Sie die folgenden Importanweisungen:

import com.google.gdata.client.*;
import com.google.gdata.client.calendar.*;
import com.google.gdata.data.*;
import com.google.gdata.data.extensions.*;
import com.google.gdata.util.*;
import java.net.URL;

Feed anfordern

Wie im Dokument Google Calendar Data API beschrieben, können Sie einen Kalenderfeed anfordern, indem Sie die folgende HTTP-Anfrage an Google Kalender senden:

GET http://www.google.com/calendar/feeds/userID/private/full

Natürlich müssen Sie userID durch die E-Mail-Adresse des Nutzers ersetzen. Weitere Informationen finden Sie in der Kalenderdokumentation. Stattdessen können Sie die spezielle Standard-URL für die Interaktion mit Calendar verwenden (wie im Calendar-Dokument beschrieben). In diesem Dokument verwenden wir jedoch die private vollständige Feed-URL, die die Nutzer-ID enthält.

Außerdem müssen Sie eine geeignete Authentifizierung vornehmen. Die Hauptunterschiede zwischen diesem Beispiel und dem ersten Beispiel im Kalenderdokument bestehen darin, dass (1) dieses Beispiel die Authentifizierung umfasst und (2) in diesem Beispiel die allgemeinere GoogleService-Klasse anstelle der Kalender-spezifischen CalendarService-Klasse verwendet wird.

Das hier verwendete Authentifizierungssystem („Google-Authentifizierung für installierte Anwendungen“) ist nur für installierte Clientanwendungen wie Desktopclients geeignet, nicht für Webanwendungen. Weitere Informationen zur Authentifizierung finden Sie in der Dokumentation zur Google-Konto-Authentifizierung.

Wenn Sie mit der Java-Clientbibliothek einen Kalenderfeed für einen Nutzer mit der E-Mail-Adresse „liz@gmail.com“ und dem Passwort „mypassword“ anfordern möchten, verwenden Sie den folgenden Code:

// Set up the URL and the object that will handle the connection:
URL feedUrl = new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
GoogleService myService = new GoogleService("cl", "exampleCo-exampleApp-1");
myService.setUserCredentials("liz@gmail.com", "mypassword");

// Mark the feed as an Event feed:
new EventFeed().declareExtensions(myService.getExtensionProfile());

// Send the request and receive the response:
Feed myFeed = myService.getFeed(feedUrl, Feed.class);

Die Klasse GoogleService stellt eine Clientverbindung (mit Authentifizierung) zu einem GData-Dienst dar. Das allgemeine Verfahren zum Senden einer Anfrage an einen Dienst mit der Clientbibliothek umfasst die folgenden Schritte:

  1. Rufen Sie die entsprechende URL ab oder erstellen Sie sie.
  2. Wenn Sie Daten an einen Dienst senden (z. B. wenn Sie einen neuen Eintrag einfügen), wandeln Sie die Rohdaten mit den Clientbibliotheksklassen in Objekte um. Dieser Schritt ist nicht erforderlich, wenn Sie nur einen Feed anfordern, wie in diesem Beispiel.
  3. Erstellen Sie eine neue GoogleService-Instanz und legen Sie den Dienstnamen (z. B. "cl" für Calendar) und den Namen Ihrer Anwendung (im Format companyName-applicationName-versionID) fest.
  4. Legen Sie die entsprechenden Anmeldedaten fest.
  5. Geben Sie in der Clientbibliothek an, welche Erweiterungen im Feed verwendet werden, damit die Bibliothek zurückgegebene Feeds richtig parsen kann.
  6. Rufen Sie eine Methode auf, um die Anfrage zu senden und Ergebnisse zu empfangen.

Mit der Methode setUserCredentials werden die ID und das Passwort des Nutzers angegeben, in dessen Namen Ihr Client die Anfrage sendet. In den Beispielen in diesem Dokument wird das Authentifizierungssystem „Authentifizierung für installierte Anwendungen“ verwendet. Weitere Informationen zu Authentifizierungssystemen finden Sie in der Dokumentation zur Google-Konto-Authentifizierung.

Nachdem Sie die Anmeldedaten festgelegt haben, geben Sie mit der Methode declareExtensions an, welche Erweiterungen im Feed verwendet werden. In diesem Fall geben wir an, dass es sich um einen Event-Feed handelt und daher die Erweiterungen verwendet werden, die durch Event kind (Art des Ereignisses) definiert sind.

Wenn Sie einen vollständigen Feed anfordern möchten, rufen Sie die Methode getFeed auf. Sie verwendet eine URL und gibt den gesamten Feed zurück, der unter dieser URL gefunden wurde. Weiter unten in diesem Dokument wird beschrieben, wie Sie genauere Anfragen senden.

Wie andere Methoden der Klasse GoogleService übernimmt getFeed die Authentifizierung und Weiterleitungen nach Bedarf.

Neues Element einfügen

So erstellen Sie einen neuen Kalendertermin:

URL postUrl =
  new URL("http://www.google.com/calendar/feeds/liz@gmail.com/private/full");
EventEntry myEntry = new EventEntry();

myEntry.setTitle(new PlainTextConstruct("Tennis with Darcy"));
myEntry.setContent(new PlainTextConstruct("Meet for a quick lesson."));

Person author = new Person("Elizabeth Bennet", null, "liz@gmail.com");
myEntry.getAuthors().add(author);

DateTime startTime = DateTime.parseDateTime("2006-04-17T15:00:00-08:00");
DateTime endTime = DateTime.parseDateTime("2006-04-17T17:00:00-08:00");
When eventTimes = new When();
eventTimes.setStartTime(startTime);
eventTimes.setEndTime(endTime);
myEntry.addTime(eventTimes);

// Send the request and receive the response:
EventEntry insertedEntry = myService.insert(postUrl, myEntry);

Nachdem wir die URL festgelegt haben, erstellen wir ein EventEntry-Objekt. EventEntry wird von der abstrakten Basisklasse BaseEntry abgeleitet, die auch die übergeordnete Klasse für die Entry-Klasse ist, die ein <atom:entry>-Element darstellt.

Die Klasse EventEntry stellt einen Event-Typ dar. Weitere Informationen finden Sie im Dokument zu Typen. Bei anderen Diensten als Kalender weisen Sie den zurückgegebenen Eintrag möglicherweise einem Entry-Objekt anstelle eines EventEntry-Objekts zu.

Der Eintragstitel ist eine TextConstruct, eine Klasse, die Text in verschiedenen Formen (Nur-Text, HTML oder XHTML) enthält. Der Eintrag wird durch ein Content-Objekt dargestellt, eine Klasse, die entweder Nur-Text oder andere Formen von Inhalten, einschließlich XML und Binärdaten, enthalten kann. Die setContent-Methode kann aber auch ein TextConstruct akzeptieren.

Jeder Autor wird durch einen Namen, einen URI und eine E-Mail-Adresse dargestellt. In diesem Beispiel lassen wir den URI weg. Sie fügen einem Eintrag einen Autor hinzu, indem Sie die Methode getAuthors().add des Eintrags aufrufen.

Wir verwenden dasselbe GoogleService-Objekt, das wir im vorherigen Beispiel erstellt haben. In diesem Fall ist die aufzurufende Methode insert, mit der ein Element an die angegebene Einfüge-URL gesendet wird.

Der Dienst gibt den neu erstellten Eintrag zurück, der möglicherweise zusätzliche serverseitig generierte Elemente wie eine Bearbeitungs-URL für den Eintrag enthält.

HTTP-Statuscodes werden als Ausnahmen zurückgegeben.

Der obige Code entspricht dem Senden von POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full (mit korrekter Authentifizierung) und der Angabe eines Eintrags in Form eines Ereignistyps.

Einen bestimmten Eintrag anfordern

Mit dem folgenden Code können Sie den Eintrag anfordern, den Sie im vorherigen Beispiel eingefügt haben.

Im Kontext dieser Beispielreihe ist das Abrufen dieses Eintrags nicht wirklich erforderlich, da Calendar den eingefügten Eintrag bereits zurückgegeben hat. Dieselbe Technik kann jedoch immer angewendet werden, wenn Sie die URI für einen Eintrag kennen.

URL entryUrl = new URL(insertedEntry.getSelfLink().getHref());
EventEntry retrievedEntry = myService.getEntry(entryUrl, EventEntry.class);

Der eingefügte Eintrag hat eine Methode, getSelfLink, die ein Link-Objekt mit der URL des Eintrags zurückgibt. Die Klasse Link hat eine getHref-Methode, die die URL als String zurückgibt. Daraus können wir ein URL-Objekt erstellen.

Anschließend müssen wir nur noch die getEntry-Methode des Dienstes aufrufen, um den Eintrag abzurufen.

EventEntry.class wird als Parameter an getEntry übergeben. Das bedeutet, dass wir vom Dienst ein Event und nicht nur einen einfachen Eintrag erwarten. Für andere Dienste als Google Kalender können Sie stattdessen einfach Entry.class übergeben.

Der obige Code entspricht dem Senden von GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID an Calendar mit der entsprechenden Authentifizierung.

Einträge durchsuchen

Verwenden Sie den folgenden Code, um die erste Übereinstimmung aus einer Volltextsuche abzurufen:

Query myQuery = new Query(feedUrl);
myQuery.setFullTextQuery("Tennis");
Feed myResultsFeed = myService.query(myQuery, Feed.class);
if (myResultsFeed.getEntries().size() > 0) {
  Entry firstMatchEntry = myResultsFeed.getEntries().get(0);
  String myEntryTitle = firstMatchEntry.getTitle().getPlainText();
}

In diesem Beispiel wird zuerst ein Query-Objekt erstellt, das hauptsächlich aus einer URL und den zugehörigen Suchparametern besteht. Für jeden der Standard-GData-Abfrageparameter gibt es eine Setter-Methode. Mit der Methode addCustomParameter können Sie auch benutzerdefinierte Abfrageparameter für einen bestimmten Dienst festlegen.

Nachdem wir das Query-Objekt erstellt haben, übergeben wir es an die query-Methode des Dienstes, die einen Feed mit den Abfrageergebnissen zurückgibt. Alternativ können Sie eine URL selbst erstellen (indem Sie der Feed-URL Abfrageparameter anhängen) und dann die Methode getFeed aufrufen. Die Methode query bietet jedoch eine nützliche Abstraktionsebene, sodass Sie die URL nicht selbst erstellen müssen.

Die getEntries-Methode des Feeds gibt eine Liste der Einträge im Feed zurück. getEntries().size gibt die Anzahl der Einträge im Feed zurück.

In diesem Fall weisen wir das erste übereinstimmende Ergebnis einem Entry-Objekt zu, sofern die Abfrage Ergebnisse zurückgegeben hat. Anschließend verwenden wir die Methode getTitle().getPlainText der Klasse Entry, um den Titel des Eintrags abzurufen und in Text zu konvertieren.

Der obige Code entspricht dem Senden von GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full?q=Tennis an Google Kalender.

Abfragen nach Kategorie

Hinweis: In Google Kalender werden keine Labels mit Terminen verknüpft. Dieses Beispiel funktioniert daher nicht mit Google Kalender.

Wenn Sie einen Feed mit allen Einträgen abrufen möchten, die der vorherigen Volltextsuche entsprechen und sich in einer bestimmten Kategorie befinden oder ein bestimmtes Label haben, verwenden Sie den folgenden Code:

Category myCategory = new Category("by_liz");
CategoryFilter myCategoryFilter = new CategoryFilter(myCategory);
myQuery.addCategoryFilter(myCategoryFilter);
Feed myCategoryResultsFeed = myService.query(myQuery, Feed.class);

Die Klasse Category stellt natürlich eine Kategorie dar, die in einem Kategoriefilter verwendet werden kann. Die Klasse Query.CategoryFilter kann mehrere Kategorien enthalten. In diesem Fall erstellen wir jedoch einen Filter mit nur einer Kategorie.

Anschließend fügen wir diesen Filter der vorhandenen Abfrage hinzu, die weiterhin den Volltext-Abfragestring aus dem vorherigen Beispiel enthält.

Wir verwenden wieder die Methode query, um die Anfrage an den Dienst zu senden.

Wenn in Google Kalender eine Kategoriesuche möglich wäre, entspräche der obige Code dem Senden von GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/-/by_liz?q=Tennis an Google Kalender.

Artikel aktualisieren

Verwenden Sie den folgenden Code, um ein vorhandenes Element zu aktualisieren. In diesem Beispiel ändern wir den Titel des zuvor abgerufenen Eintrags von „Tennis mit Darcy“ in „Wichtiges Meeting“.

retrievedEntry.setTitle(new PlainTextConstruct("Important meeting"));
URL editUrl = new URL(retrievedEntry.getEditLink().getHref());
EventEntry updatedEntry = myService.update(editUrl, myEntry);

Zuerst legen wir einen neuen Titel für den Eintrag fest, den wir zuvor abgerufen haben. Anschließend rufen wir mit der Methode getEditLink die Bearbeitungs-URL für den Eintrag ab. Anschließend rufen wir die update-Methode des Dienstes auf, um den aktualisierten Eintrag zu senden.

Der Dienst gibt den aktualisierten Eintrag zurück, einschließlich einer neuen URL für die neue Version dieses Eintrags. Weitere Informationen zu Eintragsversionen finden Sie im Abschnitt Optimistic Concurrency (Optimistische Parallelität) im Protokollreferenzdokument.

Der obige Code entspricht in etwa dem Senden von PUT http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID an den Dienst zusammen mit dem neuen Eintrag (im Atom-Format), um den ursprünglichen Eintrag zu ersetzen.

Element löschen

Verwenden Sie den folgenden Code, um den aktualisierten Eintrag zu löschen:

URL deleteUrl = new URL(updatedEntry.getEditLink().getHref());
myService.delete(deleteUrl);

Die URL, die für das Löschen verwendet werden soll, ist dieselbe wie die Bearbeitungs-URL. Dieses Beispiel ähnelt also dem vorherigen, nur dass wir die Methode delete anstelle von update aufrufen.

Der obige Code entspricht in etwa dem Senden von DELETE http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID an den Dienst.

Referenz

Referenzinformationen zu den von der Clientbibliothek bereitgestellten Klassen und Methoden finden Sie in der API-Referenz zur Java-Clientbibliothek (im Javadoc-Format).

Nach oben