Podstawowe informacje o protokole Google Data API

W tym dokumencie opisano podstawowe protokoły używane przez interfejsy API danych Google, w tym przykłady wyglądu zapytania, wygląd wyników itd.

Więcej informacji o interfejsach Google Data API znajdziesz w przewodniku Google dla programistów danych oraz w przewodniku.

Odbiorcy

Ten dokument jest przeznaczony dla wszystkich, którzy chcą zrozumieć ogólną koncepcję formatu XML oraz protokół wykorzystywany przez interfejsy API danych Google.

Jeśli chcesz napisać kod, który korzysta z bibliotek klienta danego języka, przeczytaj ten dokument, aby dowiedzieć się, co się dzieje pod warstwą abstrakcji biblioteki.

W tym dokumencie założono, że znasz podstawy formatu XML, przestrzeni nazw, kanałów dystrybucji oraz żądań GET, POST, PUT i DELETE w protokole HTTP, a także koncepcję „zasobu” HTTP. Więcej informacji na ten temat znajdziesz w sekcji Materiały dodatkowe tego dokumentu.

Ten dokument nie wymaga konkretnego języka programowania. Klient może wchodzić w interakcję z serwerem za pomocą dowolnego języka programowania, który umożliwia wysyłanie żądań HTTP i analizowanie odpowiedzi XML.

Przykłady

Poniższe przykłady pokazują proste żądania protokołu Data API, które możesz wysłać do usługi ogólnej, oraz wyniki, jakie możesz uzyskać. Przykłady wysyłania żądań w różnych językach programowania znajdziesz w przykładach i bibliotekach klienta danego języka. Informacje na temat używania interfejsów API danych Google w przypadku określonych usług Google znajdziesz w dokumentacji tych usług.

Przesyłanie prośby o kanał lub inny zasób

Załóżmy, że istnieje kanał o nazwie /myFeed i zakładamy, że obecnie nie zawiera on żadnych wpisów. Aby ją wyświetlić, wyślij do serwera poniższe żądanie:

GET /myFeed

Serwer odpowiada:

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>

Pamiętaj, że mimo że kanał nie zawiera żadnych wpisów, zawiera metadane, takie jak tytuł i nazwisko autora.

Wstawianie nowego wpisu

Aby utworzyć nowy wpis, wyślij żądanie POST i podaj kod XML reprezentujący nowy wpis:

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>

Nie dostarczasz standardowych elementów Atom <id>, <link> ani <updated>. Serwer tworzy je w odpowiedzi na żądanie POST. Pamiętaj, że autor kanału nie musi być tą samą osobą, co autor wpisu.

Serwer odpowiada:

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>

Wyszukuję ciąg znaków

Aby przeprowadzić wyszukiwanie pełnotekstowe w przypadku określonego ciągu znaków, podczas korzystania z usługi obsługującej wyszukiwanie pełnotekstowe wyślij żądanie GET z parametrem q. Więcej informacji o parametrach zapytania znajdziesz w sekcji Żądania zapytań w dokumentacji referencyjnej protokołu.

GET /myFeed?q=This

Serwer odpowiada wszystkimi wpisami, które pasują do ciągu wyszukiwania This. (W tym przypadku jest tylko jedna opcja).

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>

Aktualizowanie wpisu

Aby zaktualizować istniejący wpis, użyj PUT z identyfikatorem URI edycji (takim jak w poprzednim przykładzie w elemencie <link rel="edit">).

Jeśli zapora sieciowa nie zezwala na PUT, wykonaj HTTP HTTP POST i ustaw nagłówek zastąpienia metody w ten sposób:

X-HTTP-Method-Override: PUT

W poniższym przykładzie zmieniamy tekst wpisu ze starej wartości („To jest mój wpis”) na nową wartość („To jest mój pierwszy wpis”).):

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>

Serwer odpowiada:

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>

Pamiętaj, że identyfikator URI zmiany uległ zmianie i teraz kończy się na „/2/”, a nie „/1/”. Ostatnim numerem w identyfikatorze URI edycji jest numer wersji. Więcej informacji o wersjach znajdziesz w sekcji Równoczesna optymalizacja w dokumencie referencyjnym protokołu.

Aby zobaczyć nowy wpis w kontekście, poproś ponownie o cały zasób:

GET /myFeed

Serwer odpowiada:

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>

Usuwanie wpisu

Aby usunąć istniejący wpis, wyślij żądanie DELETE, używając jego identyfikatora URI edycji (jak w poprzednim przykładzie z serwera).

Jeśli zapora sieciowa nie zezwala na DELETE, wykonaj HTTP HTTP POST i ustaw nagłówek zastąpienia metody w ten sposób:

 X-HTTP-Method-Override: DELETE

Ten przykład usuwa wpis:

DELETE /myFeed/1/2/

Serwer odpowiada:

200 OK

Wykonaj kolejne GET, aby sprawdzić, czy kanał nie zawiera już żadnych wpisów:

GET /myFeed

Serwer odpowiada:

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>

Jeśli usunięcie nie powiedzie się, serwer zwróci kod błędu. Więcej informacji znajdziesz w sekcji Kody stanu HTTP w dokumentacji referencyjnej protokołu.

Dodatkowe materiały

Oto dokumenty innych firm:

Powrót do góry