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

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

In diesem Dokument finden Sie eine Reihe von Beispielen für die häufigsten Anwendungsfälle der C#-Version der Clientbibliothek sowie weitere Informationen zum Schreiben von GData-Clients. Am Ende dieses Dokuments finden Sie einen Link zur Referenzdokumentation für die C#-Clientbibliothek im NDoc-Format.

Für die Verwendung dieser Clientbibliothek benötigen Sie die .NET 1.1-Laufzeitumgebung. Außerdem sollten Sie alle Patches installiert haben.

.NET-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 .NET-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

Zielgruppe

Dieses Dokument richtet sich an C#-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 in C# programmieren können.

Übersicht über das Datenmodell

Die C#-Clientbibliothek bietet eine Reihe von Klassen, die den von den Google Data APIs verwendeten Elementen und Datentypen entsprechen. 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-Dateien auch selbst parsen und/oder generieren. Am einfachsten geht das mit einer geeigneten Drittanbieterbibliothek.

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 verschiedene GData-Anfragen mit der C#-Clientbibliothek gesendet werden.

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 folgende using-Anweisung:

using Google.GData.Client;

Feed anfordern

Wie in der Dokumentation zur 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. 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 C#-Clientbibliothek einen Kalenderfeed für einen Nutzer mit der E-Mail-Adresse „jo@gmail.com“ und dem Passwort „mypassword“ anfordern möchten, verwenden Sie den folgenden Code:

// Create a query and service object:

FeedQuery query = new FeedQuery();
Service service = new Service("cl", "exampleCo-exampleApp-1"));
// Set your credentials:
service.setUserCredentials("jo@gmail.com", "mypassword");

// Create the query object:
query.Uri = new Uri("http://www.google.com/calendar/feeds/jo@gmail.com/private/full");

// Tell the service to query:
AtomFeed calFeed = service.Query(query);

Die Klasse Service 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 Service-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. Rufen Sie eine Methode auf, um die Anfrage zu senden und Ergebnisse zu empfangen.

Mit der Methode service.setUserCredentials wird die Property service.Credentials mit einem Standardobjekt für .NET-Netzwerkanmeldedaten festgelegt. Die Anmeldedaten sind auf die ID und das Passwort des Nutzers festgelegt, 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 anderen Authentifizierungssystemen finden Sie in der Dokumentation zur Google-Konto-Authentifizierung.

Wenn Sie einen vollständigen Feed anfordern möchten, rufen Sie die Methode service.Query auf. Diese verwendet ein FeedQuery-Objekt 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 Service übernimmt Query die Authentifizierung und Weiterleitungen nach Bedarf.

Neues Element einfügen

Mit dem folgenden Code können Sie ein Element in einen Kalenderfeed einfügen:

AtomEntry entry = new AtomEntry();
AtomPerson author = new AtomPerson(AtomPersonType.Author);
author.Name = "Jo March"; 
author.Email = "jo@gmail.com";
entry.Authors.Add(author);
entry.Title.Text = "Tennis with Beth"; 
entry.Content.Content = "Meet for a quick lesson.";

Uri postUri = new Uri("http://www.google.com/calendar/feeds/jo@gmail.com/private/full");

// Send the request and receive the response:
AtomEntry insertedEntry = service.Insert(postUri, entry);

Nachdem wir die URL festgelegt haben, erstellen wir ein AtomEntry-Objekt.

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

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 der Authors-Sammlung des Eintrags ein AtomAuthor-Objekt hinzufügen.

Wir verwenden dasselbe Service-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.

Der obige Code entspricht dem Senden von POST http://www.google.com/calendar/feeds/jo@gmail.com/private/full (mit korrekter Authentifizierung) und dem Bereitstellen eines Eintrags.

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 Methode kann jedoch immer angewendet werden, wenn Sie die URL für einen Eintrag kennen.

FeedQuery singleQuery = new FeedQuery();
singleQuery.Uri = new Uri(newEntry.SelfUri.ToString()); 
AtomFeed newFeed = service.Query(singleQuery);
AtomEntry retrievedEntry = newFeed.Entries[0];

Der eingefügte Eintrag hat das Attribut SelfUri, das ein AtomUri-Objekt zurückgibt, mit dem über die Methode ToString() ein neues URI-Objekt erstellt werden kann.

Anschließend müssen wir nur noch die Query-Methode des Dienstes aufrufen, um ein neues AtomFeed-Objekt mit nur einem Eintrag in der Sammlung „Entries“ zu erhalten.

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

