Referenz zum Google Data APIs-Protokoll

In diesem Dokument wird das von den Google Data APIs verwendete Protokoll beschrieben, einschließlich Informationen dazu, wie eine Abfrage aussieht, wie Ergebnisse aussehen usw.

Weitere Informationen zu den Google Data APIs finden Sie im Entwicklerhandbuch zu Google Data und im Protokollleitfaden.

Zielgruppe

Dieses Dokument richtet sich an Nutzer, die die Details des XML-Formats und -Protokolls der Google Data APIs verstehen möchten.

Wenn Sie nur Code schreiben möchten, der die Google Data-Client-APIs verwendet, benötigen Sie diese Details nicht. Stattdessen können Sie die sprachspezifischen Clientbibliotheken verwenden.

Informationen zu diesem Protokoll finden Sie in diesem Dokument. In diesem Dokument finden Sie beispielsweise die folgenden Informationen:

  • Bewertung der Google-Datenarchitektur
  • Codierung mit dem Protokoll, ohne die bereitgestellten Google Data-Clientbibliotheken zu verwenden
  • Clientbibliothek in einer neuen Sprache schreiben

In diesem Dokument wird davon ausgegangen, dass Sie mit den Grundlagen von XML, Namespaces, syndizierten Feeds und den GET-, POST-, PUT- und DELETE-Anfragen in HTTP sowie dem HTTP-Konzept einer Ressource vertraut sind. Weitere Informationen hierzu finden Sie im Abschnitt Zusätzliche Ressourcen in diesem Dokument.

Für dieses Dokument ist keine bestimmte Programmiersprache erforderlich. Sie können Google Data-Nachrichten mit jeder Programmiersprache senden und empfangen, mit der Sie HTTP-Anfragen senden und XML-basierte Antworten parsen können.

Protokolldetails

In diesem Abschnitt werden das Format und die Abfragesyntax von Google Data-Dokumenten beschrieben.

Dokumentformat

Google Data, Atom und RSS 2.0 nutzen dasselbe grundlegende Datenmodell: ein Container, der sowohl globale Daten als auch eine beliebige Anzahl von Einträgen enthält. Für jedes Protokoll wird das Format durch ein Basisschema definiert. Es kann jedoch mit fremden Namespaces erweitert werden.

Die Google Data APIs können entweder das Atom-Syndikationsformat (für Lese- und Schreibvorgänge) oder das RSS-Format (nur für Lesevorgänge) verwenden.

Atom ist das Standardformat von Google Data. Wenn Sie eine Antwort im RSS-Format anfordern möchten, verwenden Sie den Parameter /alt=rss/. Weitere Informationen finden Sie unter Anfrageanfragen.

Wenn Sie Daten im RSS-Format anfordern, stellt Google Data einen Feed (oder eine andere Darstellung der Ressource) im RSS-Format bereit. Wenn für eine Google-Daten-Property keine entsprechende RSS-Property vorhanden ist, verwendet Google Data die Atom-Property und kennzeichnet sie mit einem geeigneten Namespace, um anzugeben, dass es sich um eine Erweiterung von RSS handelt.

Hinweis: In den meisten Google-Datenfeeds im Atom-Format wird der Atom-Namespace als Standard-Namespace verwendet. Dazu wird im Feedelement ein xmlns-Attribut angegeben. Beispiele hierfür finden Sie im Abschnitt „Beispiele“. Daher wird in den Beispielen dieses Dokuments nicht explizit atom: für Elemente in einem Atom-Format-Feed angegeben.

Die folgenden Tabellen zeigen die Atom- und RSS-Darstellungen der Elemente des Schemas. Alle Daten, die in diesen Tabellen nicht genannt sind, werden als einfacher XML-Code behandelt und in beiden Darstellungen angezeigt. Sofern nicht anders angegeben, befinden sich die XML-Elemente in einer bestimmten Spalte im Namespace, der dieser Spalte entspricht. In dieser Zusammenfassung wird die standardmäßige XPath-Notation verwendet: Schrägstriche zeigen die Elementhierarchie an und ein @-Zeichen steht für ein Attribut eines Elements.

