Protokollgrundlagen

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 werden die Grundlagen des Google-Datenprotokolls beschrieben, das von vielen Google APIs verwendet wird, einschließlich Beispielen für Abfragen, wie Ergebnisse aussehen usw.

Weitere Informationen zum Google-Datenprotokoll finden Sie auf der Übersichtsseite des Entwicklerhandbuchs und in der Protokollreferenz.

Zielgruppe

Dieses Dokument ist für jeden gedacht, der die allgemeinen Vorstellungen des von den Google Data APIs verwendeten XML-Formats und -Protokolls verstehen möchte.

Auch wenn Sie nur Code schreiben möchten, der die sprachspezifischen Clientbibliotheken verwendet, sollten Sie dieses Dokument lesen, um zu verstehen, was unter der Abstraktionsebene „Clientbibliothek“ geschieht.

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.

Dieses Dokument benötigt keine bestimmte Programmiersprache. Ihr Client kann mit dem Server über eine beliebige Programmiersprache interagieren, mit der Sie HTTP-Anfragen senden und XML-basierte Antworten parsen können.

Wenn Sie die Beispiele in diesem Dokument ausprobieren möchten, ohne Code schreiben zu müssen, könnten die Befehlszeilendienstprogramme cURL oder Wget nützlich sein. Weitere Informationen zur Interaktion mit Diensten, die das Google-Datenprotokoll verwenden, finden Sie auf den zugehörigen Seiten zu den Dienstprogrammen oder im Dokument cURL verwenden.

Beispiele

Die folgenden Beispiele zeigen HTTP-Anfragen, die Sie mit dem Google Data Protocol API-Protokoll direkt an einen generischen Dienst senden können, und die daraus resultierenden Ergebnisse. Beispiele zum Senden von Anfragen mit verschiedenen Programmiersprachen finden Sie in den sprachspezifischen Beispielen und Clientbibliotheken. Informationen zum Verwenden des Google-Datenprotokolls mit bestimmten Google-Diensten finden Sie in der dienstspezifischen Dokumentation.

Feed oder andere Ressource anfordern

Angenommen, es gibt einen Feed namens /myFeed und es wird angenommen, dass er derzeit keine Einträge enthält. Senden Sie die folgende HTTP-Anfrage an den Server, um sie aufzurufen:

GET /myFeed

Der Server antwortet:

200 OK

<?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."'>
  <title>Foo</title>
  <updated>2006-01-23T16:25:00-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
</feed>

Der Feed enthält zwar keine Einträge, aber Metadaten wie einen Titel und den Namen eines Autors. Es enthält außerdem eine Versionskennung in Form eines HTTP-ETags.

Neuen Eintrag einfügen

Zum Erstellen eines neuen Eintrags senden Sie eine POST-Anfrage und geben die XML-Darstellung des neuen Eintrags an:

POST /myFeed

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my entry</content>
</entry>

Beachten Sie, dass Sie keine standardmäßigen Atom-Elemente vom Typ <id>, <link> oder <updated> angeben. Diese werden vom Server als Antwort auf Ihre POST-Anfrage erstellt. Beachten Sie außerdem, dass der Autor eines Feeds nicht dieselbe Person sein muss wie der Autor eines Eintrags.

Der Server antwortet:

201 CREATED

<?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='"CUUEQX47eCp7ImA9WxRVEkQ."'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/1/'/>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my entry</content>
</entry>

String suchen

Wenn Sie eine Volltextsuche für einen bestimmten String ausführen möchten, senden Sie bei Verwendung eines Dienstes, der Volltextsuchen unterstützt, eine GET-Anfrage mit dem Parameter q. Weitere Informationen zu Abfrageparametern finden Sie im Dokument zum Protokollreferenz unter Abfrageanfragen.

GET /myFeed?q=This

Der Server antwortet mit einem Feed, der alle Einträge enthält, die mit dem Suchstring This übereinstimmen. In diesem Fall gibt es nur eine.

200 OK

