Diese Seite wurde von der Cloud Translation API übersetzt.

Protokollreferenz

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 das Google-Datenprotokoll beschrieben, das von vielen Google APIs verwendet wird, einschließlich Informationen dazu, wie eine Abfrage aussieht, wie Ergebnisse aussehen usw.

Weitere Informationen zum Google-Datenprotokoll finden Sie auf der Übersichtsseite des Entwicklerhandbuchs und im Dokument Grundlagen des Protokolls.

Zielgruppe

Dieses Dokument richtet sich an Nutzer, die mehr über die Details des XML-Formats und Protokolls erfahren möchten, das von den APIs verwendet wird, die das Google-Datenprotokoll implementieren.

Wenn Sie nur Code schreiben möchten, der eine dieser APIs verwendet, brauchen Sie diese Details nicht zu kennen. Verwenden Sie stattdessen die sprachspezifischen Clientbibliotheken.

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

Bewertung der Architektur des Google-Datenprotokolls
Codierung mit dem Protokoll, ohne die bereitgestellten 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 Protocol-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 Protocol beschrieben.

Dokumentformat

Das Google-Datenprotokoll und Atom verwenden 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.

Atom ist das Standardformat für das Google-Datenprotokoll. Wenn Sie eine Antwort in einem anderen Format anfordern möchten, verwenden Sie den alt-Abfrageparameter. Weitere Informationen finden Sie unter Abfrageanfragen.

Hinweis: Die meisten Google Data Protocol-Feeds im Atom-Format verwenden den Atom-Namespace als Standard-Namespace. Geben Sie dazu für das Feedelement das Attribut xmlns an, wie in den Beispielen unter Protokollgrundlagen gezeigt. 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-Darstellung der Elemente des Schemas. Alle Daten, die in diesen Tabellen nicht genannt sind, werden als einfacher XML-Code behandelt. Sofern nicht anders angegeben, befinden sich die XML-Elemente in einer bestimmten Spalte im Atom-Namespace.

Hinweis: In dieser Zusammenfassung wird die Standard-XPath-Notation verwendet, insbesondere Schrägstriche, die die Elementhierarchie zeigen und ein @-Zeichen ein Attribut eines Elements angibt.

In jeder der folgenden Tabellen sind die markierten Elemente erforderlich.

In der folgenden Tabelle sehen Sie die Elemente eines Google Data Protocol-Feeds:

Feedelementschema-Element	Atom-Darstellung
Feedtitel	`/feed/title`
Feed-ID	`/feed/id`
Feed-HTML-Link	`/feed/link[@rel="alternate"]`\ `[@type="text/html"]/@href`
Feedbeschreibung	`/feed/subtitle`
Feedsprache	`/feed/@xml:lang`
Feed-Urheberrecht	`/feed/rights`
Feedautor	`/feed/author/name` `/feed/author/email` (In bestimmten Fällen erforderlich, siehe Atom-Spezifikation.)
Datum der letzten Aktualisierung des Feeds	`/feed/updated` (RFC 3339-Format)
Feedkategorie	`/feed/category/@term`
Schema der Feedkategorie	`/feed/category/@scheme`
Feed-Generator	`/feed/generator` `/feed/generator/@uri`
Feedsymbol	`/feed/icon`
Feed-Logo	`/feed/logo`

Die folgende Tabelle zeigt die Elemente eines Google Data Protocol-Suchergebnisses. Beachten Sie, dass das Protokoll einige der OpenSearch 1.1-Antwortelemente in Suchergebnisfeeds anzeigt.

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

Die folgende Tabelle zeigt die Elemente eines Google Data Protocol-Eintrags:

Eintragschemaelement	Atom-Darstellung
Eintrags-ID	`/feed/entry/id`
Titel des Eintrags	`/feed/entry/title`
Link zur Teilnahme	`/feed/entry/link`
Beitragsübersicht	`/feed/entry/summary` (In bestimmten Fällen erforderlich, siehe Atom-Spezifikation.)
Inhalt des Eintrags	`/feed/entry/content` Wenn kein Inhaltselement vorhanden ist, muss der Eintrag mindestens ein `<link rel="alternate">`-Element enthalten.
Beitragsautor	`/feed/entry/author/name` `/feed/entry/author/email` (In bestimmten Fällen erforderlich, siehe Atom-Spezifikation.)
Eintragskategorie	`/feed/entry/category/@term`
Schema der Einstiegskategorie	`/feed/entry/category/@scheme`
Veröffentlichungsdatum des Beitrags	`/feed/entry/published` (RFC 3339)
Aktualisierungsdatum des Eintrags	`/feed/entry/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-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

Das Google Data-Protokoll unterstützt die bedingte HTTP-Anfrage GET. APIs, die das Protokoll implementieren, legen den Antwortheader „Last-Modified“ 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 Dienst die HTTP-Antwort „304 (Nicht geändert)“ zurück.

APIs, die das Google-Datenprotokoll implementieren, müssen 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
`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 (nur für Lesevorgänge). Wenn Sie Daten von einem Dienst im RSS-Format anfordern, stellt der Dienst einen Feed (oder eine andere Darstellung der Ressource) im RSS-Format bereit. Wenn für eine bestimmte Data API-Property keine entsprechende RSS-Property vorhanden ist, verwendet der Dienst die Atom-Property und kennzeichnet sie mit einem geeigneten Namespace, um anzugeben, dass es sich um eine Erweiterung von RSS handelt. `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 `alt=atom-in-script` Fordert eine Atom-Antwort an, die einen XML-String in einem Skript-Tag umschließt. `alt=rss-in-script` Fordert eine RSS-Antwort an, die einen XML-String in einem Skript-Tag umschließt. `alt=atom-service` Fordert ein Atom-Dienstdokument an, das den Feed beschreibt.
`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.
`category`	Kategorieabfragefilter	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.
`/-/category`	Kategorieabfragefilter	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 Dienst gibt alle Einträge zurück, die allen Kategorien entsprechen (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)`.
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 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`.
`fields`	Antwortfilter	Gibt nur die angeforderten Felder und nicht die vollständige Ressourcendarstellung zurück. Beispiel: http://www.example.com/feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit'])) Wenn er diese Anfrage erhält, gibt der Server eine Antwort zurück, die nur Link- und Eingabeelemente für den Feed enthält. Darüber hinaus sind die zurückgegebenen Elemente Teileinträge, die nur ETag-, ID-, aktualisierte und Bearbeitungsverknüpfungen enthalten. Der Feldwert muss wie bei allen Abfrageparametern URL-codiert sein. Weitere Informationen finden Sie im Abschnitt Teilantwort. Dieser Parameter ist eine experimentelle Funktion.
`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.
`prettyprint`	Gibt eine XML-Antwort mit Kennzeichnungen und Zeilenumbrüchen zurück	Wenn `prettyprint=true`, ist die vom Server zurückgegebene XML-Datei für Menschen lesbar. Standardwert: `prettyprint=false`
`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.
`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 Dienst gibt alle Einträge zurück, die allen Suchbegriffen entsprechen, z. B. `AND` zwischen den Begriffen. Wie bei der Google Websuche sucht ein Dienst 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`
`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.
`strict`	Strenge Abfrageparameterprüfung	Legen Sie `strict=true` fest, um zu prüfen, ob alle Ihre Abfrageparameter vom Dienst erkannt werden. Wenn ein Parameter nicht erkannt wird, wird ein Fehler zurückgegeben. Standardwert: `strict=false`
`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. In einigen Fällen, z. B. bei Verwendung von Version 2.1 oder neuer der Calendar Data API, wird durch Angabe einer `updated-min`, die zu weit in der Vergangenheit liegt, der Status HTTP 410 (Nicht mehr vorhanden) zurückgegeben.