In jeder der folgenden Tabellen sind die markierten Elemente erforderlich.

In der folgenden Tabelle sehen Sie die Elemente eines Google-Datenfeeds:

Feedelementschema-Element Atom-Darstellung RSS-Darstellung
Feedtitel /feed/title /rss/channel/title
Feed-ID /feed/id /rss/channel/atom:id
Feed-HTML-Link /feed/link[@rel="alternate"] \
[@type="text/html"]/@href
/rss/channel/link
Feedbeschreibung /feed/subtitle /rss/channel/description
Feedsprache /feed/@xml:lang /rss/channel/language
Feed-Urheberrecht /feed/rights /rss/channel/copyright
Feedautor

/feed/author/name
/feed/author/email

(In bestimmten Fällen erforderlich, siehe Atom-Spezifikation.)

/rss/channel/managingEditor
Datum der letzten Aktualisierung des Feeds /feed/updated
(RFC 3339-Format)
/rss/channel/lastBuildDate
(RFC 822-Format)
Feedkategorie /feed/category/@term /rss/channel/category
Schema der Feedkategorie /feed/category/@scheme /rss/channel/category/@domain
Feed-Generator /feed/generator
/feed/generator/@uri
/rss/channel/generator
Feedsymbol /feed/icon /rss/channel/image/url (es sei denn, es gibt auch ein Logo; in diesem Fall ist das Symbol nicht im Feed enthalten)
Feed-Logo /feed/logo /rss/channel/image/url

In der folgenden Tabelle sehen Sie die Elemente eines Google Data-Suchergebnisses. Beachten Sie, dass Google-Daten einige der OpenSearch 1.1-Antwortelemente in den Suchergebnisfeeds enthalten.

Schemaelement für Suchergebnisfeed Atom-Darstellung RSS-/OpenSearch-Darstellung
Anzahl der Suchergebnisse /feed/openSearch:totalResults /rss/channel/openSearch:totalResults
Startindex der Suchergebnisse /feed/openSearch:startIndex /rss/channel/openSearch:startIndex
Anzahl der Suchergebnisse pro Seite /feed/openSearch:itemsPerPage /rss/channel/openSearch:itemsPerPage

Die folgende Tabelle zeigt die Elemente eines Google-Dateneintrags:

Eintragschemaelement Atom-Darstellung RSS-Darstellung
Eintrags-ID /feed/entry/id /rss/channel/item/guid
Eintragsversions-ID Optional in EditURI eingebettet (siehe Abschnitt Optimistische Gleichzeitigkeit dieses Dokuments).
Titel des Eintrags /feed/entry/title /rss/channel/item/title
Link zur Teilnahme /feed/entry/link /rss/channel/item/link
/rss/channel/item/enclosure
/rss/channel/item/comments
Beitragsübersicht

/feed/entry/summary

(In bestimmten Fällen erforderlich, siehe Atom-Spezifikation.)

/rss/channel/item/atom:summary
Inhalt des Eintrags

/feed/entry/content

Wenn kein Inhaltselement vorhanden ist, muss der Eintrag mindestens ein <link rel="alternate">-Element enthalten.

/rss/channel/item/description
Beitragsautor

/feed/entry/author/name
/feed/entry/author/email

(In bestimmten Fällen erforderlich, siehe Atom-Spezifikation.)

/rss/channel/item/author
Eintragskategorie /feed/entry/category/@term /rss/channel/item/category
Schema der Einstiegskategorie /feed/entry/category/@scheme /rss/channel/item/category/@domain
Veröffentlichungsdatum des Beitrags /feed/entry/published
(RFC 3339)
/rss/channel/item/pubDate
(RFC 822)
Aktualisierungsdatum des Eintrags /feed/entry/updated
(RFC 3339)
/rss/channel/item/atom:updated
(RFC 3339)

Abfragen

In diesem Abschnitt wird die Verwendung des Abfragesystems beschrieben.

Designgrundsätze des Abfragemodells