<?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/"S0wCTlpIIip7ImA0X0QI"'>
  <title>Foo</title>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
  <entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
    <id>http://www.example.com/id/1</id>
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <updated>2006-01-23T16:26:03-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
    <content type='text'>This is my entry</content>
  </entry>
</feed>

Eintrag aktualisieren

So aktualisieren Sie einen vorhandenen Eintrag:

  1. Rufen Sie den Eintrag ab, den Sie aktualisieren möchten.
  2. Ändern Sie sie wie gewünscht.
  3. Senden Sie eine PUT-Anfrage mit dem aktualisierten Eintrag im Nachrichtentext an den Bearbeitungs-URI des Eintrags. Der Bearbeitungs-URI wird im vorherigen Beispiel als href-Attribut des <link rel='edit'>-Elements angezeigt.

Außerdem müssen Sie das ETag des ursprünglichen Eintrags angeben, damit die Änderungen durch andere nicht überschrieben werden.

Im folgenden Beispiel ändern wir den Text des Eintrags von seinem alten Wert („This is my entry“) in einen neuen Wert („This is my first entry.“):

PUT /myFeed/1/1/

<?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='"CUUEQX47eCp7ImA9WxRVEkQ."'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/'/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my first entry.</content>
</entry>

Der Server antwortet:

200 OK

<?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='"FkkOQgZGeip7ImA6WhVR"'>
  <id>http://www.example.com/id/1</id>
  <link rel='edit' href='http://example.com/myFeed/1/'/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
    <name>Elizabeth Bennet</name>
    <email>liz@gmail.com</email>
  </author>
  <title type='text'>Entry 1</title>
  <content type='text'>This is my first entry.</content>
</entry>

Das ETag wurde geändert. Weitere Informationen zu Ressourcenversionen finden Sie im Abschnitt Ressourcenversionsverwaltung (ETags) des Protokollreferenzdokuments.

Wenn Sie den neuen Eintrag im Kontext sehen möchten, fordern Sie die gesamte Ressource noch einmal an:

GET /myFeed

Der Server antwortet:

200 OK

<?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/"D08FQn8-eil7ImA9WxZbFEw."'>
  <title>Foo</title>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
  <entry gd:etag='"FkkOQgZGeip7ImA6WhVR"'>
    <id>http://www.example.com/id/1</id>
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <updated>2006-01-23T16:28:05-08:00</updated>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
    <content type='text'>This is my first entry.</content>
  </entry>
</feed>

Hinweis: Wenn deine Firewall PUT nicht zulässt, gib den HTTP-POST an und lege den Methodenüberschreibungsheader so fest:

X-HTTP-Method-Override: PUT

Eintrag löschen

Senden Sie zum Löschen eines vorhandenen Eintrags eine DELETE-Anfrage mit dem Bearbeitungs-URI des Eintrags, wie im vorherigen Beispiel vom Server angegeben.

Wenn Ihre Firewall DELETE nicht unterstützt, führen Sie ein HTTP-POST aus und legen Sie den Header für die Methodenüberschreibung so fest:

X-HTTP-Method-Override: DELETE

Wenn Sie einen Eintrag löschen, können Sie auswählen, ob er das bedingte Löschen durchführen soll (nur löschen, wenn der Eintrag sich seit dem letzten Abruf nicht geändert hat) oder einen bedingungsfreien Löschvorgang ausführt. Weitere Informationen finden Sie im Abschnitt Ressourcenversionsverwaltung (ETags) des Protokollreferenzdokuments. Legen Sie für einen unbedingten Löschvorgang den folgenden HTTP-Header fest:

If-Match: *

Im folgenden Beispiel wird ein Eintrag gelöscht (sofern die Header entsprechend festgelegt sind):

DELETE /myFeed/1/

Der Server antwortet:

200 OK

Führen Sie eine weitere GET aus, um zu prüfen, ob der Feed jetzt keine Einträge mehr enthält:

GET /myFeed