Kategorieabfragen

Wir haben beschlossen, ein etwas ungewöhnliches Format für Kategorieabfragen bereitzustellen. Anstatt eine Abfrage wie die folgende zu verlangen:

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

haben wir Folgendes eingeführt:

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 Kategorieabfragen zu den häufigsten Suchanfragen gehören.

Der Nachteil dieses Ansatzes ist, dass Sie bei dieser Art von Kategorieabfragen /-/ verwenden müssen, damit 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 eines der folgenden Atom- und Data API-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="http://www.w3.org/2005/Atom"
        xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
        xmlns:gd='http://schemas.google.com/g/2005'
        gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
  <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 gd:etag='W/"C0QBRXcycSp7ImA9WxRVGUo."'>
    <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 gd:etag='W/"C0QBRXrurSp7ImA9WxRVGUo."'>
    <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 Daten-APIs 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.
410 GELÖSCHT	Der angeforderte Änderungsverlauf ist nicht mehr auf dem Server verfügbar. Weitere Informationen finden Sie in der dienstspezifischen Dokumentation.
500 INTERNER SERVERFEHLER	Interner Fehler. Dies ist der Standardcode, der für alle unbekannten Serverfehler verwendet wird.

Ressourcenversionsverwaltung (ETags)

Manchmal müssen Sie auf eine bestimmte Version eines bestimmten Eintrags verweisen.

Das ist insbesondere in zwei Fällen wichtig:

einen bedingten Abruf durchführen, bei dem Ihr Client einen Eintrag anfordert und der Server den Eintrag nur dann sendet, wenn er sich seit der letzten Anforderung durch den Client geändert hat.
Sicherstellen, dass nicht versehentlich mehrere Änderungen von anderen Clients überschrieben werden Die Daten-APIs tun dies, indem Aktualisierungen und Löschungen fehlschlagen, wenn der Client eine alte Versionskennung für den Eintrag angibt.

In den beiden Google Data APIs werden diese beiden Fälle mit ETags, einem Standardteil von HTTP, verarbeitet.

Ein ETag ist eine Kennung, die eine bestimmte Version eines bestimmten Eintrags angibt. Der Server hängt ein ETag an Eingabe- und Feed-Elemente an, die es an Kunden sendet. Wenn sich ein Eintrag oder Feed ändert, ändert sich auch das ETag.

Die Google Data APIs bieten ETags an zwei Stellen: in einem ETag-HTTP-Header und in einem gd:etag-Attribut von <feed>- und <entry>-Elementen.

In den Google Data APIs ist ein ETag normalerweise ein String aus Buchstaben und Ziffern, manchmal auch Bindestriche und Punkte. Der String ist normalerweise in Anführungszeichen eingeschlossen. Die Anführungszeichen gehören zum ETag. Hier ist ein ETag von einem Data API-Eintrag: "S0wCTlpIIip7ImA0X0QI".

Es gibt zwei Arten von ETags: stark und schwach. Starke ETags kennzeichnen eine bestimmte Version eines bestimmten Eintrags und können verwendet werden, um zu verhindern, dass Änderungen anderer Clients überschrieben werden. Schwache ETags im Kontext der Google Data APIs werden nur zum bedingten Abruf verwendet. Ein schwaches ETag beginnt immer mit W/. Beispiel: W/"D08FQn8-eil7ImA9WxZbFEw."

Nicht alle Google Data APIs unterstützen starke ETags. Bei solchen Tags werden starke ETags nur für Einträge verwendet, ETags in Feeds sind immer schwach.

Hier ein Beispiel für einen Feed (einschließlich einiger HTTP-Header), der von einem Dienst abgerufen wird, der starke ETags unterstützt:

GData-Version: 2.0
ETag: W/"C0QBRXcycSp7ImA9WxRVFUk."
...
<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
  ...
  <entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
    ...
  </entry>
</feed>

Clientbibliotheken, die Version 2 der Data APIs unterstützen, verarbeiten ETags transparent für Sie. Die folgenden Informationen richten sich an Clients, die keine Clientbibliotheken verwenden, und an Leser, die an der Versionsverwaltung auf Protokollebene interessiert sind.

Hinweis: Informationen zum System für die Ressourcenversionsverwaltung in Version 1.0 der Data APIs finden Sie im Referenzhandbuch zu Version 1.0.

Bedingtes Abrufen

Wenn Sie einen bereits abgerufenen Eintrag abrufen möchten, können Sie die Effizienz verbessern, indem Sie den Server anweisen, den Eintrag nur dann zu senden, wenn er sich seit dem letzten Abruf geändert hat.