Nach einem Eintrag suchen

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

FeedQuery myQuery = new Query(feedUrl);
myQuery.Query = "Tennis"; 
AtomFeed myResultsFeed = myService.Query(myQuery);
if (myResultsFeed.Entries.Count > 0) {
  AtomEntry firstMatchEntry = myResultsFeed.Entries[0]; 
  String myEntryTitle = firstMatchEntry.Title.Text; 
}

In diesem Beispiel wird zuerst ein FeedQuery-Objekt erstellt, das hauptsächlich aus einer URL und den zugehörigen Suchparametern besteht. Für jeden der Standard-GData-Abfrageparameter gibt es eine Property.

Nachdem wir das FeedQuery-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 Query aufrufen. Die Methode FeedQuery bietet jedoch eine nützliche Abstraktionsebene, sodass Sie die URL nicht selbst erstellen müssen.

Die Sammlung Entries des Feeds gibt eine Liste der Einträge im Feed zurück. Entries.Count gibt die Anzahl der Einträge im Feed zurück.

In diesem Fall weisen wir das erste übereinstimmende Ergebnis einem AtomEntry-Objekt zu, sofern die Abfrage Ergebnisse zurückgegeben hat. Anschließend verwenden wir das Attribut Title der Klasse AtomEntry, um den Titel des Eintrags abzurufen.

Der obige Code entspricht dem Senden von GET http://www.google.com/calendar/feeds/jo@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:

AtomCategory myCategory = new AtomCategory("by_jo");
QueryCategory myCategoryFilter = new QueryCategory(myCategory);
myQuery.Categories.Add(myCategoryFilter);
AtomFeed myCategoryResultsFeed = myService.Query(myQuery);

Die Klasse AtomCategory stellt natürlich eine Kategorie dar, die in einem Kategoriefilter verwendet werden kann. Die Klasse QueryCategory 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/jo@gmail.com/private/full/-/by_jo?q=Tennis an Google Kalender.

Artikel aktualisieren

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

retrievedEntry.Title.Text = "Important meeting";
retrievedEntry.Update();

Zuerst legen wir einen neuen Titel für den Eintrag fest, den wir zuvor abgerufen haben. Anschließend rufen wir einfach die Methode Upate auf, um den aktualisierten Eintrag an den Dienst 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 v1-Protokollreferenzdokument.

Der obige Code entspricht in etwa dem Senden von PUT http://www.google.com/calendar/feeds/jo@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 ein vorhandenes Element zu löschen:

updateEntry.Delete();

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/jo@gmail.com/private/full/entryID an den Dienst.

Mit Google Kalender-Feeds arbeiten

Die obigen Beispiele zeigen, wie Sie die Google Data C#-API verwenden, um mit generischen GData-Feeds zu arbeiten. Wenn Sie jedoch mit einem Google Kalender-Feed arbeiten, enthält der Feed viele kalenderspezifische Daten, auf die mit den standardmäßigen Atom-orientierten Objekten in der Basis-API-Bibliothek nicht einfach zugegriffen werden kann. Um Ihnen die Interaktion mit diesen Feeds zu erleichtern, stellen wir die folgenden Erweiterungen zur Verfügung:

using Google.GData.Extensions;
using Google.GData.Calendar;

Der Namespace „Extensions“ bezieht sich auf Erweiterungen im Allgemeinen. Der Namespace „Calendar“ bietet Zugriff auf einen benutzerdefinierten Kalenderdienst, Feed und Abfrageobjekt. Ein ausführlicheres Beispiel für die Verwendung dieser Erweiterungen finden Sie im Unterverzeichnis „Samples“ der C#-API-Installation. Die folgenden Objekte werden hinzugefügt:

EventQuery

Eine Unterklasse von FeedQuery, mit der Sie zwei benutzerdefinierte Parameter für den Kalenderdienst festlegen können (start-min und start-max).

CalendarService

Eine Unterklasse von „service“, die einen Ereignisfeed zurückgeben kann.

EventFeed

Eine Unterklasse von AtomFeed, die EventEntries verfügbar macht.

EventEntry

Eine Unterklasse von AtomEntry, die zusätzliche Eigenschaften für Kalenderdaten hat.

Weitere Informationen zu diesen speziellen Klassen finden Sie in der API-Dokumentation und im Beispielprogramm.

Referenz

Referenzinformationen zur C#-Clientbibliothek finden Sie in der Referenzdokumentation.

Nach oben