Das Abfragemodell ist absichtlich sehr einfach gehalten. Die Grundsätze sind:

  • Abfragen werden als HTTP-URIs und nicht als HTTP-Header oder als Teil der Nutzlast ausgedrückt. Ein Vorteil dieses Ansatzes besteht darin, dass Sie eine Verknüpfung zu einer Abfrage herstellen können.
  • Prädikate werden auf ein einzelnes Element beschränkt. Daher gibt es keine Möglichkeit, eine Korrelationsabfrage wie „Alle E-Mails von Nutzern suchen, die mir heute mindestens 10 E-Mails gesendet haben“ zu senden.
  • Die Gruppe von Eigenschaften, auf die sich Suchanfragen prädizieren können, ist sehr begrenzt. Die meisten Abfragen sind einfach Volltextsuchanfragen.
  • Die Ergebnisreihenfolge hängt von der Implementierung ab.
  • Das Protokoll ist natürlich erweiterbar. Wenn Sie in Ihrem Dienst zusätzliche Prädikate oder Sortierungen bereitstellen möchten, können Sie dies durch die Einführung neuer Parameter ganz einfach tun.

Abfrageanfragen

Ein Client fragt einen Google Data-Dienst ab, indem er eine HTTP-GET-Anfrage ausgibt. Der Abfrage-URI besteht aus dem URI der Ressource (in Atom FeedURI genannt), gefolgt von Suchparametern. Die meisten Suchparameter werden als herkömmliche ?name=value[&...]-URL-Parameter dargestellt. Kategorieparameter werden anders behandelt (siehe unten).

Wenn der FeedURI beispielsweise http://www.example.com/feeds/jo lautet, können Sie eine Abfrage mit dem folgenden URI senden:

http://www.example.com/feeds/jo?q=Darcy&updated-min=2005-04-19T15:30:00Z

Google Data-Dienste unterstützen die bedingte HTTP-Anfrage GET. Sie legen den Antwortheader „Zuletzt geändert“ anhand des Werts des <atom:updated>-Elements im zurückgegebenen Feed oder Eintrag fest. Ein Client kann diesen Wert als Wert des Anfrageheaders „If-Modified-Since“ zurücksenden, um zu vermeiden, dass der Inhalt noch einmal abgerufen wird, wenn er sich nicht geändert hat. Wenn sich der Inhalt seit dem Zeitpunkt „If-Modified-Since“ nicht geändert hat, gibt der Google-Datendienst die HTTP-Antwort „304 (Nicht geändert)“ zurück.

Ein Google Data-Dienst muss Kategorie- und alt-Abfragen unterstützen. Die Unterstützung für andere Parameter ist optional. Das Übergeben eines Standardparameters, der von einem bestimmten Dienst nicht verstanden wird, führt zu einer 403 Forbidden-Antwort. Das Übergeben eines nicht unterstützten nicht standardmäßigen Parameters führt zu einer 400 Bad Request-Antwort. Informationen zu anderen Statuscodes finden Sie im Abschnitt HTTP-Statuscodes in diesem Dokument.

Die Standardabfrageparameter sind in der folgenden Tabelle zusammengefasst. Alle Parameterwerte müssen URL-codiert sein.

Parameter Bedeutung Hinweise
q Volltext-Abfragestring
  • Geben Sie beim Erstellen einer Abfrage Suchbegriffe an, die durch Leerzeichen getrennt sind und das Format q=term1 term2 term3 haben. Wie bei allen Abfrageparameterwerten müssen die Leerzeichen URL-codiert sein. Der Google-Datendienst gibt alle Einträge zurück, die mit allen Suchbegriffen übereinstimmen. So wird z. B. AND zwischen den Begriffen verwendet. Wie bei der Google Websuche sucht ein Datendienst von Google nach vollständigen Wörtern (und ähnlichen Wörtern mit demselben Wortstamm), nicht nach Teilstrings.
  • Wenn Sie nach einer genauen Wortgruppe suchen möchten, setzen Sie sie in Anführungszeichen: q="exact phrase".
  • Verwenden Sie das Formular q=-term, um Einträge auszuschließen, die einem bestimmten Begriff entsprechen.
  • Bei der Suche wird nicht zwischen Groß- und Kleinschreibung unterschieden.
  • Beispiel: Wenn Sie nach allen Einträgen suchen möchten, die die genaue Wortgruppe „Elizabeth Bennet“ und das Wort „Darcy“ enthalten, aber nicht das Wort „Austen“ enthalten, verwenden Sie die folgende Abfrage: ?q="Elizabeth Bennet" Darcy -Austen