Senden Sie für diesen bedingten Abruf eine HTTP-GET-Anfrage mit einem HTTP-If-None-Match-Header. Geben Sie in der Kopfzeile das ETag des Eintrags an.

Hier ein Beispiel für einen If-None-Match-Header:

If-None-Match: W/"D08FQn8-eil7ImA9WxZbFEw."

Wenn der Server diese Anfrage empfängt, prüft er, ob der von Ihnen angeforderte Eintrag dasselbe ETag wie das von Ihnen angegebene ETag hat. Wenn die ETags übereinstimmen, bleibt der Eintrag unverändert und der Server gibt den HTTP 304-Statuscode Not Modified zurück.

Wenn die ETags nicht übereinstimmen, wurde der Eintrag seit Ihrer letzten Anforderung geändert und der Server gibt den Eintrag zurück.

Einträge aktualisieren

Die einfachste Methode, um das Überschreiben der Änderungen eines anderen Clients zu vermeiden, besteht darin, dass die Version des Eintrags, mit der Ihr Client begonnen hat, der Version entspricht, die vom Server gespeichert wurde. Wenn ein zweiter Client eine Aktualisierung vor seinem Client vornimmt, wird die Aktualisierung des Clients abgelehnt, da die Änderungen nicht mehr auf der neuesten Version basieren.

Wenn Ihr Client Daten von einem Dienst abruft, der starke ETags unterstützt, verfügt jeder Eintrag über ein ETag, das als eindeutige Versions-ID für diese Version des Eintrags fungiert.

Hinweis: Die Aktualisierung mit ETags funktioniert nur bei starken ETags. Bei Diensten mit schwachen ETags sind alle Aktualisierungen erfolgreich, unabhängig davon, ob eine andere Person den Eintrag seit dem Abrufen aktualisiert hat. Mit dem neuesten Update werden immer alle vorherigen Updates überschrieben. Senden Sie schwache ETags also beim Aktualisieren oder Löschen nicht. In diesem Fall erhalten Sie eine Fehlermeldung.

Wenn Ihr Client also ein Update an einen strong-ETags-Dienst sendet, muss er angeben, welche Version des Eintrags aktualisiert wird. Dafür gibt es zwei Möglichkeiten:

Verwenden Sie einen If-Match-HTTP-Header.
Verwende das Attribut gd:etag im Element <atom:entry>.

Wir empfehlen, nach Möglichkeit If-Match.

Wenn Sie einen Eintrag mit If-Match aktualisieren möchten, müssen Sie zuerst den entsprechenden Eintrag übernehmen. Nehmen Sie die gewünschten Änderungen am Eintrag vor und erstellen Sie dann eine neue PUT-Anfrage mit dem geänderten Eintrag. Details zu den zu verwendenden URLs finden Sie in der dienstspezifischen Dokumentation.

Fügen Sie vor dem Senden von PUT einen HTTP-If-Match-Header mit dem ETag aus dem ursprünglichen Eintrag hinzu:

If-Match: "S0wCTlpIIip7ImA0X0QI"

Senden Sie dann die PUT-Anfrage.

Wenn die Aktualisierung erfolgreich ist, gibt der Server den HTTP-Statuscode 200 OK und eine Kopie des aktualisierten Eintrags zurück.

Wenn die Aktualisierung fehlschlägt, weil das von Ihnen angegebene ETag nicht mit dem aktuellen ETag im Eintrag übereinstimmt (was bedeutet, dass sich der Eintrag auf dem Server seit dem letzten Abruf geändert hat), gibt der Server den HTTP-Statuscode 412 Precondition Failed zurück.

Wenn Sie HTTP-Header nicht einfach schreiben können oder keinen anderen Grund dafür haben, den Header If-Match zu verwenden, können Sie stattdessen das Attribut gd:etag verwenden.

Wenn Sie keinen If-Match-Header senden, verwendet der Server den gd:etag-Attributwert des aktualisierten Eintrags als impliziten If-Match-Wert.

Wenn Sie das Versionsverwaltungssystem überschreiben und den Eintrag aktualisieren möchten, unabhängig davon, ob er seit dem Abrufen von einer anderen Person aktualisiert wurde, verwenden Sie If-Match: *, anstatt das ETag im Header anzugeben.

Informationen dazu, welche Dienste starke ETags unterstützen, finden Sie im Migrationsleitfaden.

Einträge löschen

Das Löschen von Einträgen mit starken ETags funktioniert ähnlich wie das Aktualisieren.

Wenn Sie einen Eintrag mit einem starken ETag löschen möchten, rufen Sie zuerst den zu löschenden Eintrag ab und senden Sie dann eine DELETE-Anfrage an die Bearbeitungs-URL des Eintrags.

Wenn Sie sichergehen möchten, dass Sie keinen Eintrag löschen, der seit dem Abrufen durch einen anderen Client geändert wurde, fügen Sie einen HTTP-If-Match-Header ein, der den ETag-Wert des ursprünglichen Eintrags enthält.

Wenn Sie das Versionsverwaltungssystem überschreiben und den Eintrag löschen möchten, unabhängig davon, ob er seit dem Abrufen von einer anderen Person aktualisiert wurde, verwenden Sie If-Match: *, anstatt das ETag im Header anzugeben.

Wenn ein Eintrag kein starkes ETag hat, ist eine DELETE-Anfrage immer erfolgreich.

Teilantwort (experimentell)

Standardmäßig sendet der Server nach der Verarbeitung von Anfragen die vollständige Darstellung der Zielressource zurück. Bei der Teilantwort können Sie nur die gewünschten Elemente oder Attribute anstelle der vollständigen Ressourcendarstellung anfordern. Dadurch kann Ihre Clientanwendung das Übertragen, Parsen und Speichern nicht benötigter Felder vermeiden und so Netzwerk-, CPU- und Speicherressourcen effizienter nutzen.

Informationen dazu, ob eine Teilantwort für das von Ihnen verwendete Produkt verfügbar ist, finden Sie in der zugehörigen API-Dokumentation.

