RkBlog

Hardware, programming and astronomy tutorials and reviews.

Wprowadzenie do GData

Co to jest i do czego służy protokół i API GData (Google Data).

GData to protokół i API służące do pobierania, szukania, edycji, dodawania i usuwania danych. GData wykorzystuje żądaniach HTTP: GET, POST, PUT i DELETE, a przesyłane dane zapisane są w formacie kanałów Atom. GData obsługuje też uwierzytelnianie. Protokół ten został opracowany przez Google w celu ułatwienia integracji posiadanych aplikacji między sobą, a także w celu udostępnienia API osobom trzecim, umożliwiając tym samym integrowanie innych aplikacji z usługami Google jak kalendarz czy dokumenty. Na stronach Google dostępna jest pełna specyfikacja protokołu, API dla poszczególnych usług, a także biblioteki dla różnych języków programistycznych ułatwiające korzystanie z API.

Załóżmy że na naszej stronie pod odnośnikiem /kanał mamy "kanał" Atom obsługujący protokół GData. By pobrać zawartość kanału wystarczy wysłać żądanie GET:
GET /kanał
Powodzenie operacji rozpoznamy po statusie 200 odpowiedzi serwera:
200 OK
Zwrócone dane (kanał nie zawiera wpisów) będą postaci:
<?xml version="1.0"?>
<feed xmlns="http://www.w3.org/2005/Atom">
  <title>Mój Kanał</title>
  <updated>2006-01-23T16:25:00-08:00</updated>
  <id>http://www.strona.pl/kanał</id>
  <author>
    <name>Imię Nazwisko</name>
  </author>
  <link href="/kanał" rel="self"/>
</feed>

By dodać wpis wystarczy wysłać dane w formacie GData za pomocą żądania POST
POST /kanał
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <author>
    <name>Jan Kowalski</name> 
    <email>jan@kowalski.pl</email> 
  </author>
  <title type="text">Tytuł wpisu 1</title>
  <content type="text">To jest mój wpis</content>
</entry>
Nie podajemy elementów Atom takich jak "id", "link" czy "updated" - serwer je tworzy w odpowiedzi na przesłane żądanie. W przypadku udanej operacji serwer zwróci odpowiedź o statusie 201:
201 CREATED
Oraz "fragment" kanału zawierający dodane dane:
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>1</id>
  <link rel="edit" href="http://www.strona.pl/kanał/1/1/"/>
  <updated>2006-01-23T16:26:03-08:00</updated>
  <author>
    <name>Jan Kowalski</name> 
    <email>jan@kowalski.pl</email> 
  </author>
  <title type="text">Tytuł wpisu 1</title>
  <content type="text">To jest mój wpis</content>
</entry>

W celu wyszukania wpisów zawierających podaną frazę należy wysłać żądanie GET z parametrem q zawierającym szukaną frazę:
GET /kanał?q=wpis
Serwer zwróci odpowiedź ze statusem 200 w przypadku powodzenia:
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.strona.pl/kanał</id>
  <author>
    <name>Imię Nazwisko</name>
  </author>
  <link href="/kanał" rel="self"/>
  <entry>
    <id>1</id>
    <link rel="edit" href="http://www.strona.pl/kanał/1/1/"/>
    <updated>2006-01-23T16:26:03-08:00</updated>
    <author>
      <name>Jan Kowalski</name> 
      <email>jan@kowalski.pl</email> 
    </author>
    <title type="text">Tytuł wpisu 1</title>
    <content type="text">To jest mój wpis</content>
  </entry>
</feed>

By zaktualizować istniejący wpis należy wysłać żądanie PUT z odnośnikiem edycji podanym dla danego wpisu w kanale atom (link rel="edit"). Jeżeli firewall blokuje żądania PUT można wysłać żądanie POST z modyfikacją nagłówka:
X-HTTP-Method-Override: PUT
Przy dodawaniu wpisu (co robiliśmy wcześniej) serwer generuje link edycji dla nowego wpisu (w przykładzie http://www.strona.pl/kanał/1/1/). Wysyłamy żądanie:
PUT /kanał/1/1/
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>1</id>
  <link rel="edit" href="http://www.strona.pl/kanał/1/1/"/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
      <name>Jan Kowalski</name> 
      <email>jan@kowalski.pl</email> 
    </author>
    <title type="text">Nowy Tytuł</title>
    <content type="text">To nowy wpis</content>
</entry>

Serwer odpowie:
<?xml version="1.0"?>
<entry xmlns="http://www.w3.org/2005/Atom">
  <id>1</id>
  <link rel="edit" href="http://www.strona.pl/kanał/1/2/"/>
  <updated>2006-01-23T16:28:05-08:00</updated>
  <author>
      <name>Jan Kowalski</name> 
      <email>jan@kowalski.pl</email> 
    </author>
    <title type="text">Nowy Tytuł</title>
    <content type="text">To nowy wpis</content>
</entry>
Zwróć uwagę że zmianie uległ link edycji (/2/ zamiast /1/). Ostatnia z liczb pełni rolę numeru wersji wpisu.

By usunąć wpis wysyłamy żądanie DELETE, lub w przypadku blokady na firewallu wysyłamy żądanie POST zawierające w nagłówku:
X-HTTP-Method-Override: DELETE
By skasować nasz wpis wystarczy wysłać żądanie:
DELETE /kanał/1/2/
W przypadku sukcesu serwer odpowie statusem 200
200 OK
RkBlog

11 July 2008;

Comment article