/-/category Kategoriefilter
  • Listen Sie jede Kategorie so auf, als wäre sie Teil des URI der Ressource im Format /categoryname/. Dies ist eine Ausnahme vom üblichen name=value-Formular.
  • Alle Kategorien vor anderen Suchparametern auflisten
  • Stellen Sie der ersten Kategorie /-/ voran, um deutlich zu machen, dass es sich um eine Kategorie handelt. Wenn beispielsweise der Feed von Jos Dateien eine Kategorie für Einträge über Fritz enthält, können Sie diese Einträge wie den folgenden anfordern: http://www.example.com/feeds/jo/-/Fritz. Dadurch kann die Implementierung kategoriebasierte Abfrage-URIs von Ressourcen-URIs unterscheiden.
  • Sie können mehrere Kategorien abfragen, indem Sie mehrere Kategorieparameter getrennt durch Schrägstriche auflisten. Der Google-Datendienst gibt alle Einträge zurück, die mit allen Kategorien übereinstimmen. Verwenden Sie z. B. AND zwischen den Begriffen. Beispiel: http://www.example.com/feeds/jo/-/Fritz/Laurie gibt Einträge zurück, die mit beiden Kategorien übereinstimmen.
  • Wenn Sie ein OR zwischen den Begriffen verwenden möchten, verwenden Sie ein Pipe-Zeichen (|), das als %7C codiert ist. Beispiel: http://www.example.com/feeds/jo/-/Fritz%7CLaurie gibt Einträge zurück, die mit einer der beiden Kategorien übereinstimmen.
  • Ein Eintrag stimmt mit einer angegebenen Kategorie überein, wenn der Eintrag in einer Kategorie mit einem übereinstimmenden Begriff oder Label enthalten ist, wie in der Atom-Spezifikation definiert. Ungefähr ist der Begriff der interne String, den die Software zur Identifizierung der Kategorie verwendet. Das Label ist der für Menschen lesbare String, der dem Nutzer auf einer Benutzeroberfläche angezeigt wird.
  • Verwenden Sie das Formular /-categoryname/, um Einträge auszuschließen, die einer bestimmten Kategorie entsprechen.
  • Wenn Sie eine Kategorie mit einem Schema abfragen möchten, z. B. <category scheme="urn:google.com" term="public"/>, müssen Sie das Schema in geschweiften Klammern vor dem Kategorienamen platzieren. Beispiel: /{urn:google.com}public Wenn das Schema einen Schrägstrich (/) enthält, sollte es als %2F codiert sein. Um eine Kategorie ohne Schema abzugleichen, verwenden Sie ein leeres Paar geschweifte Klammern. Wenn Sie keine geschweiften Klammern angeben, stimmen Kategorien in jedem Schema überein.
  • Die oben genannten Funktionen können kombiniert werden. Beispiel: /A%7C-{urn:google.com}B/-C bedeutet (A OR (NOT B)) AND (NOT C).
category Kategoriefilter
  • Eine alternative Methode zum Ausführen eines Kategoriefilters. Die beiden Methoden sind äquivalent.
  • Wenn Sie ein OR zwischen den Begriffen verwenden möchten, verwenden Sie ein Pipe-Zeichen (|), das als %7C codiert ist. Beispiel: http://www.example.com/feeds?category=Fritz%7CLaurie gibt Einträge zurück, die mit einer der beiden Kategorien übereinstimmen.
  • Wenn Sie ein AND zwischen zwei Begriffen eingeben möchten, verwenden Sie ein Komma (,). Beispiel: http://www.example.com/feeds?category=Fritz,Laurie gibt Einträge zurück, die mit beiden Kategorien übereinstimmen.
author Beitragsautor
  • Der Dienst gibt Einträge zurück, bei denen der Name des Autors und/oder die E-Mail-Adresse mit dem Abfragestring übereinstimmen.
