In diesem Dokument wird beschrieben, wie Sie mit der .NET-Clientbibliothek Anfragen an die Google Data API („GData“) senden und zurückgegebene Antworten interpretieren.
Google bietet eine Reihe von Clientbibliotheken für die Interaktion mit GData-fähigen Diensten in verschiedenen Programmiersprachen. Mit diesen Bibliotheken können Sie GData-Anfragen erstellen, an einen Dienst senden und Antworten empfangen.
Dieses Dokument enthält Beispiele für häufige Verwendungsmöglichkeiten 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 diese Clientbibliothek benötigen Sie die .NET 1.1-Laufzeit. Außerdem sollten Sie auf allen Patches aktuell sein.
.NET-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 zum Verwenden der .NET-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 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 Ideen hinter dem Google Data APIs-Protokoll vertraut sind. Außerdem wird vorausgesetzt, dass Sie wissen, wie man in C# programmiert.
Datenmodell – Übersicht
Die C#-Clientbibliothek stellt eine Reihe von Klassen zur Verfügung, die den von den Google Data APIs verwendeten Elementen und Datentypen entsprechen. 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.
Du kannst XML selbst parsen und/oder generieren. Die einfachste Möglichkeit dafür ist eine geeignete Drittanbieter-Bibliothek.
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 Sie verschiedene GData-Anfragen mit der C#-Clientbibliothek senden.
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 müssen Sie die folgende using-Anweisung verwenden:
using Google.GData.Client;
Feed anfordern
Wie in der Google Calendar Data API-Dokumentation 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. 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 C#-Clientbibliothek für einen Nutzer mit der E-Mail-Adresse „jo@gmail.com“ und dem Passwort „mypassword“ anzufordern:
// 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 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
Service-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.
- Rufen Sie eine Methode auf, um die Anfrage zu senden und Ergebnisse zu erhalten.
Mit der Methode service.setUserCredentials wird das Attribut service.Credentials mit einem Standardobjekt für .NET-Netzwerkanmeldedaten festgelegt.
Als Anmeldedaten werden die ID und das Passwort des Nutzers festgelegt, in dessen Namen der Client die Anfrage sendet. In den Beispielen dieses Dokuments wird das Authentifizierungssystem Authentifizierung für installierte Anwendungen verwendet. Weitere Informationen zu anderen Authentifizierungssystemen finden Sie in der Dokumentation zur Google-Kontoauthentifizierung.
Wenn Sie einen gesamten Feed anfordern möchten, rufen Sie die Methode service.Query auf. Dabei wird mit einem FeedQuery-Objekt 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 Service-Klasse übernimmt Query bei Bedarf die Authentifizierung und die Weiterleitungen.
Neues Element einfügen
Wenn Sie ein Element in einen Kalender-Feed einfügen möchten, können Sie den folgenden Code verwenden:
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 die URL festgelegt wurde, wird ein AtomEntry-Objekt erstellt.
Der Titel des Eintrags ist eine AtomTextConstruct, eine Klasse, die Text in verschiedenen Formen (einfacher Text, HTML oder XHTML) enthält. Der Eintrag wird durch ein AtomContent-Objekt dargestellt. Das ist eine Klasse, die entweder Nur-Text oder andere Formen von Inhalten enthalten kann, einschließlich XML- und Binärdaten.
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 ein AtomAuthor-Objekt zur Sammlung Authors des Eintrags hinzufügen.
Wir verwenden dasselbe Service-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.
Der Code oben entspricht dem Senden von POST http://www.google.com/calendar/feeds/jo@gmail.com/private/full (mit der richtigen Authentifizierung) und der Eingabe eines Eintrags.
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 Reihe von Beispielen ist das Abrufen dieses Eintrags nicht wirklich notwendig, da Google Kalender den eingefügten Eintrag bereits zurückgegeben hat. Die gleiche Technik kann jedoch angewendet werden, wenn Sie die URL eines Eintrags 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 enthält das Attribut SelfUri, das ein AtomUri-Objekt zurückgibt, mit dem unter Verwendung der ToString()-Methode ein neues URI-Objekt erstellt werden kann.
Anschließend rufen wir die Methode Query des Dienstes auf, um ein neues AtomFeed-Objekt mit nur einem Eintrag in der Eintragssammlung abzurufen.
Der Code oben entspricht dem Senden von GET http://www.google.com/calendar/feeds/jo@gmail.com/private/full/entryID an den Kalender mit ordnungsgemäßer Authentifizierung.
Suche nach Einträgen
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 konstruiert, das hauptsächlich aus einer URL und zugehörigen Suchparametern besteht. Jeder der GData-Standardabfrageparameter hat eine Property.
Nachdem wir das FeedQuery-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 Query aufrufen. Die Methode FeedQuery bietet jedoch eine nützliche Abstraktionsebene, damit 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.
Wenn die Abfrage Ergebnisse zurückgibt, wird das erste übereinstimmende Ergebnis einem AtomEntry-Objekt zugewiesen. Anschließend verwenden wir die Eigenschaft 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.
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:
AtomCategory myCategory = new AtomCategory("by_jo");
QueryCategory myCategoryFilter = new QueryCategory(myCategory);
myQuery.Categories.Add(myCategoryFilter);
AtomFeed myCategoryResultsFeed = myService.Query(myQuery);
Die Klasse AtomCategory ist selbstverständlich eine Kategorie, die in einem Kategoriefilter verwendet werden soll. Die Klasse QueryCategory 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/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 wird der Titel des zuvor abgerufenen Eintrags aus dem alten Text („Tennis mit Beth“) in „Wichtige Besprechung“ geändert.
retrievedEntry.Title.Text = "Important meeting"; retrievedEntry.Update();
Zuerst legen wir einen neuen Titel für den zuvor abgerufenen Eintrag fest. Dann 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 Referenzdokument zum v1-Protokoll im Abschnitt Optimistische Gleichzeitigkeit.
Der Code oben entspricht in etwa der Übermittlung 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.
Elemente löschen
Verwenden Sie den folgenden Code, um ein vorhandenes Element zu löschen:
updateEntry.Delete();
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/jo@gmail.com/private/full/entryID an den Dienst.
Mit Google Kalender-Feeds arbeiten
In den Beispielen oben wird beschrieben, wie Sie die Google Data C# API für allgemeine GData-Feeds verwenden. Wenn Sie jedoch mit einem Google Kalender-Feed arbeiten, enthält dieser viele kalenderspezifische Daten, auf die mit den standardmäßigen Atom-orientierten Objekten in der API-Basisbibliothek nicht problemlos zugegriffen werden kann. Mit den folgenden Erweiterungen können Sie besser mit diesen Feeds interagieren:
using Google.GData.Extensions; using Google.GData.Calendar;
Der Namespace „Extensions“ bezieht sich auf Erweiterungen im Allgemeinen. Mit dem Namespace „Calendar“ haben Sie Zugriff auf einen benutzerdefinierten Kalenderdienst, einen benutzerdefinierten Feed und ein 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:
- Ereignisabfrage
- Eine Unterklasse von FeedQuery, mit der Sie zwei benutzerdefinierte Parameter für den Kalenderdienst festlegen können: start-min und start-max.
- Kalenderservice
- Eine Unterklasse des Dienstes, der einen Ereignisfeed zurückgeben kann.
- Ereignisfeed
- Eine Unterklasse von AtomFeed, die EventEntries verfügbar macht.
- Ereigniseintrag
- Eine Unterklasse von AtomEntry mit zusätzlichen Attributen im Zusammenhang mit Kalenderdaten.
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.