Warnung: Diese Seite bezieht sich auf die älteren Google Data APIs. Sie ist nur für die APIs relevant, die im Verzeichnis der Google Data APIs aufgeführt sind. Viele davon wurden durch neuere APIs ersetzt. Informationen zu einer bestimmten neuen API finden Sie in der Dokumentation der neuen API. Informationen zum Autorisieren von Anfragen mit einer neueren API finden Sie unter Authentifizierung und Autorisierung von Google-Konten.
In diesem Dokument wird beschrieben, wie Sie mit der JavaScript-Clientbibliothek Google Data API-Abfragen 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 API-Anfragen erstellen, an einen Dienst senden und Antworten empfangen.
Dieses Dokument enthält einige allgemeine Informationen zur Verwendung der JavaScript-Clientbibliothek sowie eine Reihe von häufigen Anwendungsfällen.
Zielgruppe
Dieses Dokument richtet sich an JavaScript-Programmierer, die Clientanwendungen schreiben möchten, die mit Google Data-Diensten interagieren.
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 JavaScript programmiert.
Referenzinformationen zu den von der Clientbibliothek bereitgestellten Klassen und Methoden finden Sie in der API-Referenz für die JavaScript-Clientbibliothek (im JSdoc-Format).
Dieses Dokument ist in der angegebenen Reihenfolge gelesen. Die Beispiele beruhen auf früheren Beispielen.
Nutzungsbedingungen
Sie verpflichten sich, die Nutzungsbedingungen für die Google JavaScript-Clientbibliothek einzuhalten, wenn Sie die JavaScript-Clientbibliothek verwenden.
Datenmodell- und Kontrollfluss – Übersicht
Die JavaScript-Clientbibliothek verwendet eine Reihe von Klassen, die die von den Google Data APIs verwendeten Elemente darstellen.
Hinweis: Die zugrunde liegende Datendarstellung ist JSON, die Clientbibliothek bietet jedoch eine Abstraktionsebene, sodass Sie nicht direkt mit den JSON-Daten arbeiten müssen. Wenn Sie direkt mit JSON ohne die Clientbibliothek arbeiten möchten, finden Sie weitere Informationen unter JSON mit Google Data APIs verwenden.
Die Bibliothek bietet Methoden, mit denen Sie Daten asynchron an einen Dienst senden und von diesem empfangen können, der über eine Daten-API verfügt. Die Methode google.gdata.calendar.CalendarService.getEventsFeed() sendet beispielsweise eine Feedanfrage an Google Kalender. Einer der Parameter, die Sie übergeben, ist eine Continuation-Funktion, die auch als Callback bezeichnet wird. Der Dienst gibt den Feed im JSON-Format durch Aufruf der Continuation-Funktion zurück. Der Client kann dann verschiedene get-Methoden aufrufen, um die Daten in Form von JavaScript-Objekten zu verwenden.
Um einen neuen Eintrag hinzuzufügen, erstellen Sie den Eintrag mit den Klassen und Methoden der Clientbibliothek und rufen dann die Methode feed.insertEntry() auf, um den neuen Eintrag an den Dienst zu senden. Auch hier stellen Sie eine Continuation-Funktion bereit, die vom Dienst aufgerufen wird, wenn der Eintrag erfolgreich hinzugefügt wurde.
Wenn Sie noch nicht mit JavaScript vertraut sind, ist der Steuerungsablauf möglicherweise etwas verwirrend. Nachdem Sie eine Methode wie getEventsFeed() oder insertEntry() aufgerufen haben, wird das Skript in den meisten Fällen beendet. Die Ausführung wird in der Fortsetzungsfunktion fortgesetzt, wenn der Dienst die angeforderten Daten zurückgibt. Daher sollten alle Aktionen Ihres Clients in Bezug auf die zurückgegebenen Daten in der Continuation-Funktion erfolgen oder von dieser Funktion aufgerufen werden. Unter Umständen müssen Sie einige Variablen global definieren, um sie in mehreren Funktionen verwenden zu können.
Weitere Informationen zu diesem Programmierstil finden Sie unter Fortlaufender Stil.
Unterstützte Umgebungen
Derzeit werden nur JavaScript-Client-Anwendungen unterstützt, die auf einer Webseite in einem Browser ausgeführt werden. Derzeit werden folgende Browser unterstützt:
- Firefox 2.x und 3.x
- Internet Explorer 6, 7 und 8
- Safari 3.x und 4.x
- Google Chrome (alle Versionen)
Die JavaScript-Clientbibliothek übernimmt die gesamte Kommunikation mit dem Server des Dienstes. Wenn Sie ein erfahrener JS-Entwickler sind, denken Sie vielleicht: „Aber was ist mit der Richtlinie für denselben Ursprung? Mit der JavaScript-Clientbibliothek kann Ihr Client Google-Datenanfragen von jeder Domain senden und gleichzeitig mit dem Browsersicherheitsmodell konform bleiben.
Eine Übersicht über die Authentifizierung bei den Google Data APIs finden Sie in der Authentifizierungsübersicht der Google Data APIs. Im weiteren Verlauf dieses Dokuments wird davon ausgegangen, dass Sie mit den Grundlagen der Funktionsweise dieses Systems vertraut sind.
Beispiele für Clientanwendungen
Auf unserer Beispielseite können Sie die JavaScript-Clientbibliothek in Aktion sehen.
Anleitung und Beispiele
Die folgenden Beispiele zeigen, wie verschiedene Daten-API-Anfragen mit der JavaScript-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 im Dokument Google Calendar Data API.
Bibliothek laden
Bevor Ihr Client die Client-Bibliothek nutzen kann, muss er den Client-Bibliothek-Code vom Server anfragen.
Verwenden Sie zuerst ein <script>-Tag im Abschnitt <head> Ihres HTML-Dokuments, um den Google AJAX API-Loader abzurufen:
<script type="text/javascript" src="https://www.google.com/jsapi"></script>
Sie können die Umlaufzeit auf die Server von Google minimieren und die Latenz verringern, indem Sie die Bibliothek vorab laden. Wenn Sie bestimmte Pakete direkt aus dem Google AJAX API-Loader vorab laden möchten (ohne google.load() zu verwenden), verwenden Sie Folgendes:
<script type="text/javascript"
src="https://www.google.com/jsapi?autoload=%7Bmodules%3A%5B%7Bname%3Agdata%2Cversion%3A2.x%2Cpackages%3A%5Bblogger%2Ccontacts%5D%7D%5D%7D"></script>
Hinweis: Die src-URL des Skripts muss vollständig URL-codiert sein. Das vorherige Beispiel ist <script type="text/javascript" src="https://www.google.com/jsapi?autoload={modules:[{name:gdata,version:2.x,packages:[blogger,contacts]}]}"></script>.
Wenn Sie Module nicht automatisch laden, können Sie die Google Data-Clientbibliothek anhand des nächsten Beispiels in Ihrem JavaScript-Einrichtungscode nach dem Abrufen des allgemeinen Loaders laden. Der Aufruf muss über den <head>-Abschnitt des HTML-Dokuments (oder über eine JavaScript-Datei mit dem <script>-Tag im <head>-Abschnitt des HTML-Dokuments) erfolgen:
google.load("gdata", "2");
Alternativ können Sie anstelle der gesamten Bibliothek auch bestimmte Dienste anfordern. In diesem Beispiel werden nur die Pakete für Blogger und Kontakte heruntergeladen:
google.load("gdata", "2.x", {packages: ["blogger", "contacts"]});
Der zweite Parameter für google.load() ist die angeforderte Versionsnummer der JavaScript-Clientbibliothek.Unser Versionsschema basiert auf dem Modell der Google Maps API. Hier sind die möglichen Versionsnummern und ihre Bedeutung:
"1"- Die vorletzte Überarbeitung der Hauptversion 1.
"1.x"- Die allerneueste Überarbeitung der Hauptversion 1.
"1.s"- Die letzte stabile Überarbeitung der Hauptversion 1. Auf der Grundlage des Feedbacks, das wir von Entwicklern erhalten, erklären wir von Zeit zu Zeit eine bestimmte Version der Clientbibliothek für die Stabilität. Möglicherweise enthält diese Version jedoch nicht die neuesten Funktionen.
"1.0","1.1" usw.- Eine bestimmte Version der Bibliothek mit einer angegebenen Haupt- und Nebenversionsnummer.
Nachdem Sie google.load() aufgerufen haben, müssen Sie das Ladeprogramm anweisen, zu warten, bis die Seite geladen ist, und dann Ihren Code aufzurufen:
google.setOnLoadCallback(getMyFeed);
Dabei ist getMyFeed() eine Funktion, die im nächsten Abschnitt dieses Dokuments definiert wird. Verwenden Sie diesen Ansatz, anstatt einen onload-Handler an das <body>-Element anzuhängen.
Nicht authentifizierten Feed anfordern
Wenn Sie einen nicht authentifizierten Feed anfordern möchten, fügen Sie den folgenden Code in Ihre JavaScript-Datei oder in ein <script>-Tag in Ihrer HTML-Datei ein.
Im folgenden Code wird getMyFeed() zuerst vom AJAX API-Loader aufgerufen, wie im vorherigen Abschnitt beschrieben.
Sie ruft setupMyService() auf, um eine Verbindung (durch ein CalendarService-Objekt dargestellt) mit Google Kalender zu erstellen. Wir haben den Code zur Diensterstellung in eine separate Funktion für die Modularität herausgebracht. Später ändern wir die Funktion setupMyService() entsprechend Ihren Authentifizierungsoptionen.
Nach dem Einrichten des Dienstes ruft getMyFeed() die getEventsFeed()-Methode der Clientbibliothek auf, um den Feed anzufordern.
Wir geben die Feed-URL in einer globalen Variablen an, damit sie in späteren Funktionen verwendet werden kann. In diesem Beispiel verwenden wir die URL des öffentlichen (nicht authentifizierten) Feeds für den Nutzer liz@gmail.com. Sie können auch default anstelle der E-Mail-Adresse des Nutzers verwenden, um den authentifizierten Nutzer zu repräsentieren.
var feedUrl = "http://www.google.com/calendar/feeds/liz@gmail.com/public/full";
function setupMyService() {
var myService = new google.gdata.calendar.CalendarService('exampleCo-exampleApp-1');
return myService;
}
function getMyFeed() {
myService = setupMyService();
myService.getEventsFeed(feedUrl, handleMyFeed, handleError);
}
myService wird zur einfachen Verwendung in späteren Funktionen als globale Variable festgelegt.
Damit der obige Code in Ihrem eigenen Client funktioniert, müssen Sie die E-Mail-Adresse eines echten Nutzers für ein Google Kalender-Konto mit einem öffentlich freigegebenen Kalender verwenden.
Hinweis: Wenn Sie ein neues CalendarService-Objekt erstellen, ruft die Clientbibliothek die Methode google.gdata.client.init() auf. Dadurch wird geprüft, ob der Browser, in dem der Client ausgeführt wird, unterstützt wird. Wenn ein Fehler auftritt, wird in der Clientbibliothek eine Fehlermeldung angezeigt. Wenn Sie einen solchen Fehler selbst beheben möchten, können Sie vor dem Erstellen des Dienstes google.gdata.client.init(handleInitError) explizit aufrufen. Dabei ist handleInitError() Ihre Funktion. Wenn ein Init-Fehler auftritt, empfängt Ihre Funktion ein Standardfehlerobjekt. Sie können mit diesem Objekt alles tun, was Sie möchten.
Beim Aufruf von getEventsFeed() ist das zweite Argument handleMyFeed, eine Callback-Funktion (siehe unten). Die Anfrage wird von Google Kalender verarbeitet. Wenn die Anfrage erfolgreich war, wird ein „Feedstammobjekt“ mit dem angeforderten Feed an den Callback übergeben. Ein Feedstamm ist ein Containerobjekt, das einen Feed enthält.
Das dritte Argument für getEventsFeed() ist eine optionale Fehlerbehandlungsfunktion. Wenn bei der Clientbibliothek ein Fehler auftritt, wird anstelle der Erfolgsrückruffunktion der angegebene Fehler-Handler aufgerufen. Das Objekt, das die Clientbibliothek als Argument an den Fehler-Handler weitergibt, ist eine Instanz des JavaScript-Error-Objekts mit einer zusätzlichen cause-Eigenschaft.
Hier sehen Sie einfache Versionen der Callback-Funktion und des Fehler-Handlers:
function handleMyFeed(myResultsFeedRoot) {
alert("This feed's title is: " + myResultsFeedRoot.feed.getTitle().getText());
}
function handleError(e) {
alert("There was an error!");
alert(e.cause ? e.cause.statusText : e.message);
}
Wir beheben Fehler, indem wir sie einfach dem Nutzer anzeigen. Der Fehler-Handler Ihres Clients sollte wahrscheinlich komplexer sein. In einigen Kontexten ist möglicherweise kein Grund angegeben. In diesen Fällen wird in unserem Beispiel-Fehler-Handler die Standardeigenschaft message verwendet.
Da dieser Code keine Authentifizierung ermöglicht, können Sie ihn nur verwenden, um einen öffentlichen Feed abzurufen.
Authentifizierung
Die JavaScript-Clientbibliothek kann in zwei Modi verwendet werden. Wenn Sie ein Gadget schreiben, nutzt es zur Authentifizierung die sogenannte OAuth-Proxy-Funktion. Wenn auf den Zugriff über eine eigenständige JavaScript-Anwendung zugegriffen wird, verwendet er das AuthSub-Authentifizierungssystem. Informationen zur Authentifizierung finden Sie im Dokument Authentifizierungsübersicht für Google Data APIs. In diesem Abschnitt wird davon ausgegangen, dass Sie mit den Grundlagen dieses Systems vertraut sind.
Ändern Sie die Feed-URL vor der Authentifizierung mit dem Beispielcode aus diesem Dokument von „öffentlich“ zu „privat“:
var feedUrl = "http://www.google.com/calendar/feeds/liz@gmail.com/private/full";
Authentifizierung in einem Webclient mit AuthSub
Das Autorisierungssystem „AuthSub for JavaScript“ ist nicht mehr verfügbar.
Stattdessen empfehlen wir die Verwendung von OAuth 2.0 für clientseitige Anwendungen.
Authentifizierung bei einem Gadget mit dem OAuth Proxy
Im Folgenden finden Sie einen kurzen Überblick darüber, was während der Authentifizierung für ein Gadget geschieht:
- Ihr Gadget wird zum ersten Mal geladen und versucht, mit einer der Google Data APIs auf die Daten des Nutzers zuzugreifen.
- Die Anfrage schlägt fehl, weil der Nutzer noch keinen Zugriff auf seine Daten gewährt hat.
Das Antwortobjekt enthält eine URL (in
response.oauthApprovalUrl) für die OAuth-Genehmigungsseite. Ihr Gadget sollte eine Methode zum Starten eines neuen Fensters mit dieser URL bereitstellen. - Auf der Genehmigungsseite entscheidet sich der Nutzer, Zugriff auf Ihr Gadget zu gewähren oder zu verweigern. Wenn der Vorgang erfolgreich war, wird der Nutzer zur angegebenen
oauth_callback-Seite weitergeleitet. Die beste Nutzererfahrung erzielen Sie mithttp://oauth.gmodules.com/gadgets/oauthcallback. - Als Nächstes schließt der Nutzer das Pop-up-Fenster. Um Ihrem Gadget mitzuteilen, dass der Nutzer die Genehmigung erteilt hat, haben wir einen Pop-up-Handler bereitgestellt, mit dem Sie das Schließen des Genehmigungsfensters erkennen können. Alternativ kann in Ihrem Gadget ein Link angezeigt werden (z.B. Ich habe den Zugriff genehmigt), über den der Nutzer nach dem Schließen dieses Fensters manuell klicken kann.
- Ihr Gadget versucht ein zweites Mal auf die Google Data API zuzugreifen, indem es die Daten des Nutzers noch einmal anfordert. Dieser Versuch war erfolgreich.
- Ihr Gadget ist authentifiziert und kann normal funktionieren.
Fügen Sie im Gadget im Abschnitt <ModulePrefs> ein <OAuth>-Element hinzu:
<ModulePrefs>
...
<OAuth>
<Service name="google">
<Access url="https://www.google.com/accounts/OAuthGetAccessToken" method="GET" />
<Request url="https://www.google.com/accounts/OAuthGetRequestToken?
scope=http://www.blogger.com/feeds/%20http://www.google.com/calendar/feeds/" method="GET" />
<Authorization url="https://www.google.com/accounts/OAuthAuthorizeToken?
oauth_callback=http://oauth.gmodules.com/gadgets/oauthcallback" />
</Service>
</OAuth>
...
</ModulePrefs>
Ändern Sie in diesem Abschnitt die folgenden Abfrageparameter:
scopeEin erforderlicher Parameter in der Anfrage-URL. Ihr Gadget kann nur auf Daten der in diesem Parameter verwendeten
scopezugreifen. In diesem Beispiel greift das Gadget auf Ihre Blogger- und Kalenderdaten zu. Ein Gadget kann wie in diesem Beispiel Daten für einen einzelnen Bereich oder für mehrere Bereiche anfordern.oauth_callbackEin optionaler Parameter in der Autorisierungs-URL. Die OAuth-Genehmigungsseite leitet zu dieser URL weiter, nachdem der Benutzer den Zugriff auf seine Daten genehmigt hat. Du kannst diesen Parameter weglassen, auf deine eigene genehmigte Seite festlegen oder vorzugsweise
http://oauth.gmodules.com/gadgets/oauthcallbackverwenden. Später bietet er die beste Nutzererfahrung, wenn Nutzer Ihr Gadget zum ersten Mal installieren. Diese Seite enthält ein JavaScript-Snippet, das das Pop-up-Fenster automatisch schließt.
Laden Sie als Nächstes die JavaScript-Clientbibliothek im Abschnitt <Content> Ihres Gadgets. Ändern Sie die Funktion setupMyService() aus den vorherigen Beispielen, um die Methode useOAuth() des Dienstobjekts aufzurufen. Damit wird dem Gadget mitgeteilt, dass zur Authentifizierung anstelle von AuthSub der OAuth-Proxy verwendet wird. Die folgende Vorlage soll Ihnen den Einstieg erleichtern:
<Content type="html">
<![CDATA[
...
<script src="https://www.google.com/jsapi"></script>
<script type="text/javascript">
var myService = null;
function setupMyService() {
myService = new google.gdata.calendar.CalendarService('exampleCo-exampleApp-1');
myService.useOAuth('google');
fetchData();
}
function initGadget() {
google.load('gdata', '2.x');
google.setOnLoadCallback(setupMyService);
}
function fetchData() {
var callback = function(response) {
if (response.oauthApprovalUrl) {
// TODO: Display "Sign in" link (response.oauthApprovalUrl contains the URL)
} else if (response.feed) {
// TODO: show results
} else {
// TODO: handle the error
}
};
myService.getEventsFeed('http://www.google.com/calendar/feeds/default/public/full', callback, callback);
}
gadgets.util.registerOnLoadHandler(initGadget);
</script>
...
]]>
</Content>
Der Anruf an google.accounts.user.login(scope) wurde entfernt. Der Proxy übernimmt die Authentifizierung für Sie.
Weitere Informationen zum Schreiben von Google Data API-Gadgets, einschließlich Details dazu, was fetchData() enthalten sollte, finden Sie in unserem Artikel zum Erstellen eines Google Data Gadgets oder in der vollständigen Dokumentation OAuth-Gadgets schreiben.
Neues Element einfügen
Wenn Sie einen neuen Kalendertermin erstellen möchten, setzen Sie die Ausführung aus dem vorherigen Beispiel fort. Ändern Sie dazu das Ende der Funktion handleMyFeed(), um eine neue Funktion aufzurufen:
function handleMyFeed(myResultsFeedRoot) {
alert("This feed's title is: " + myResultsFeedRoot.feed.getTitle().getText());
insertIntoMyFeed(myResultsFeedRoot);
}
Verwenden Sie in der neuen Funktion zuerst den Konstruktor CalendarEventEntry, um den neuen Eintrag zu erstellen. Fügen Sie dann den Eintrag ein und geben Sie dem Dienst einen Callback, der nach dem Einfügen aufgerufen werden soll.
function insertIntoMyFeed(feedRoot) {
var newEntry = new google.gdata.calendar.CalendarEventEntry({
authors: [{
name: "Elizabeth Bennet",
email: "liz@gmail.com"
}],
title: {
type: 'text',
text: 'Tennis with Darcy'
},
content: {
type: 'text',
text: 'Meet for a quick lesson'
},
locations: [{
rel: "g.event",
label: "Event location",
valueString: "Netherfield Park tennis court"
}],
times: [{
startTime: google.gdata.DateTime.fromIso8601("2007-09-23T18:00:00.000Z"),
endTime: google.gdata.DateTime.fromIso8601("2007-09-23T19:00:00.000Z")
}]
});
feedRoot.feed.insertEntry(newEntry, handleMyInsertedEntry, handleError);
}
Beachten Sie, dass der Name jeder im Konstruktor verwendeten Objekteigenschaft mit dem Namen der für diese Eigenschaft verwendeten Setter-Methode übereinstimmt. Statt beispielsweise mit dem entsprechenden JSON-Feldnamen zu übereinstimmen.
Beachten Sie außerdem, dass Sie nicht nur ISO 8601-Datums- und Uhrzeitstrings für startTime und endTime angeben können. Sie müssen diese Strings zuerst über die Methode fromIso8601() ausführen.
Der Dienst gibt eine Kopie des eingefügten Eintrags als entryRoot-Objekt zurück und übergibt dieses Objekt an den Callback:
function handleMyInsertedEntry(insertedEntryRoot) {
alert("Entry inserted. The title is: " + insertedEntryRoot.entry.getTitle().getText());
alert("The timestamp is: " + insertedEntryRoot.entry.getTimes()[0].startTime);
}
Einen bestimmten Eintrag anfordern
Wenn Sie einen bestimmten Eintrag anfordern möchten, ändern Sie zuerst die handleMyInsertedEntry()-Funktion so, dass eine neue Eingabeanfragefunktion aufgerufen wird:
function handleMyInsertedEntry(insertedEntryRoot) {
alert("Entry inserted. The title is: " + insertedEntryRoot.entry.getTitle().getText());
alert("The timestamp is: " + insertedEntryRoot.entry.getTimes()[0].startTime);
requestMySpecificEntry(insertedEntryRoot.entry.getSelfLink().getHref());
}
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.
function requestMySpecificEntry(entryURI) {
myService.getEventsEntry(entryURI, handleMySpecificEntry, handleError);
}
function handleMySpecificEntry(retrievedEntryRoot) {
myEntryRoot = retrievedEntryRoot; // Global variable for later use
alert("This entry's title is: " + retrievedEntryRoot.entry.getTitle().getText());
}
Dieses Beispiel ist im Wesentlichen mit dem Beispiel getEventsFeed() identisch, nur dass die Methode getEventEntry() des Dienstes aufgerufen wird, um einen bestimmten Eintrag abzurufen. Der URI ist etwas anders: Er verweist auf den Hauptkalender des authentifizierten Nutzers und hat am Ende eine Eintrag-ID.
Außerdem müssen wir den abgerufenen Eintrag später verwenden können, daher kopieren wir ihn in eine globale Variable.
Einträge suchen
Ändern Sie für eine Volltextsuche zuerst die Funktion handleMySpecificEntry(), um eine neue Suchfunktion aufzurufen:
function handleMySpecificEntry(retrievedEntryRoot) {
myEntryRoot = retrievedEntryRoot; // Global variable for later use
alert("This entry's title is: " + retrievedEntryRoot.entry.getTitle().getText());
searchMyFeed();
}
Verwenden Sie dann den folgenden Code, um die erste Übereinstimmung aus der Suche abzurufen:
function searchMyFeed() {
var myQuery = new google.gdata.calendar.CalendarEventQuery(feedUrl);
myQuery.setFullTextQuery("Tennis");
myQuery.setMaxResults(10);
myService.getEventsFeed(myQuery, handleMyQueryResults, handleError);
}
function handleMyQueryResults(myResultsFeedRoot) {
if (myResultsFeedRoot.feed.getEntries()[0]) {
alert("The first search-match entry's title is: " + myResultsFeedRoot.feed.getEntries()[0].getTitle().getText());
}
else {
alert("There are no entries that match the search query.");
}
}
Artikel aktualisieren
Zum Aktualisieren eines vorhandenen Elements fügen Sie zuerst am Ende von handleMyQueryResults() eine Zeile hinzu, um eine neue Aktualisierungsfunktion aufzurufen:
updateMyEntry();
Verwenden Sie dann den folgenden Code. In diesem Beispiel ändern wir den Titel des zuvor abgerufenen Eintrags (der in einem früheren Beispiel im globalen Objekt mit dem Namen myEntryRoot enthalten war) vom alten Text („Tennis mit Darcy“) in „Wichtige Besprechung“.
function updateMyEntry() {
myEntryRoot.entry.getTitle().setText("Important meeting");
myEntryRoot.entry.updateEntry(handleMyUpdatedEntry, handleError);
}
function handleMyUpdatedEntry(updatedEntryRoot) {
alert("Entry updated. The new title is: " + updatedEntryRoot.entry.getTitle().getText());
}
Wie bei allen Kalendermethoden wird mit der Methode updateEntry() automatisch der richtige Bearbeitungs-URI festgelegt, der beim Aktualisieren des Eintrags verwendet wird. Sie müssen diesen URI also nicht explizit angeben.
Elemente löschen
Wenn Sie den aktualisierten Eintrag löschen möchten, fügen Sie handleMyUpdatedEntry() zuerst eine Zeile hinzu:
deleteMyEntry(updatedEntryRoot);
Verwenden Sie dann den folgenden Code:
function deleteMyEntry(updatedEntryRoot) {
updatedEntryRoot.entry.deleteEntry(handleMyDeletedEntry, handleError);
}
function handleMyDeletedEntry() {
alert("Entry deleted");
}
Auch hier wird mit der Methode deleteEntry() automatisch der richtige Bearbeitungs-URI zum Löschen des Eintrags ermittelt.
Beachten Sie, dass kein Eintrag zurückgegeben wird. Wenn der Callback aufgerufen wird, wissen wir, dass das Löschen erfolgreich war. Wenn der Löschvorgang fehlschlägt, wird deleteEntry() anstelle von handleMyDeletedEntry() von handleError() aufgerufen.
ETags verwenden
Hinweis: ETags können nur mit Diensten verwendet werden, auf denen das Google Data Protocol v2.0 ausgeführt wird.
Einführung
In Version 2 des Google Data JavaScript-Clients wird ETags unterstützt. ETags sind Kennungen, die eine bestimmte Version eines bestimmten Eintrags angeben. Dies ist in zwei Fällen wichtig:
- Bei einem bedingten Abruf, wenn ein Client einen Eintrag anfordert und der Server den Eintrag nur dann sendet, wenn sich der Eintrag seit der letzten Anforderung durch den Client geändert hat.
- Sicherstellen, dass nicht versehentlich mehrere Änderungen von anderen Clients überschrieben werden Die Data APIs tun dies, indem Aktualisierungen und Löschungen fehlschlagen, wenn der Client ein altes ETag für den Eintrag angibt.
Es gibt zwei Arten von ETags: schwach und stark. Ein schwaches ETag beginnt immer mit W/. Beispiel: W/"D08FQn8-eil7ImA9WxZbFEw". Schwache ETags können sich bei einer Änderung des Eintrags nicht unbedingt ändern. Sie können mit HTTP also nur zum bedingten Abruf verwendet werden. Starke ETags kennzeichnen eine bestimmte Version eines bestimmten Eintrags und können sowohl für bedingte Abrufe als auch für Aktualisierungen oder Löschungen verwendet werden, um zu verhindern, dass Änderungen anderer Clients überschrieben werden. Aufgrund dieser Unterscheidung lässt die Clientbibliothek keine schwachen ETags mit einer Aktualisierungs- oder Löschanfrage senden.
ETags können an zwei Stellen in der Serverantwort gefunden werden:
- Im
ETag-HTTP-Header. - Im Feed/Eintrag als
gd:etag-Attribut.
Wenn ein Dienst Version 2 unterstützt, hat jeder Feed und jedes Eingabeobjekt die Methode getEtag(), um den Wert des ETags abzurufen.
Der JavaScript-Client unterstützt zwei Methoden, um ETags in eine Anfrage einzubinden. Das erste ist das neue opt_params-Objekt. Alle Funktionen "get", "update" und "insert" in Version 2 der Clientbibliothek haben einen neuen opt_params-Parameter. Mit diesem Objekt werden bei einer Anfrage optionale Parameter angegeben. Derzeit ist 'etag' der einzige unterstützte optionale Parameter. In Zukunft werden möglicherweise noch weitere Parameter eingeführt. So können Sie einer GET-Anfrage beispielsweise ein ETag hinzufügen:
var opt_params = {};
opt_params['etag'] = 'ETAG GOES HERE';
service.getFeed(uri, successHandler, errorHandler, opt_params);
Sie können ein ETag auch direkt einem Feed oder Eintragsobjekt hinzufügen, indem Sie die Methode setEtag() des Feeds bzw. Eintrags aufrufen.
Weitere Informationen zu ETags finden Sie in der GData-Protokoll-Referenz.
ETags zum Abrufen von Daten verwenden
ETags können beim Abrufen von Daten helfen, Bandbreite und Ausführungszeit zu reduzieren. Ein ETag kann in eine GET-Anfrage mit dem If-None-Match header: aufgenommen werden
If-None-Match: ETAG GOES HERE
Wenn das ETag mit der aktuellen Version des Feeds oder Eintrags übereinstimmt, antwortet der Server mit einer 304 NOT MODIFIED-Antwort und einem leeren Textkörper. Andernfalls antwortet der Server mit einer 200 OK-Antwort und den Feed- oder Eintragsdaten.
Sie können ETags im JavaScript-Client verwenden, indem Sie beim Senden der Anfrage den Parameter 'etag' angeben:
var etag = feed.getEtag(); // Feed loaded from a previous request
var opt_params = {};
opt_params['etag'] = etag;
service.getFeed(feedUrl, successHandler, errorHandler, opt_params);
Bedingte Abrufe funktionieren sowohl mit starken als auch mit schwachen ETags. Wenn das ETag übereinstimmt, wird der Fehler-Handler mit einer 304-Antwort aufgerufen:
function successHandler(feedRoot) {
// 200 response
// Update UI to display updates
}
function errorHandler(errorObj) {
if (errorObj.cause.getStatus() == 304) {
// 304 response, do nothing
}
// otherwise the response is some other error
}
Im Beispiel Bedingter Abruf mit Blogger finden Sie ein praktischeres Beispiel für die Verwendung von ETags im JavaScript-Client. Bei diesem Beispiel wird Blogger in Intervallen von 5 Sekunden abgefragt, um nach Aktualisierungen für Ihren Blog zu suchen. Wenn es Änderungen gibt, wird im Beispiel eine Liste von Beiträgen aktualisiert.
ETags zum Aktualisieren und Löschen von Daten verwenden
Durch die Verwendung von ETags bei Aktualisierungs-/Löschanfragen wird sichergestellt, dass die Änderungen des jeweils anderen nicht versehentlich überschrieben werden. In diesem Fall wird ein ETag in den If-Match-Header eingefügt:
If-Match: ETAG GOES HERE
Wenn das ETag in der Anfrage mit dem ETag auf dem Server übereinstimmt, ist das Update bzw. die Löschung erfolgreich. Eine ETag-Abweichung gibt jedoch an, dass sich der Eintrag geändert hat und die Aktualisierung/Löschung fehlschlägt. In diesem Fall sollte die Anwendung eine neue Instanz der Daten anfordern und dann das Update/Löschen wiederholen.
In bestimmten Fällen können Sie Ihre Änderungen erzwingen, unabhängig von anderen Änderungen am Eintrag. Dazu übergeben Sie einen * an den If-Match-Header:
If-Match: *
Beachten Sie, dass dadurch Änderungen von anderen Kunden überschrieben werden. Verwenden Sie die Einstellungen daher mit Bedacht.
Sie können nur Einträge mit einem starken ETag aktualisieren oder löschen. Die Angabe eines schwachen ETags führt zu einem Fehler. Um dies zu verhindern, legt der JavaScript-Client keine schwachen ETags bei Aktualisierungs- und Löschanfragen fest.
ETags werden genau wie bedingte Abrufe verwendet:
function updateData(entry, service) {
var etag = entry.getEtag();
var opt_params = {};
opt_params['etag'] = etag; // Or use '*' to force an update.
service.updateEntry(successHandler, errorHandler, opt_params);
}
function successHandler(response) {
// Successful update
}
function errorHandler(errorObj) {
// ERROR - Update failed. Could be due to an ETag mismatch, but check the
// error message to make sure. An ETag error will be in the format:
// Mismatch: etags = ["Qnc-fTVSLyp7ImA9WxJbFEsDRAw."], version = [1249675665358000]
}
Bei Aktualisierungen kann ein ETag an zwei Stellen angegeben werden:
- Im Eintrag mithilfe der Methoden
getEtag()undsetEtag(). - Im Header mit dem Objekt
opt_params(wie oben gezeigt)
Für einen Eintrag, der aus einer vorherigen GET-Anfrage geladen wurde, ist bereits ein ETag-Feld festgelegt. Daher ist die Angabe desselben ETags im opt_params-Objekt redundant. Wenn ein ETag sowohl im Eintrag als auch im opt_params angegeben wird, hat das ETag im opt_params Vorrang. Dies kann etwas verwirrend sein. Wenn Sie Probleme mit bedingten Updates haben, sollten Sie das ETag sowohl im Eintrag als auch im opt_params-Objekt prüfen.
Zur Vereinfachung haben die google.gdata.Entry-Klassen auch ihre eigenen updateEntry()- und deleteEntry()-Methoden. Wenn die Einstiegsklasse bereits ein ETag hat, müssen Sie es der Anfrage nicht hinzufügen. Die Client-Bibliothek erledigt das automatisch für Sie. Beispiel:
// entry was loaded from a previous request. No need to specify // an ETag in opt_params here, it is added automatically. entry.deleteEntry(successHandler, errorHandler);
Auf diese Weise profitieren Sie von ETags, ohne sich Sorgen machen zu müssen, ob Sie sie korrekt festlegen. Wenn Sie die Aktualisierung jedoch mit '*' erzwingen möchten, müssen Sie das Objekt opt_params immer mit 'etag' = '*' einfügen.
Sie können bedingte Updates bei bedingten Updates in den Kontakten sehen. Im Beispiel wird zuerst eine Testkontaktgruppe erstellt, in der alle in diesem Beispiel verwendeten Daten erstellt werden. Sie können diese Kontaktgruppe löschen, wenn Sie mit der Stichprobe fertig sind. Im Beispiel werden dann zwei iFrames mit dem Inhalt der Kontaktgruppe geladen. Sie können Aktualisierungen in einem iFrame vornehmen und sehen, wie sich dies auf Aktualisierungen im anderen iFrame auswirkt. Weitere Informationen zur Verwendung finden Sie im Beispiel.
Beispiele
- Bedingter Abruf in Blogger: Blogger alle fünf Sekunden wird abgefragt und nach Updates gesucht.
- Bedingte Aktualisierung in Kontakten: Zeigt zwei separate iFrames mit Kontaktdaten an. Sie können also festlegen, wie zwei Clients beim Erstellen, Aktualisieren und Löschen von Kontakten interagieren können.
Referenz
Referenzinformationen zu den von der Clientbibliothek bereitgestellten Klassen und Methoden finden Sie in der API-Referenz für die JavaScript-Clientbibliothek (im JSdoc-Format).