alt Alternativer Darstellungstyp
  • Wenn Sie keinen alt-Parameter angeben, gibt der Dienst einen Atom-Feed zurück. Das entspricht alt=atom.
  • alt=rss gibt einen RSS 2.0-Ergebnisfeed zurück.
  • alt=json gibt eine JSON-Darstellung des Feeds zurück. Weitere Informationen
  • alt=json-in-script fordert eine Antwort an, die JSON in einem Skript-Tag umschließt. Weitere Informationen
updated-min, updated-max Grenzwerte für das Eintragsaktualisierungsdatum
  • Verwenden Sie das Zeitstempelformat RFC 3339. Beispiel: 2005-08-09T10:57:00-08:00.
  • Die Untergrenze ist inklusive, während die Obergrenze ausgeschlossen ist.
published-min, published-max Grenze am Veröffentlichungsdatum des Eintrags
  • Verwenden Sie das Zeitstempelformat RFC 3339. Beispiel: 2005-08-09T10:57:00-08:00.
  • Die Untergrenze ist inklusive, während die Obergrenze ausgeschlossen ist.
start-index 1-basierter Index des ersten abzurufenden Ergebnisses
  • Dies ist kein allgemeiner Mechanismus zum Bewegen des Cursors. Wenn Sie zuerst eine Abfrage mit ?start-index=1&max-results=10 und dann eine weitere Abfrage mit ?start-index=11&max-results=10 senden, kann der Dienst nicht garantieren, dass die Ergebnisse ?start-index=1&max-results=20 entsprechen. Dies liegt daran, dass Einfügungen und Löschungen zwischen den beiden Abfragen stattgefunden haben könnten.
max-results Maximale Anzahl der abzurufenden Ergebnisse Für jeden Dienst mit dem Standardwert max-results (zur Beschränkung der Standardgröße des Feeds) können Sie eine sehr große Zahl angeben, um den gesamten Feed zu erhalten.
entryID ID eines bestimmten abzurufenden Eintrags
  • Wenn Sie eine Eingabe-ID angeben, können Sie keine anderen Parameter festlegen.
  • Das Format der Eintrags-ID wird vom Google Data-Dienst bestimmt.
  • Im Gegensatz zu den meisten anderen Abfrageparametern wird die Eingabe-ID als Teil des URI und nicht als Name=Wert-Paar angegeben.
  • Beispiel: http://www.example.com/feeds/jo/entry1.

Kategorieabfragen

Wir haben uns für ein etwas ungewöhnliches Format für Kategorieabfragen entschieden. Anstelle einer Abfrage wie der folgenden:

http://example.com/jo?category=Fritz&category=2006

verwenden wir:

http://example.com/jo/-/Fritz/2006

Dieser Ansatz identifiziert eine Ressource ohne die Verwendung von Abfrageparametern und erzeugt sauberere URIs. Wir haben uns für Kategorien entschieden, weil wir der Meinung sind, dass am häufigsten Kategorieanfragen verwendet werden.

Der Nachteil dieses Ansatzes besteht darin, dass Sie /-/ in Kategorieabfragen verwenden müssen, damit Google Data-Dienste Kategorieabfragen von anderen Ressourcen-URIs wie http://example.com/jo/MyPost/comments unterscheiden können.

Abfrageantworten

Abfragen geben je nach Anfrageparameter einen Atom-Feed, einen Atom-Eintrag oder einen RSS-Feed zurück.

Abfrageergebnisse enthalten die folgenden OpenSearch-Elemente direkt unter dem <feed>- oder <channel>-Element (je nachdem, ob die Ergebnisse Atom oder RSS sind):

openSearch:totalResults
Die Gesamtzahl der Suchergebnisse für die Suchanfrage (nicht unbedingt alle im Ergebnisfeed).
openSearch:startIndex
Der 1-basierte Index des ersten Ergebnisses.
openSearch:itemsPerPage
Die maximale Anzahl von Elementen, die auf einer Seite angezeigt werden. Dadurch können Kunden direkte Links zu beliebigen anderen Seiten generieren. Eine mögliche Störung bei der Verwendung dieser Zahl können Sie dem Hinweis zu start-index in der Tabelle im Abschnitt Abfrageanfragen entnehmen.