Der Server antwortet mit einem Feed, der nur Metadaten enthält:

200 OK

<?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/"D0cERnk-eip7ImA9WBBXGEg."'>
  <title>Foo</title>
  <updated>2006-01-23T16:30:11-08:00</updated>
  <id>http://www.example.com/myFeed</id>
  <author>
    <name>Jo March</name>
  </author>
  <link href='/myFeed' rel='self'/>
</feed>

Wenn der Löschvorgang fehlschlägt, gibt der Server einen Fehlercode zurück. Weitere Informationen finden Sie unter HTTP-Statuscodes im Protokollreferenzdokument.

Teilweise Feeds oder Einträge anfordern (experimentell)

Im Gegensatz zum einfachen Beispielfeed, der in diesem Dokument gezeigt wird, können Feeds in der Praxis recht komplex sein. Bei einigen APIs können Sie nur die relevanten Elemente oder Attribute anfordern, anstatt die vollständige Ressourcendarstellung darzustellen. Wenn Sie das Abrufen und Parsen nicht benötigter Daten vermeiden, können Sie die Effizienz Ihrer Clientanwendung erheblich verbessern.

Wenn Sie eine Teilantwort anfordern möchten, verwenden Sie den Abfrageparameter fields, um anzugeben, welche Elemente oder Attribute zurückgegeben werden sollen. Weitere Informationen finden Sie im Protokollreferenzdokument unter Teilantwort.

Im folgenden Beispiel werden nur die Feed-ID, der Autor und der Titel für jeden Feedeintrag angefordert.

GET /myFeed?fields=id,entry(author)

Der Server antwortet:

200 OK

<?xml version='1.0' encoding='utf-8'?>
<feed xmlns='http://www.w3.org/2005/Atom'
  xmlns:gd='http://schemas.google.com/g/2005'>
  <id>http://www.example.com/myFeed</id>
  <entry>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 1</title>
  </entry>
  <entry>
    <author>
      <name>Elizabeth Bennet</name>
      <email>liz@gmail.com</email>
    </author>
    <title type='text'>Entry 2</title>
  </entry>
</feed>

Sie können den Parameter fields mit jeder Art von Anfrage verwenden, die Daten zurückgibt. Zusätzlich zu GET umfasst dies POST und PUT (sowie PATCH, die für Teilaktualisierungsanfragen verwendet wird).

Hinweis: Der Abfrageparameter fields steuert nur die Daten, die als Antwort auf eine Anfrage zurückgesendet werden. Er wirkt sich nicht auf die Daten aus, die Sie im Text einer PUT-, POST- oder PATCH-Anfrage angeben müssen.

Unten sehen Sie Beispiele für POST und PUT.

  • Auch wenn Sie eine POST-Anfrage für eine Teilantwort senden, müssen Sie dieselben Daten angeben, wie unter Neuen Eintrag einfügen beschrieben. Im folgenden Beispiel wird eine Teilantwort angefordert, die nur den Titel des neu erstellten Eintrags enthält: 
    POST /myFeed?fields=title
      
...data...

    Der Server antwortet:

    200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
  <title type='text'>Entry 1</title>
</entry>
  • Auch wenn Sie eine PUT-Anfrage für eine Teilantwort senden, müssen Sie eine modifizierte Version der vollständigen Ressourcendarstellung angeben, wie unter Eintrag aktualisieren beschrieben. Im folgenden Beispiel wird eine Teilantwort angefordert, die nur den neuen ETag-Wert des geänderten Eintrags enthält: 
    PUT /myFeed/1/1?fields=@gd:etag
  
...data...

    Der Server antwortet:

    200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'
  gd:etag='"FkkOQgZGeip7ImA6WhVR"'/>

Bestimmte Felder aktualisieren (experimentell)

Wenn die von Ihnen verwendete API eine Teilantwort unterstützt und bearbeitbare Felder hat, können Sie auch vermeiden, dass beim Ändern eines Eintrags unnötige Daten gesendet werden. Bei der Teilaktualisierung können Sie nur Daten für die Felder senden, die Sie ändern möchten.