Wenn Sie eine Teilantwort anfordern möchten, verwenden Sie den Abfrageparameter fields, um die Elemente oder Attribute anzugeben, die zurückgegeben werden sollen. Hier ein Beispiel:

http://www.example.com/feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit']))

Die Antwort des Servers enthält nur Link- und Eintragselemente für den Feed. Die Eingabeelemente enthalten nur ETag-, ID-, aktualisierte und bearbeitete Linkinformationen. Die Syntax des Abfrageparameters fields wird in den folgenden Abschnitten behandelt. Weitere Informationen zur Antwort finden Sie unter Teilantworten verarbeiten.

Hinweis: Sie können den Abfrageparameter fields für jede Anfrage verwenden, die Daten zurückgibt. Zusätzlich zu GET umfasst dies POST und PUT (sowie PATCH, die für Teilaktualisierungen verwendet wird). Der Abfrageparameter fields wirkt sich jedoch nur auf die Antwortdaten aus. Er hat keine Auswirkungen auf die Daten, die Sie angeben müssen oder die aktualisiert oder erstellt werden.

Parameter "Fields" – Syntaxzusammenfassung

Das Format des Suchparameterwerts fields basiert auf der XPath-Syntax, unterstützt jedoch nur einen Teil der gültigen XPath-Ausdrücke. Die unterstützte Syntax wird unten zusammengefasst. Zusätzliche Beispiele finden Sie im darauffolgenden Abschnitt.

Verwenden Sie eine durch Kommas getrennte Liste, um mehrere Felder auszuwählen.
Verwenden Sie a/b, um ein Element b auszuwählen, das im Element a verschachtelt ist. Verwenden Sie a/b/c, um ein Element c auszuwählen, das in b verschachtelt ist.
Verwenden Sie das Präfix '@', um ein Attribut mit dem angegebenen Namen zu identifizieren. Lassen Sie das Präfix '@' weg, um auf ein Element zu verweisen.
Sie können Feldbedingungen anwenden, um Elemente auszuwählen, die bestimmten Kriterien entsprechen. Fügen Sie dazu Ausdrücke in Klammern „[ ]“ hinter dem Element ein, das Sie einschränken möchten.
Beispielsweise gibt fields=entry[author/name='Elizabeth'] nur Feedeinträge zurück, für die Elisabeth die Autorin ist.
Geben Sie ein Feld-Unterselektor an, um nur bestimmte Attribute oder Unterelemente anzufordern, indem Sie Ausdrücke nach jedem ausgewählten Element in Klammern "( )" setzen.
Beispielsweise gibt fields=entry(id,author/email) für jeden Feedeintrag nur die ID und die E-Mail-Adresse des Autors zurück.
Sie können Strings entweder mit doppelten oder einfachen Anführungszeichen trennen.