Der Atom-Antwortfeed und die Einträge können auch die folgenden Atom- und Google Data-Elemente enthalten (sowie weitere, die in der Atom-Spezifikation aufgeführt sind):

<link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="..."/>
Gibt den URI an, unter dem der vollständige Atom-Feed abgerufen werden kann.
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="..."/>
Gibt den PostURI des Atom-Feeds an, über den neue Einträge gepostet werden können.
<link rel="self" type="..." href="..."/>
Enthält den URI dieser Ressource. Der Wert des Attributs type hängt vom angefragten Format ab. Wenn sich in der Zwischenzeit keine Daten ändern, wird beim Senden einer weiteren GET-Anfrage an diesen URI dieselbe Antwort zurückgegeben.
<link rel="previous" type="application/atom+xml" href="..."/>
Gibt den URI des vorherigen Teils dieses Abfrageergebnissatzes an, wenn er aufgeteilt wird.
<link rel="next" type="application/atom+xml" href="..."/>
Gibt den URI des nächsten Teils dieses Abfrageergebnissatzes an, wenn er aufgeteilt wird.
<link rel="edit" type="application/atom+xml" href="..."/>
Gibt den EditURI des Atom-Eintrags an, über den Sie einen aktualisierten Eintrag senden.

Hier ist ein Beispiel für einen Antworttext als Antwort auf eine Suchanfrage:

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns:atom="http://www.w3.org/2005/Atom"
        xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/">
  <id>http://www.example.com/feed/1234.1/posts/full</id> 
  <updated>2005-09-16T00:42:06Z</updated> 
  <title type="text">Books and Romance with Jo and Liz</title> 
  <link rel="alternate" type="text/html" href="http://www.example.net/"/> 
  <link rel="http://schemas.google.com/g/2005#feed"
    type="application/atom+xml"
    href="http://www.example.com/feed/1234.1/posts/full"/> 
  <link rel="http://schemas.google.com/g/2005#post"
    type="application/atom+xml"
    href="http://www.example.com/feed/1234.1/posts/full"/> 
  <link rel="self" type="application/atom+xml"
    href="http://www.example.com/feed/1234.1/posts/full"/> 
  <author>
    <name>Elizabeth Bennet</name> 
    <email>liz@gmail.com</email> 
  </author>
  <generator version="1.0"
    uri="http://www.example.com">Example Generator Engine</generator> 
  <openSearch:totalResults>2</openSearch:totalResults> 
  <openSearch:startIndex>0</openSearch:startIndex> 
  <entry>
    <id>http://www.example.com/feed/1234.1/posts/full/4521614025009481151</id> 
    <published>2005-01-09T08:00:00Z</published> 
    <updated>2005-01-09T08:00:00Z</updated> 
    <category scheme="http://www.example.com/type" term="blog.post"/> 
    <title type="text">This is the title of entry 1009</title> 
    <content type="xhtml">
      <div
        xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1009</div> 
    </content>
    <link rel="alternate" type="text/html"
      href="http://www.example.com/posturl"/> 
    <link rel="edit" type="application/atom+xml"
      href="http://www.example.com/feed/1234.1/posts/full/4521614025009481151"/> 
    <author>
      <name>Elizabeth Bennet</name> 
      <email>liz@gmail.com</email> 
    </author>
  </entry>
  <entry>
    <id>http://www.example.com/feed/1234.1/posts/full/3067545004648931569</id> 
    <published>2005-01-07T08:00:00Z</published> 
    <updated>2005-01-07T08:02:00Z</updated> 
    <category scheme="http://www.example.com/type" term="blog.post"/> 
    <title type="text">This is the title of entry 1007</title> 
    <content type="xhtml">
      <div
        xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1007</div> 
    </content>
    <link rel="alternate" type="text/html"
      href="http://www.example.com/posturl"/> 
    <link rel="edit" type="application/atom+xml"
      href="http://www.example.com/feed/1234.1/posts/full/3067545004648931569"/> 
    <author>
      <name>Elizabeth Bennet</name> 
      <email>liz@gmail.com</email> 
    </author>
  </entry>
