Google Data APIs-Protokoll – Grundlagen

In diesem Dokument werden die Grundlagen des Protokolls beschrieben, das von den Google Data APIs verwendet wird, darunter Beispiele für Abfragen und Ergebnisse.

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

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.

Beispiele

Die folgenden Beispiele zeigen nur die Anfragen an Data API-Protokolle, die Sie möglicherweise an einen generischen Dienst senden, und die daraus resultierenden Ergebnisse. Beispiele zum Senden von Anfragen mit verschiedenen Programmiersprachen finden Sie in den sprachspezifischen Beispielen und Clientbibliotheken. Informationen zur Verwendung der Google Data APIs 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 Anfrage an den Server, um sie aufzurufen:

GET /myFeed

Der Server antwortet:

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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.

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"?>
<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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <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 allen Einträgen, die dem Suchstring This entsprechen. In diesem Fall gibt es nur eine.

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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>
    <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>
</feed>

Eintrag aktualisieren

Verwenden Sie zum Aktualisieren eines vorhandenen Eintrags PUT mit dem Bearbeitungs-URI des Eintrags (wie im vorherigen Beispiel im <link rel="edit">-Element vom Server angegeben).

Wenn Ihre Firewall PUT 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: PUT

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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/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"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>http://www.example.com/id/1</id>
  <link rel="edit" href="http://example.com/myFeed/1/2/"/>
  <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 Bearbeitungs-URI hat sich geändert. Er endet jetzt mit „/2/“ statt „/1/“. Die letzte Zahl im Bearbeitungs-URI ist eine Versionsnummer. Weitere Informationen zu Versionen finden Sie im Abschnitt Optimistische Gleichzeitigkeit 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"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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>
    <id>http://www.example.com/id/1</id>
    <link rel="edit" href="http://example.com/myFeed/1/2/"/>
    <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>

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

Im folgenden Beispiel wird ein Eintrag gelöscht:

DELETE /myFeed/1/2/

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:

200 OK

<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <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.

Weitere Informationen

Die folgenden Dokumente von Drittanbietern sind möglicherweise hilfreich:

Nach oben