Wenn Sie eine teilweise Aktualisierung verwenden möchten, senden Sie eine PATCH-Anfrage an denselben Bearbeitungs-URI, den Sie mit PUT verwenden. Die Daten, die Sie mit PATCH senden, müssen bestimmten Konventionen entsprechen. Die Semantik ist jedoch flexibel genug, um Daten in der Zielressource mit nur einer Anfrage zu ersetzen, hinzuzufügen oder sogar zu löschen.

Hinweis:Wie bei PUT müssen Sie auch hier das ETag des Eintrags angeben, damit Änderungen nicht überschrieben werden.

Weitere Informationen zu PATCH und der Semantik finden Sie unter Teilaktualisierung im Protokollreferenzdokument.

Dieses Beispiel zeigt eine teilweise Aktualisierungsanfrage, die den Titel des Eintrags ändert:

PATCH /myFeed/1/1/

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

Wenn der Server eine PATCH-Anfrage empfängt, entfernt er zuerst alle im gd:fields-Attribut des Eintrags angegebenen Felder (falls vorhanden) und führt dann alle im Anfragetext enthaltenen Daten mit der Zielressource zusammen. In diesem Beispiel wird das Titelelement zuerst aus der Zielressource entfernt und dann der neue Titelwert zusammengeführt. Diese Anfrage ersetzt im Prinzip den alten Titel durch den neuen.

Beachten Sie jedoch, dass die Semantik von PATCH die Teildarstellung mit der vorhandenen Ressource verbindet. Sie müssen nicht immer ein Feld entfernen, um seinen Wert zu aktualisieren.

  • Wenn das Feld nur einmal im Zieleintrag vorhanden ist, überschreibt das Feld beim Zusammenführen das entsprechende Feld im Zieleintrag.
  • Wenn das Feld im Zieleintrag mehrmals vorhanden sein kann, wird das Teilfeld beim Zusammenführen in den Zieleintrag eingefügt.

Der Unterschied zwischen sich wiederholenden und sich nicht wiederholenden Feldern ist im nächsten Beispiel zu sehen. Dabei werden einem Eintrag ein neuer Titel und ein neuer Autor hinzugefügt, ohne dass zuvor ein gd:fields-Attribut verwendet werden muss.

PATCH /myFeed/1/1/

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:edtag="EksPTg1Bfyp7IWA6WhJT">
  <title>A new title</title>
  <author>
    <name>Fitzwilliam Darcy</name>
    <email>darcy@gmail.com</email>
  </author>
</entry>

Da die teilweise Eingabedarstellung kein gd:fields-Attribut hat, werden keine Felder entfernt. Die neuen Werte für die Elemente <title> und <author> werden jedoch mit der Zielressource zusammengeführt:

  • Da bei Atom nur ein Titel pro Eintrag zulässig ist, überschreibt der neue Titel den vorhandenen Wert. 
  • Da Atom mehrere Autoren pro Eintrag zulässt, wird der neue Autor an die Liste der Autorenelemente angehängt, die sich bereits in der Zielressource befinden.

    Hinweis: Nicht alle APIs entsprechen dem Atom-Standard. Beispielsweise ist bei einigen APIs nur ein einziges <author>-Element pro Eintrag zulässig, bei anderen wird der Eingabeautor von der Feedebene übernommen, sodass das Feld schreibgeschützt ist.

Nachdem der Server eine gültige PATCH-Anfrage verarbeitet hat, gibt er den HTTP-Statuscode 200 zusammen mit einer Kopie der vollständigen Darstellung des aktualisierten Eintrags zurück.

Wenn der Server nur bestimmte Elemente oder Attribute zurückgeben soll, können Sie den Abfrageparameter fields mit PATCH verwenden, um eine Teilantwort anzufordern.

Weitere Informationen

Die folgenden Dokumente von Drittanbietern sind möglicherweise hilfreich:

Nach oben