</feed>

Wenn der angeforderte Feed im Atom-Format vorliegt, keine Suchparameter angegeben hat und das Ergebnis nicht alle Einträge enthält, wird das folgende Element in den Feed der obersten Ebene eingefügt: <link rel="next" type="application/atom+xml" href="..."/>. Sie verweist auf einen Feed mit den nächsten Einträgen. Die nachfolgenden Sätze enthalten ein entsprechendes <link rel="previous" type="application/atom+xml" href="..."/>-Element. Durch Aufrufen aller nächsten Links kann ein Client alle Einträge aus einem Feed abrufen.

HTTP-Statuscodes

In der folgenden Tabelle wird beschrieben, was verschiedene HTTP-Statuscodes im Kontext der Google Data-Dienste bedeuten.

Code Erklärung
200 OK Kein Fehler
201 – ERSTELLT Eine Ressource wurde erstellt.
304 NICHT GEÄNDERT Die Ressource hat sich seit der im Header "If-Modified-Since" angegebenen Anfrage nicht geändert.
400 FEHLERANFRAGE Ungültiger Anfrage-URI oder -Header oder nicht unterstützter nicht standardgemäßer Parameter.
401 NICHT AUTORISIERT Genehmigung erforderlich.
403 VERBOTEN Nicht unterstützter Standardparameter oder Authentifizierung oder Autorisierung fehlgeschlagen.
404 NICHT GEFUNDEN Ressource (z. B. Feed oder Eintrag) nicht gefunden.
KONFLIKT 409 Die angegebene Versionsnummer stimmt nicht mit der neuesten Versionsnummer der Ressource überein.
500 INTERNER SERVERFEHLER Interner Fehler. Dies ist der Standardcode, der für alle nicht erkannten Fehler verwendet wird.

Optimistische Gleichzeitigkeit (Versionsverwaltung)

Manchmal ist es wichtig, dass Änderungen von Kunden nicht versehentlich deren Änderungen überschreiben. Dies lässt sich am einfachsten erreichen, indem sichergestellt wird, dass die aktuelle Version eines Eintrags, die ein Client ändert, mit der Version übereinstimmt, auf der die Änderungen durch den Client basieren. Wenn ein zweiter Client eine Aktualisierung vor dem ersten Client vornimmt, wird die Aktualisierung des ersten Clients abgelehnt, da die Änderungen im ersten Client nicht mehr auf der neuesten Version basieren.

In Google-Datenfeeds, die die Versionsverwaltung unterstützen, fügen wir eine Versions-ID an den EditURI der einzelnen Einträge an, um diese Semantik zu erreichen. Beachten Sie, dass nur der EditURI betroffen ist, nicht die Eintrag-ID. In diesem Schema ändert jede Aktualisierung den EditURI des Eintrags und garantiert so, dass nachfolgende Updates, die auf der ursprünglichen Version basieren, fehlschlagen. Löschungen sind in Bezug auf diese Funktion natürlich identisch mit Aktualisierungen. Wenn Sie einen Löschvorgang mit einer alten Versionsnummer senden, schlägt der Löschvorgang fehl.

Nicht alle Google-Datenfeeds unterstützen optimistische Gleichzeitigkeitserkennung. Wenn der Server in einem Feed, der diesen unterstützt, einen Versionskonflikt auf PUT oder DELETE erkennt, antwortet der Server mit 409 Conflict. Der Text der Antwort enthält den aktuellen Status des Eintrags (ein Atom-Eintragsdokument). Der Kunde sollte den Konflikt lösen und die Anfrage noch einmal einreichen. Verwenden Sie dazu den EditURI aus der Antwort 409.

Motivation und Design

Dieser Ansatz für optimistische Gleichzeitigkeit ermöglicht es uns, die gewünschte Semantik zu implementieren, ohne dass ein neues Markup für Versions-IDs erforderlich ist. Das macht die Antworten von Google Data mit Nicht-Google Data Atom-Endpunkten kompatibel.