Um ein doppeltes oder einfaches Anführungszeichen zu maskieren, wiederholen Sie das Anführungszeichen. Beispielsweise generiert """Hello,"" he said" den String "Hello," he said und '''Hello,'' he said' den String 'Hello,' he said.
Sie können bei der Feldauswahl Platzhalter verwenden.
Mit entry/gd:* werden beispielsweise alle untergeordneten Elemente des Eintrags im Namespace gd ausgewählt und mit entry/@gd:* werden die Attribute der untergeordneten Elemente im selben Namespace ausgewählt.

Der Abfrageparameter fields dient als Ausgabefilter. Das bedeutet, dass die Teilantwort erst nach der Verarbeitung der restlichen Abfrage berechnet wird. Wenn Sie beispielsweise einen max-results-Abfrageparameter angeben, um anzugeben, dass Sie 20 Ergebnisse pro Seite wünschen, werden die ersten 20 Ergebnisse generiert und die Teilantwort daraus berechnet. Wenn die fields-Spezifikation mit keinem der ersten 20 Einträge übereinstimmt, die durch die Abfrage ausgewählt wurden, wird ein leerer Feed zurückgegeben. Die ersten 20 passenden Einträge werden nicht zurückgegeben.

Hinweis: Versuchen Sie nicht, Feldbedingungen als Abfrageauswahl zu verwenden. Versuchen Sie also nicht, einen vollständigen Feed abzurufen und Feldbedingungen anzuwenden, um relevante Elemente aus einem sehr großen Datensatz herauszufiltern. Verwenden Sie nach Möglichkeit andere Suchparameter wie start-index und max-results, um die Ergebnisse der einzelnen Abfragen auf eine überschaubare Größe zu reduzieren. Andernfalls kann die Leistungssteigerung, die durch die teilweise Reaktion möglich ist, durch die schwerwiegende Leistungseinnahme aufgewogen werden, die durch eine unsachgemäße Verwendung verursacht wird.

Feldparameter formatieren

In den folgenden Richtlinien wird erläutert, wie Sie den Wert des Abfrageparameters fields erstellen. Jede Richtlinie enthält Beispiele und beschreibt, wie sich der Parameterwert auf die Antwort auswirkt.

Hinweis: Wie bei allen Abfrageparameterwerten muss der Wert des Parameters fields URL-codiert sein. In den folgenden Beispielen wird die Codierung weggelassen, um die Lesbarkeit zu verbessern.

Identifizieren Sie die Felder, die zurückgegeben werden sollen, oder treffen Sie eine Feldauswahl.

Der Wert des Abfrageparameters fields ist eine durch Kommas getrennte Liste von Elementen oder Attributen (gemeinsam als Felder bezeichnet). Jedes Feld wird relativ zum Stammelement der Ressourcendarstellung angegeben. Wenn Sie einen Feed abrufen, werden die Felder im Verhältnis zum Element <feed> angegeben. Wenn Sie einen einzelnen Eintrag abrufen, werden die Felder im Verhältnis zum Element <entry> angegeben. Wenn das ausgewählte Element ein wiederkehrendes Element im Feed ist oder zu diesem gehört, gibt der Dienst alle Instanzen dieses Elements zurück.

Hier einige Beispiele für Feeds:

Beispiele	Auswirkung
`entry`	Gibt alle `<entry>`-Elemente und alle Unterelemente dieser Einträge zurück, aber keine anderen untergeordneten Elemente von `<feed>`.
`id,entry`	Gibt sowohl den Feed-`<id>` als auch alle `<entry>`-Elemente zurück.
`entry/title`	Gibt das `<title>`-Element für alle Feedeinträge zurück. Wenn ein verschachteltes Element zurückgegeben wird, enthält die Antwort einschließende Tags für alle übergeordneten -Elemente. Die übergeordneten Tags enthalten nur dann andere untergeordnete Elemente oder Attribute, wenn sie explizit ausgewählt wurden.
`entry/author/uri`	Gibt nur das Unterelement `<uri>` des Elements `<author>` für alle Feedeinträge zurück.
`entry/*:rating`	Gibt für alle Feedeinträge nur Unterelemente mit lokalem Namen `rating` in einem Namespace zurück.

Hier einige Beispiele für Einsteiger:

Beispiele	Auswirkung
`author`	Gibt das untergeordnete `<author>`-Element des Zieleintrags zurück.
`@gd:etag`	Gibt das Attribut `etag` des Zieleintrags zurück.
`author/uri`	Gibt das `<uri>`-Unterelement des `<author>`-Elements für den Zieleintrag zurück.
`media:group/media:*`	Gibt alle untergeordneten Felder von `<media:group>` im Namespace `media` für den Zieleintrag zurück.

Beschränken Sie die Antwort auf ausgewählte Felder, die bestimmte Kriterien erfüllen, oder verwenden Sie Feldbedingungen.

Wenn in Ihrer Anfrage ein Element angegeben ist, das mehrmals vorkommt, enthält die Teilantwort standardmäßig alle Instanzen dieses Elements. Sie können auch festlegen, dass die Antwort nur Elemente mit einem bestimmten Attributwert oder Elemente mit einer anderen Bedingung mit der Syntax „[ ]“ enthalten soll, wie in den folgenden Beispielen gezeigt. Weitere Informationen finden Sie im Abschnitt Feldbedingungssyntax.

Beispiele	Auswirkung
`entry[link/@rel='edit']`	Gibt alle Feedeinträge zurück, die ein `<link>`-Element mit einem `rel`-Attributwert von `'edit'` enthalten.
`entry/title[text()='Today']`	Gibt alle `<title>`-Elemente zurück, die in Feedeinträgen vorkommen, wenn ihr Inhalt `'Today'` ist.
`entry/author[name='Jo']`	Gibt alle `<author>`-Elemente zurück, die in Feedeinträgen vorkommen, wenn sie ein `<name>`-Unterelement mit dem Inhalt `'Jo'` haben.
`author[name='Jo']`	Gibt das `<author>`-Element im Zieleintrag zurück, wenn es ein `<name>`-Unterelement mit dem Inhalt `'Jo'` enthält.

Fordern Sie nur Teile der ausgewählten Elemente an oder verwenden Sie eine Feldunterauswahl.

Wenn in Ihrer Anfrage bestimmte Elemente angegeben sind, gibt der Dienst die Elemente standardmäßig vollständig zurück. Sie können festlegen, dass die Antwort nur bestimmte Unterelemente in den ausgewählten Elementen enthalten soll. Dazu verwenden Sie die Syntax „( )“ für die untergeordnete Auswahl wie in den folgenden Beispielen dargestellt.

Beispiele	Auswirkung
`entry/author(uri)`	Gibt nur das Unterelement `<uri>` für Autoren in Feedeinträgen zurück.
`entry/author[name='Jo'](uri)`	Gibt nur das `<uri>`-Unterelement `<author>` für Einträge mit dem Autorennamen `'Jo'` zurück.
`entry(link(@rel,@href))`	Gibt nur die Werte der Attribute `rel` und `href` für jedes `<link>`-Element in Feedeinträgen zurück.
`entry(title,link[@rel='edit'])`	Gibt nur `<title>`- und `<link>`-Elemente mit `rel`-Attributen zum Bearbeiten für jeden Feedeintrag zurück.
`entry(title,author(uri)`	Gibt sowohl `<title>`-Elemente als auch Autor-`<uri>`-Elemente für jeden Feedeintrag zurück.

Weitere Informationen zur Syntax von Feldbedingungen

Sie können Feldbedingungen mit Feldern oder untergeordneten Feldern verwenden. Die Bedingung muss als „true“ ausgewertet werden, damit das ausgewählte Feld in die Ergebnisse aufgenommen wird.Wenn keine Feldbedingung vorhanden ist, werden alle Felder des ausgewählten Typs eingeschlossen.

Der Textwert des ausgewählten Feldes wird für Vergleiche verwendet. Wenn es sich bei dem Feld um ein Element handelt, entspricht der Textwert seinem Inhalt. Wenn das Feld ein Attribut ist, ist der Textwert der Attributwert. Wenn das Feld keinen Textwert hat, schlägt der Vergleich fehl und das Feld ist nicht in den Ergebnissen enthalten.

Die folgende Tabelle enthält die XPath-Operatoren, die für Feldbedingungen unterstützt werden, sowie einige Beispiele.

Betreiber	Syntax	Beispiele
Stringvergleich	`=` oder `eq` `!=` oder `ne`	Gibt den gesamten Eintrag zurück, wenn er ein `<link>`-Element mit dem Attribut `rel` enthält, das auf „`self'`“ festgelegt ist: `entry[link/@rel='self']` Gibt den gesamten Eintrag zurück, wenn er ein `<title>`-Element mit Inhalten enthält, die dem String `'unknown'` entsprechen: `entry[title eq 'unknown']` Gibt das gesamte `<title>`-Element zurück, wenn sein Inhalt nicht `'unknown'` ist: `title[text() != 'unknown']`
Logischer Vergleich	`and or not`	Gibt einen beliebigen Link zurück, bei dem das Attribut `rel` auf `'self'` oder `'edit'` festgelegt ist: `link[@rel='self' or @rel='edit']` Gibt einen beliebigen Link zurück, bei dem das Attribut `rel` auf `'self'` und das Attribut `type` auf `'application/atom+xml'` festgelegt ist: `link[@rel='self' and @type='application/atom+xml']` Gibt einen Link zurück, der kein Attribut `rel` mit dem Wert `'self'` hat: `link[not(@rel='self')]` Wie in XPath sieht `not` auch wie ein Funktionsaufruf aus.
Numerischer Vergleich	`=` oder `eq` `!=` oder `ne` `>` oder `gt` `>`= oder `ge` `<` oder `lt` `<=` oder `le`	Gibt ein beliebiges `<gd:rating>`-Element mit einem `value`-Attribut zurück, das in die Ganzzahl 5 umgewandelt werden kann: `gd:rating[@value=5]` Gibt ein beliebiges `<gd:rating>`-Element mit einem `average`-Attribut zurück, das in eine Gleitkommazahl umgewandelt werden kann, die größer als 4,3 ist : `gd:rating[@average gt 4.3]`
Zeitraumvergleich	Verwenden Sie numerische Vergleichsoperatoren wie in den Beispielen gezeigt.	Für den Vergleich von Datum und Uhrzeit können Sie Elemente, Attribute oder Stringliterale in `xs:date` oder `xs:dateTime` umwandeln. Für `xs:dateTime` ist die Standardzeitzone UTC. Es empfiehlt sich jedoch, explizit eine Zeitzone anzugeben. Gibt ein `<yt:recorded>`-Element zurück, das ein Datum seit dem 1. Januar 2005 enthält: `yt:recorded[xs:date(text())>=xs:date('2005-01-01')]` Gibt alle Einträge zurück, die nach der in der UTC-Zeitzone angegebenen Zeit aktualisiert wurden: `entry[xs:dateTime(updated)>xs:dateTime('2008-07-25T08:19:37.549Z')]`
Vorhanden	Verwenden Sie den Namen des Elements oder Attributs, wie in den Beispielen gezeigt.	Gibt alle Einträge zurück, die einen Link mit dem Attribut `rel` enthalten: `entry[link/@rel]` Gibt alle `<gd:rating>`-Elemente mit dem Attribut `value` zurück: `entry/gd:rating[@value]`
Boolesch	`true()false()`	Boolesche Werte können beim Testen nützlich sein, um Feldbedingungen in den Status „wahr“ oder „falsch“ zu erzwingen. Gibt alle `<link>`-Elemente zurück: `link[true()]`

Umgang mit Teilantworten

Nachdem ein Server, der eine Teilantwort unterstützt, eine gültige Anfrage verarbeitet, die den Abfrageparameter fields enthält, sendet er einen HTTP-Statuscode 200 OK zusammen mit den angeforderten Attributen oder Elementen zurück. Wenn der Abfrageparameter fields einen Fehler enthält oder ungültig ist, gibt der Server den HTTP-Statuscode 400 Bad Request zurück.

Das Stammelement der Antwort ist je nach Ziel-URI entweder <feed> oder <entry>. Der Inhalt des Stammelements enthält nur die ausgewählten Felder für diesen Feed oder Eintrag sowie die umschließenden Tags für die übergeordneten Elemente.

Der Wert des fields-Abfrageparameters der Anfrage kann auf zwei Arten wiederholt werden:

Das Stammelement hat ein Attribut gd:fields, das den Wert des in der Anfrage angegebenen Abfrageparameters fields angibt.
Wenn der Ziel-URI ein Feed ist, hat jeder bearbeitbare Eintrag ein gd:fields-Attribut, das den entsprechenden Abschnitt der fields-Auswahl angibt.

Hinweis: Damit die gd:fields-Attributwerte in der Teilantwort erscheinen, müssen Sie sie der Spezifikation des fields-Abfrageparameters hinzufügen. Dazu können Sie @gd:fields verwenden oder den allgemeinen @gd:* verwenden, der auch ETag-Informationen enthält.

Mit der folgenden Beispielabfrage wird vom Server ein Dokument zurückgegeben, das nur Attribute im Namespace gd (sowohl auf Feed- als auch auf Eintragsebene) sowie die Feed-ID, den Titel und den Bearbeitungslink für jeden Feedeintrag enthält:

http://example.com/myFeed?fields=@gd:*,id,entry(@gd:*,title,link[@rel='edit'])

Der Server gibt die folgende Teilantwort zusammen mit einem 200 Successful-HTTP-Statuscode zurück:

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='W/"DEAEQH47eCp7IWA9WxBVGUo."'
    gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])>
  <id>http://example.com/myFeed</id>
  <entry gd:etag='"EksPTg1Bfyp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <title>This year</title>
  </entry>
  <entry gd:etag='"EksPQA1Cdyp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/2/'/>
    <title>Last year</title>
  </entry>
  <entry d:etag='"EksPQAxHeCp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/3/'/>
    <title>Today</title>
  </entry>
</feed>

Wenn die ausgewählten Felder nichts zurückgeben, gibt der Dienst zwar den HTTP-Statuscode 200 Successful zurück, aber die Teilantwort ist ein leerer Feed:

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:gd='http://schemas.google.com/g/2005'
  gd:etag='W/"DEAEQH47eCp7IWA9WxBVGUo."'
  gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])>
</feed>

Teilweise Aktualisierung (experimentell)

Bei Google-Produkten, die eine teilweise Antwort und bearbeitbare Ressourcen unterstützen, können Sie auch eine Teilaktualisierung verwenden. Bei der Teilaktualisierung senden Sie nur die Felder, die Sie aktualisieren möchten, nicht eine geänderte Version der vollständigen Ressourcendarstellung. Dadurch kann die Clientanwendung bei Aktualisierungen sowie bei Verwendung der Teilantwort zum Abrufen von Daten effizienter sein.

Bei einer teilweisen Aktualisierung müssen Sie anstelle von PUT jedoch eine PATCH-Anfrage verwenden. Die Semantik für PATCH ist so leistungsstark, dass Sie mit nur einer Anfrage bestimmte Felder für einen bestimmten Eintrag hinzufügen, ersetzen und löschen können.

Informationen dazu, ob ein teilweises Update für das von Ihnen verwendete Produkt verfügbar ist, finden Sie in der produktspezifischen Dokumentation.

Teilweise Aktualisierungsanfrage senden

Zum Senden einer partiellen Aktualisierungsanfrage senden Sie eine HTTP-PATCH-Anfrage an dieselbe URL, die Sie normalerweise mit PUT zum Aktualisieren der Ressource verwenden würden. Der Text der PATCH-Anfrage ist ein partielles <entry>-Element, das die Felder angibt, die Sie hinzufügen oder ändern möchten. Das Attribut gd:fields des Eintrags gibt die Felder an, die Sie löschen möchten.

Der Server verarbeitet PATCH-Anfragen in einer bestimmten Reihenfolge:

Er entfernt zuerst die durch das Attribut gd:fields angegebenen Felder aus der Ressourcendarstellung.
Die Syntax des Attributs gd:fields entspricht der Syntax für den Abfrageparameter fields, der für die Anforderung einer Teilantwort verwendet wird. Weitere Informationen finden Sie unter Unterstützte Syntax.
Anschließend werden die Daten im Text der Anfrage in die vorhandene Ressourcendarstellung zusammengeführt.
Weitere Informationen dazu, wie die Daten zusammengeführt werden, finden Sie unten im Abschnitt Felder hinzufügen oder aktualisieren.

Hinweis: Da der Text einer PATCH-Anfrage in der Regel nicht mit dem Atom Syndication Format kompatibel ist, verwenden Sie für eine PATCH-Anfrage den Wert application/xml.

Hier ein Beispiel für eine Teilaktualisierungsanfrage:

PATCH /myFeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='description'>
  <title>New title</title>
</entry>

Mit dieser PATCH-Anfrage werden die folgenden Änderungen an der Ressourcendarstellung vorgenommen, die auf dem Server für den Ziel-URI-Eintrag gespeichert sind:

Entfernt das Element <description>.
Aktualisiert das <title>-Element.

Semantik einer Teilaktualisierungsanfrage

In der folgenden Anleitung wird erläutert, wie Sie Ihre PATCH-Anfrage zum Löschen, Hinzufügen oder Aktualisieren bestimmter Felder innerhalb eines Eintrags einrichten. Mit einer einzelnen PATCH-Anfrage können diese Vorgänge beliebig kombiniert werden.

Felder löschen. Verwenden Sie das Attribut gd:fields des Elements <entry>, um alle Felder zu identifizieren, die Sie aus der Ressource löschen möchten. Mit der folgenden Beispielanfrage werden der Titel und die Zusammenfassung eines Eintrags gelöscht. Durch die Anfrage werden jedoch keine anderen Daten für den Eintrag hinzugefügt oder aktualisiert.
```
PATCH /myfeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='title,summary'/>
```
Felder hinzufügen oder aktualisieren. Verwenden Sie den Textteil des <entry>-Elements, um die Daten anzugeben, die Sie für eine Ressource hinzufügen oder aktualisieren möchten. Nachdem Felder gelöscht wurden, werden diese Felder gemäß den folgenden Regeln mit den vorhandenen Daten für die Ressource zusammengeführt:
- Felder, die noch nicht vorhanden sind, werden hinzugefügt. Wenn für die Ressourcendaten noch kein Wert für ein Feld angegeben ist, wird das Feld den vorhandenen Daten hinzugefügt. Wenn ein Eintrag beispielsweise keinen Titel hat und Ihre PATCH-Anfrage ein <title>-Element enthält, wird der neue Titel dem Eintrag hinzugefügt.
- Bereits vorhandene Felder werden ersetzt oder angehängt. Das Verhalten beim Zusammenführen von Feldern, die bereits in den Ressourcendaten angegeben sind, hängt von den Merkmalen des jeweiligen Felds ab:
  - Nicht wiederkehrende Felder werden ersetzt. Wenn in den Ressourcendaten bereits ein Wert für ein nicht wiederkehrendes Element angegeben ist, ersetzt der in der PATCH-Anfrage angegebene Wert den vorhandenen Wert für dieses Element. Im folgenden Beispiel wird der vorhandene Titel durch den neuen ersetzt.
```
PATCH /myFeed/1/1/
Content-Type: application/xml

  <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'>
  <title>New Title</title>
</entry>
```
    Ein komplexeres Beispiel finden Sie unten. In diesem Beispiel wird davon ausgegangen, dass der Eintrag nur einen Autor haben kann und dass die Zielressource bereits Werte für den Namen und die E-Mail-Adresse des Autors hat. Obwohl das <author>-Element zwei untergeordnete Felder hat, ist nur das <name>-Element in den bereitgestellten Daten vorhanden. Daher wird nur der Wert dieses Felds überschrieben. Der Wert des <email>-Elements, der in den bereitgestellten Daten fehlt, bleibt unverändert.
```
PATCH /myfeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'>
  <author>
    <name>New Name</name>
  </author>
</entry>
```
  - Wiederkehrende Felder werden angehängt. Wenn in den Ressourcendaten bereits ein Wert für ein wiederkehrendes Element angegeben ist, wird das neue Element dem vorhandenen Satz von Werten hinzugefügt.
    
    Es kann vorkommen, dass Sie etwas anderes tun möchten, als eine neue Instanz eines wiederkehrenden Elements hinzuzufügen. Sie haben z. B. folgende Möglichkeiten:
    - Ersetzen Sie eine ganze Liste wiederkehrender Elemente. Sie können alle sich wiederholenden Felder mit dem Attribut gd:fields (z. B. gd:fields='ns:accessControl') löschen und einen vollständigen Satz der Ersatzfelder angeben. Da alle vorhandenen Elemente zuerst gelöscht werden, stehen die von Ihnen angegebenen Felder nicht in Konflikt mit vorhandenen Werten, wenn sie angehängt werden.
    - Ersetzen Sie einen Wert in einer Gruppe von vorhandenen Werten für ein wiederkehrendes Element. In diesem Fall entfernen Sie das einzelne Element, indem Sie den Wert für gd:fields so eng definieren, dass andere Werte, die Sie beibehalten möchten, nicht gelöscht werden. Wenn Sie beispielsweise nur eine Zugriffssteuerung mit einem action von embed entfernen möchten, können Sie gd:fields='ns:accessControl[@action="embed"]' verwenden. Geben Sie dann im Textkörper des Elements <entry> das einzelne Feld an, durch das Sie es ersetzen möchten:
```
PATCH /myfeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='ns:accessControl[@action="embed"]>
  <ns:accessControl action="embed" permission="allowed" />
</entry>
```

Reaktion auf eine Teilaktualisierung

Nach der Verarbeitung einer gültigen Anfrage für eine Teilaktualisierung gibt die API den HTTP-Antwortcode 200 OK zurück. Standardmäßig ist der Text der Antwort der vollständige Eintrag, den Sie aktualisiert haben. Der Server aktualisiert ETag-Werte, wenn er eine PATCH-Anfrage verarbeitet, genau wie bei PUT.

Wenn eine PATCH-Anfrage zu einem neuen Ressourcenstatus führt, der syntaktisch oder semantisch ungültig ist, gibt der Server den HTTP-Statuscode HTTP 400 Bad Request oder 422 Unprocessable Entity zurück und der Ressourcenstatus bleibt unverändert. Wenn Sie beispielsweise versuchen, ein Pflichtfeld zu löschen, und keinen Ersatz bereitstellen, gibt der Server einen Fehler zurück.

Hinweis: Es ist wichtig zu verstehen, wie verschiedene Felder miteinander in Beziehung stehen. Es ist möglich, eine Ressource in einen inkonsistenten Zustand zu versetzen, indem nur ein Teil der gegenseitig voneinander abhängigen Werte aktualisiert wird. Es ist beispielsweise möglich, eine Startzeit auf einen späteren Wert als eine Endzeit zu aktualisieren. Obwohl die API einen Fehlercode zurückgeben sollte, empfehlen wir Ihnen, diese Bedingungen vollständig zu testen, um Konsistenz zu gewährleisten.

Alternative Schreibweise, wenn PATCH nicht unterstützt wird

Wenn Ihre Firewall PATCH nicht unterstützt, führen Sie eine HTTP-POST-Anfrage aus und setzen Sie den Überschreibungsheader auf PATCH, wie unten dargestellt:

POST /myfeed/1/1/ X-HTTP-Method-Override: PATCH Content-Type: application/xml ...

Teilantwort mit Teilaktualisierung verwenden

Sie können eine Teilantwort als Grundlage für eine nachfolgende Teilaktualisierungsanfrage verwenden. Geben Sie in diesem Fall einen fields-Abfrageparameter an, der Bearbeitungslinks enthält, sowie @gd:*. Dadurch wird sichergestellt, dass die Teilantwort Informationen wie das ETag- und das gd:fields-Attribut enthält, die für nachfolgende Anfragen wichtig sind.

In diesem Beispiel wird eine Teilantwort zurückgegeben, die Sie als Grundlage für eine zukünftige Teilaktualisierung verwenden können:

http://example.com/myFeed/1/1/?fields=@gd:*,link[@rel='edit'](@href),gd:who

Der Server antwortet:

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:etag='"E0UKRAREeCp7IWA6WhJT"'
    gd:fields="@gd;*,link[@rel='edit'](@href),gd:who">
  <link href='http://example.com/myFeed/1/1/'/>
  <gd:who email='liz@gmail.com'/>
  <gd:who email='jo@gmail.com'/>
  <gd:who email='jane@gmail.com'/>
</entry>

Angenommen, Sie möchten den Nutzer mit der E-Mail-Adresse 'jane@gmail.com' entfernen, einen Nutzer mit der E-Mail-Adresse 'will@gmail.com' hinzufügen und die E-Mail-Adresse für den aktuell als 'jo@gmail.com' aufgeführten Nutzer in 'josy@gmail.com' ändern.

Sie können diese Änderungen einfach vornehmen, indem Sie mit den Ergebnissen der vorherigen Antwort beginnen, nur die anderen Felder ändern und den geänderten Teileintrag als Text der PATCH-Anfrage einreichen. In diesem Beispiel sind folgende Änderungen erforderlich:

Löschen Sie <gd:who email='jane'/> aus der Liste der bereitgestellten Elemente.
Fügen Sie <gd:who email='will@gmail.com'/> der Liste der bereitgestellten Elemente hinzu.
Ersetzen Sie <gd:who email='jo@gmail.com'/> durch <gd:who email='josy@gmail.com'/>.

Die PATCH-Anfrage, die auf der abhängigen Teilantwort basiert, ist unten zu sehen:

PATCH /myFeed/1/1/
Content-Type: application/xml

<entry gd:fields="@gd:*,link[@rel='edit'](@href),gd:who"
    gd:etag="FE8LQQJJeSp7IWA6WhVa">
  <link href='http://example.com/myFeed/1/1'/>
  <gd:who email='liz@gmail.com'/>
  <gd:who email='josy@gmail.com'/>
  <gd:who email='will@gmail.com'/>
</entry>

Hinweis: Bei diesem Ansatz werden die Attribute gd:fields und gd:etag (falls unterstützt) in der Teilantwort für den Eintrag verwendet. Der Text des Teileintrags muss alle Felder und Attribute beibehalten, die in der Teilantwort vorhanden waren – mit Ausnahme derjenigen, die Sie explizit entfernen möchten. Sie können alle vorhandenen Felder im Textkörper mit neuen Werten aktualisieren und neue Felder hinzufügen, die Sie hinzufügen möchten.

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 für einen Google-Dienst, sollte ein Google-spezifisches Authentifizierungssystem namens Account Authentication Proxy for Web-Application 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 Data API-Anfragen (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 Authentifizierungsübersicht der Google Data APIs 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 mit Daten-APIs, die Leistung kann jedoch im Vergleich zu Clients, die diese Methoden unterstützen, beeinträchtigt werden. 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:

Atom- und RSS-Vergleich im Vergleich
Übersicht über Atom von IBM
Dublin Core-Erweiterungen zu RSS
HTTP 1.1-Methodendefinitionen: Spezifikation für GET, POST, PUT und DELETE
HTTP 1.1-Statuscodes
REST-Protokoll erstellen
Webdienst für REST erstellen
Technische Einführung in XML
XML-Namespaces nach Beispiel
ETag-Abschnitt der HTTP-Spezifikation

Nach oben