In diesem Dokument wird beschrieben, wie Sie mit der Java-Clientbibliothek Abfragen der Google Data API („GData“) senden und zurückgegebene Antworten interpretieren.
Google bietet eine Reihe von Clientbibliotheken in verschiedenen Programmiersprachen für die Interaktion mit Diensten mit Daten-APIs. 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 Beispiele für häufige Anwendungsfälle.
Sie benötigen Java 1.5, um diese Clientbibliothek verwenden zu können.
Java-Clientbibliothek herunterladen
Die Beispiele in diesem Handbuch beziehen sich auf die Google Calendar API. Sie stellen jedoch keine genaue oder aktuelle Anleitung zur Verwendung der Calendar API dar. Informationen zur Verwendung der Java-Clientbibliothek mit der Data API eines bestimmten Dienstes finden Sie in der dienstspezifischen Dokumentation. Wenn Sie zum Beispiel mit Google Kalender arbeiten, lesen Sie den Entwicklerleitfaden für die Calendar Data API.
Inhalt
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 Ideen hinter dem Google Data APIs-Protokoll vertraut sind. Außerdem wird vorausgesetzt, dass Sie wissen, wie man in Java programmiert.
Referenzinformationen zu den von der Clientbibliothek bereitgestellten Klassen und Methoden finden Sie in der API-Referenz zur Java-Clientbibliothek (im Javadoc-Format).
Dieses Dokument ist in der angegebenen Reihenfolge gelesen. Die Beispiele beruhen auf früheren Beispielen.
Datenmodell – Übersicht
Die Java-Clientbibliothek verwendet eine Reihe von Klassen, die die von den Google Data APIs verwendeten Elemente darstellen. Beispielsweise gibt es eine Feedklasse, die dem Element <atom:feed> entspricht. Sie bietet Methoden zum Erstellen eines Eintrags, zum Abrufen und Festlegen der Werte verschiedener Unterelemente usw. Außerdem gibt es 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 den Atom-Inhalt automatisch parsen und die Werte der Atom-Elemente in die entsprechenden Objekte einfügen. Die Methode getFeed ruft beispielsweise einen Feed ab, parst ihn und gibt ein Feed-Objekt mit den resultierenden Werten zurück.
Um einen Feed oder Eintrag an einen Dienst zu senden, erstellen Sie ein Feed- oder Eintragsobjekt und rufen dann eine Bibliotheksmethode (z. B. die Methode insert) auf, die das Objekt automatisch in XML übersetzt und sendet.
Sie können XML auch selbst parsen und/oder generieren. Die einfachste Methode hierfür ist eine geeignete Drittanbieterbibliothek wie Rome.
So wie die XML-Syntax der Google Data API erweiterbar ist, ist auch das entsprechende Objektmodell erweiterbar. Die Clientbibliothek stellt beispielsweise Klassen bereit, die den im Google Data-Namespace definierten Elementen entsprechen.
Anleitung und Beispiele
Die folgenden Beispiele zeigen, wie verschiedene Daten-API-Anfragen mit der Java-Clientbibliothek gesendet werden.
Diese Beispiele verdeutlichen, wie mit einem bestimmten Dienst interagiert werden kann: Google Kalender. Wir zeigen Ihnen, wo 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 Kalender-Feed 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 im Kalender-Dokument. Sie können stattdessen wie in Google Kalender beschrieben die spezielle Standard-URL für die Interaktion mit Google Kalender verwenden. In diesem Dokument verwenden wir jedoch die URL des privaten vollständigen Feeds, die die Nutzer-ID enthält.
Außerdem müssen Sie eine geeignete Authentifizierung angeben. Die Hauptunterschiede zwischen diesem Beispiel und dem ersten Beispiel im Kalenderdokument bestehen darin, dass (1) dieses Beispiel eine Authentifizierung umfasst und (2) dieses Beispiel die allgemeinere GoogleService-Klasse anstelle der kalenderspezifischen CalendarService-Klasse verwendet.
Beachten Sie, dass das Authentifizierungssystem, das wir hier verwenden (auch bekannt als „Google-Authentifizierung für installierte Anwendungen“), nur für installierte Client-Anwendungen wie Desktop-Clients und nicht für Webanwendungen geeignet ist. Weitere Informationen zur Authentifizierung finden Sie in der Dokumentation zur Google-Kontoauthentifizierung.
Verwenden Sie den folgenden Code, um einen Kalender-Feed über die Java-Clientbibliothek für einen Nutzer mit der E-Mail-Adresse „liz@gmail.com“ und dem Passwort „mypassword“ anzufordern:
// 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 Abfrage an einen Dienst mithilfe der Clientbibliothek besteht aus den folgenden Schritten:
- Rufen Sie die entsprechende URL ab oder erstellen Sie sie.
- Wenn Sie Daten an einen Dienst senden (z. B. wenn Sie einen neuen Eintrag einfügen), wandeln Sie die Rohdaten mithilfe der Clientbibliotheksklassen in Objekte um. Dieser Schritt gilt nicht, wenn Sie nur einen Feed anfordern, wie in diesem Beispiel.
- Erstellen Sie eine neue
GoogleService-Instanz und legen Sie den Dienstnamen (z. B."cl"für Google Kalender) und den Namen Ihrer Anwendung (im FormatcompanyName-applicationName-versionID) fest. - Legen Sie die entsprechenden Anmeldedaten fest.
- Geben Sie für die Clientbibliothek an, welche Erweiterungen der Feed verwenden soll, damit die zurückgegebenen Feeds korrekt geparst werden können.
- Rufen Sie eine Methode auf, um die Anfrage zu senden und Ergebnisse zu erhalten.
Die Methode setUserCredentials gibt die ID und das Passwort des Nutzers an, in dessen Namen der Client die Abfrage sendet. In den Beispielen dieses Dokuments wird das Authentifizierungssystem "Authentifizierung für installierte Anwendungen" verwendet. Weitere Informationen zu Authentifizierungssystemen finden Sie in der Dokumentation zur Google-Kontoauthentifizierung.
Nach dem Festlegen der Anmeldedaten geben Sie durch Aufruf der Methode declareExtensions an, welche Erweiterungen der Feed verwenden soll. In diesem Fall ist der Feed ein Ereignisfeed und verwendet daher die von der Ereignisart definierten Erweiterungen.
Wenn Sie einen gesamten Feed anfordern möchten, rufen Sie die Methode getFeed auf. Dabei wird eine URL verwendet und der gesamte Feed zurückgegeben, der unter dieser URL gefunden wurde. Wie Sie spezifischere Abfragen senden, erfahren Sie weiter unten in diesem Dokument.
Wie andere Methoden der GoogleService-Klasse übernimmt getFeed bei Bedarf die Authentifizierung und die Weiterleitungen.
Neues Element einfügen
Um einen neuen Kalendertermin zu erstellen, können Sie den folgenden Code verwenden:
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);
Nach dem Festlegen der URL konstruieren wir ein EventEntry-Objekt. EventEntry wird von der abstrakten Basisklasse BaseEntry abgeleitet. Diese ist auch die übergeordnete Klasse der Klasse Entry, die ein <atom:entry>-Element darstellt.
Die Klasse EventEntry stellt eine Ereignisart dar. Weitere Informationen finden Sie im Dokumenttyp. Für andere Dienste als Google Kalender können Sie den zurückgegebenen Eintrag einem Entry-Objekt statt einem EventEntry-Objekt zuweisen.
Der Titel des Eintrags ist eine TextConstruct, eine Klasse, die Text in verschiedenen Formen (einfacher Text, HTML oder XHTML) enthält. Der Eintrag wird durch ein Content-Objekt repräsentiert. Diese Klasse kann entweder Nur-Text oder andere Formen von Inhalten enthalten, einschließlich XML- und Binärdaten. Die Methode setContent kann aber auch TextConstruct akzeptieren.
Jeder Autor wird als Name, URI und E-Mail-Adresse dargestellt. In diesem Beispiel wird der URI weggelassen. 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 lautet die aufzurufende Methode insert. Damit wird ein Element an die angegebene Einfügungs-URL gesendet.
Der Dienst gibt den neu erstellten Eintrag zurück, der zusätzliche vom Server generierte Elemente enthalten kann, z. B. eine Bearbeitungs-URL für den Eintrag.
HTTP-Statuscodes werden als Ausnahmen zurückgegeben.
Der Code oben entspricht dem Senden von POST http://www.google.com/calendar/feeds/liz@gmail.com/private/full (mit der richtigen Authentifizierung) und der Bereitstellung eines Eintrags in Form eines Ereignisses.
Einen bestimmten Eintrag anfordern
Mit dem folgenden Code können Sie den spezifischen Eintrag anfordern, den Sie im vorherigen Beispiel eingefügt haben.
Im Kontext dieser Beispielreihe ist das Abrufen dieses Eintrags nicht unbedingt notwendig, da Google Kalender den eingefügten Eintrag bereits zurückgegeben hat. Sie können jedoch immer dieselbe Methode anwenden, wenn Sie den 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 die Methode getSelfLink, mit der ein Link-Objekt zurückgegeben wird, das die URL des Eintrags enthält. Die Klasse Link hat eine getHref-Methode, die die URL als String zurückgibt, aus der ein URL-Objekt erstellt werden kann.
Anschließend rufen wir die Methode getEntry des Dienstes auf, um den Eintrag abzurufen.
Beachten Sie, dass wir EventEntry.class als Parameter an getEntry übergeben. Damit wird angegeben, dass der Dienst ein Ereignis und nicht nur einen einfachen Eintrag erwartet. Für andere Dienste als Google Kalender können Sie einfach Entry.class übergeben.
Der Code oben entspricht dem Senden von GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full/entryID an den Kalender mit ordnungsgemäßer Authentifizierung.
Einträge suchen
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 konstruiert, das hauptsächlich aus einer URL und zugehörigen Suchparametern besteht. Jeder der GData-Standardabfrageparameter hat eine Setter-Methode. Mit der Methode addCustomParameter können Sie auch benutzerdefinierte Abfrageparameter für einen bestimmten Dienst festlegen.
Nachdem wir das Query-Objekt konstruiert 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 Suchparameter an die Feed-URL anhängen) und dann die Methode getFeed aufrufen. Die Methode query bietet jedoch eine nützliche Abstraktionsebene, damit Sie die URL nicht selbst erstellen müssen.
Die Methode getEntries des Feeds gibt eine Liste der Einträge im Feed zurück. getEntries().size gibt die Anzahl der Einträge im Feed zurück.
Wenn die Abfrage Ergebnisse zurückgibt, wird das erste übereinstimmende Ergebnis einem Entry-Objekt zugewiesen. Anschließend rufen wir die Methode getTitle().getPlainText der Entry-Klasse ab, um den Titel des Eintrags abzurufen und in Text umzuwandeln.
Der obige Code entspricht dem Senden von GET http://www.google.com/calendar/feeds/liz@gmail.com/private/full?q=Tennis an Google Kalender.
Nach Kategorie abfragen
Hinweis: Google Kalender verknüpft keine Labels mit Terminen, sodass dieses Beispiel in Google Kalender nicht funktioniert.
Verwenden Sie den folgenden Code, um einen Feed abzurufen, der aus allen Einträgen besteht, die mit der früheren Volltextsuche übereinstimmen und eine bestimmte Kategorie oder ein bestimmtes Label haben:
Category myCategory = new Category("by_liz");
CategoryFilter myCategoryFilter = new CategoryFilter(myCategory);
myQuery.addCategoryFilter(myCategoryFilter);
Feed myCategoryResultsFeed = myService.query(myQuery, Feed.class);
Die Klasse Category ist selbstverständlich eine Kategorie, die in einem Kategoriefilter verwendet werden soll. Die Klasse Query.CategoryFilter kann mehrere Kategorien enthalten. In diesem Fall erstellen wir einen Filter mit nur einer Kategorie.
Dann 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 Abfrage an den Dienst zu senden.
Wenn Google Kalender eine Kategoriesuche zulässt, entspricht 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 wird der Titel des zuvor abgerufenen Eintrags aus dem alten Text („Tennis mit Darcy“) in „Wichtige Besprechung“ geändert.
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 zuvor abgerufenen Eintrag fest. Anschließend wird die Bearbeitungs-URL für den Eintrag mit der Methode getEditLink abgerufen. Anschließend rufen wir die Methode update 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 Protokollreferenzdokument im Abschnitt Optimistische Gleichzeitigkeit.
Der Code oben entspricht in etwa der Übermittlung 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.
Elemente 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 gelöscht werden soll, ist die gleiche wie die der Bearbeitungs-URL. Dieses Beispiel ist dem vorherigen sehr ähnlich, nur dass die Methode delete anstelle von update aufgerufen wird.
Der Code oben 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).