Anstelle der Angabe von Versions-IDs konnten wir auch den Aktualisierungsstempel bei jedem Eintrag (/atom:entry/atom:updated) auswählen. Es gibt jedoch zwei Probleme bei der Verwendung des Aktualisierungszeitstempels:

  • Sie funktioniert nur bei Updates, nicht beim Löschen.
  • Anwendungen werden gezwungen, Datum/Uhrzeit-Werte als Versions-IDs zu verwenden. Das macht es schwieriger, Google-Daten auf viele vorhandene Datenspeicher umzustellen.

Authentifizierung

Wenn ein Client versucht, auf einen Dienst zuzugreifen, muss er möglicherweise die Anmeldedaten des Nutzers für den Dienst angeben, um nachzuweisen, dass der Nutzer die Berechtigung hat, die betreffende Aktion auszuführen.

Der Ansatz, den ein Client für die Authentifizierung verwenden soll, hängt vom Clienttyp ab:

  • Eine Desktopanwendung sollte ein Google-spezifisches Authentifizierungssystem mit der Bezeichnung Kontoauthentifizierung für installierte Anwendungen (auch bekannt als „ClientLogin“) verwenden. Webbasierte Clients dürfen dieses System nicht verwenden.
  • Ein webbasierter Client, z. B. das Front-End eines Drittanbieters, der ein Google-Datendienst verwendet, sollte ein Google-spezifisches Authentifizierungssystem namens Account Authentication Proxy for Web-Applications (auch "AuthSub" genannt) verwenden.

Im ClientLogin-System fragt der Desktop-Client den Nutzer nach seinen Anmeldedaten und sendet diese dann an das Google-Authentifizierungssystem.

Wenn die Authentifizierung erfolgreich ist, gibt das Authentifizierungssystem ein Token zurück, das der Client beim Senden von Google-Datenanfragen in einem HTTP-Autorisierungsheader verwendet.

Falls die Authentifizierung fehlschlägt, gibt der Server den Statuscode „403 Forbidden“ zusammen mit einem WWW-Authenticate-Header zurück, der eine für die Authentifizierung anwendbare Identitätsbestätigung enthält.

Das AuthSub-System funktioniert ähnlich, mit der Ausnahme, dass der Nutzer nicht nach seinen Anmeldedaten gefragt wird, sondern eine Verbindung zu einem Google-Dienst herstellt, der Anmeldedaten anfordert. Der Dienst gibt dann ein Token zurück, das die Webanwendung verwenden kann. Der Vorteil dieses Ansatzes besteht darin, dass Google (anstatt das Web-Front-End) die Anmeldedaten des Nutzers sicher verarbeitet und speichert.

Weitere Informationen zu diesen Authentifizierungssystemen finden Sie in der Google-Datenauthentifizierungsübersicht oder in der Dokumentation zur Google-Kontoauthentifizierung.

Sitzungsstatus

Bei vielen Implementierungen der Geschäftslogik ist eine Sitzungstreue erforderlich. Damit wird der Status der Nutzersitzung erfasst.

Google erfasst den Sitzungsstatus auf zwei Arten: mithilfe von Cookies und mithilfe eines Tokens, das als Suchparameter gesendet werden kann. Beide Methoden erzielen denselben Effekt. Wir empfehlen, dass Clients eine dieser Tracking-Methoden für den Sitzungsstatus unterstützen (eine davon ist ausreichend). Wenn ein Client keine dieser Methoden unterstützt, funktioniert er zwar weiterhin mit Google Data-Diensten, die Leistung kann jedoch im Vergleich zu Clients, die diese Methoden unterstützen, beeinträchtigt sein. Wenn ein Client diese Methoden nicht unterstützt, führt jede Anfrage zu einer Weiterleitung, sodass jede Anfrage und alle zugehörigen Daten zweimal an den Server gesendet werden. Dies wirkt sich sowohl auf die Leistung des Clients als auch auf den Server aus.

Die Google-Clientbibliotheken verarbeiten den Sitzungsstatus für Sie. Wenn Sie also unsere Bibliotheken verwenden, müssen Sie nichts unternehmen, um Unterstützung für den Sitzungsstatus zu erhalten.

Weitere Informationen

Die folgenden Dokumente von Drittanbietern sind möglicherweise hilfreich:

Nach oben