Podstawowe informacje o protokole

Ostrzeżenie: ta strona dotyczy starszych interfejsów API Google – interfejsów API danych Google – dotyczy tylko interfejsów API wymienionych w katalogu interfejsów API danych Google, z których wiele zostało zastąpionych nowszych. Informacje na temat konkretnego nowego interfejsu API można znaleźć w dokumentacji nowego interfejsu API. Informacje o autoryzowaniu żądań za pomocą nowszego interfejsu API znajdziesz w artykule Uwierzytelnianie i autoryzacja kont Google.

W tym dokumencie opisujemy podstawy protokołu danych Google, które są używane w wielu interfejsach API Google, w tym przykładowe zapytania, wygląd wyników itd.

Więcej informacji o protokole Google Data Protocol znajdziesz na stronie z przeglądem Przewodnika dla programistów i w dokumentacji protokołu.

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.

Jeśli chcesz wypróbować przykłady w tym dokumencie bez pisania kodu, skorzystaj z narzędzia wiersza poleceń cURL lub Wget. Aby dowiedzieć się więcej, zapoznaj się z instrukcjami ręcznymi dotyczącymi tych narzędzi lub z artykułem na temat korzystania z cURL do korzystania z usług, które korzystają z protokołu danych Google.

Przykłady

Poniższe przykłady pokazują żądania HTTP, które możesz wysłać do usługi ogólnej przy użyciu protokołu Google Data Protocol bezpośrednio, 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 protokołu Google z konkretnymi usługami Google znajdziesz w dokumentacji tej usługi.

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ą zobaczyć, wyślij do serwera to żądanie HTTP:

GET /myFeed

Serwer odpowiada:

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>

Pamiętaj, że mimo że kanał nie zawiera żadnych wpisów, zawiera metadane, takie jak tytuł i nazwisko autora. Zawiera on też identyfikator wersji w formacie ETag HTTP.

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' 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>

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' 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>

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 plikiem danych zawierającym wszystkie wpisy, które pasują do ciągu wyszukiwania This. (W tym przypadku jest tylko jedna opcja).

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>

Aktualizowanie wpisu

Aby zaktualizować istniejący wpis, wykonaj następujące czynności.

  1. Pobierz wpis, który chcesz zaktualizować.
  2. Wprowadź odpowiednie zmiany.
  3. Wyślij żądanie PUT ze zaktualizowanym wpisem w treści wiadomości do identyfikatora URI edycji wpisu. W poprzednim przykładzie identyfikator URI edycji jest atrybutem href elementu <link rel='edit'>.

Musisz też określić tag ETag oryginalnego wpisu, aby mieć pewność, że nie zastąpisz zmian wprowadzonych przez inną osobę.

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' 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>

Serwer odpowiada:

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>

Tag ETag się zmienił. Więcej informacji o wersjach zasobów znajdziesz w sekcji Obsługa wersji zasobów (ETags) 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' 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>

Uwaga: jeśli zapora sieciowa nie zezwala na PUT, wykonaj HTTP HTTP POST i ustaw nagłówek zastępowania metod w ten sposób:

X-HTTP-Method-Override: PUT

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

Usuwając wpis, możesz wybrać, czy ma on zostać usunięty warunkowo (tylko w przypadku, gdy wpis nie został zmieniony od czasu ostatniego pobrania), czy też usunięty bezwarunkowo. Więcej informacji znajdziesz w sekcji Obsługa wersji zasobów (ETags) w dokumentacji referencyjnej protokołu. Aby usunąć usuwanie bezwarunkowe, ustaw ten nagłówek HTTP:

If-Match: *

Ten przykład usuwa wpis (jeśli nagłówki są odpowiednio ustawione):

DELETE /myFeed/1/

Serwer odpowiada:

200 OK

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

GET /myFeed

Serwer odpowiada kanałem, który zawiera wyłącznie metadane:

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>

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.

Żądanie częściowych plików danych lub wpisów (funkcja eksperymentalna)

W przeciwieństwie do prostego przykładowego pliku danych wyświetlanego w tym dokumencie kanały w praktyce mogą być dość złożone. W przypadku niektórych interfejsów API możesz prosić tylko o wybrane elementy lub atrybuty, a nie o pełne reprezentowanie zasobów. Unikając pobierania i analizowania niepotrzebnych danych, możesz znacznie zwiększyć wydajność aplikacji klienckiej.

Aby wysłać żądanie częściowej odpowiedzi, użyj parametru zapytania fields, który określa, które elementy lub atrybuty mają być zwracane. Więcej informacji znajdziesz w sekcji Odpowiedź częściowa w dokumencie referencyjnym protokołu.

W tym przykładzie wymagany jest tylko identyfikator kanału oraz autor i tytuł każdego wpisu w kanale,

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

Serwer odpowiada:

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>

Parametru fields możesz używać w przypadku dowolnego żądania, które zwraca dane. Obejmują one nie tylko parametry GET, jak i POST (PUT, a także PATCH, który służy do wysyłania żądań).

Uwaga: parametr zapytania fields określa tylko dane wysyłane w odpowiedzi na żądanie. Nie ma wpływu na dane, które należy podać w treści żądania PUT, POST lub PATCH.

Poniżej znajdziesz przykłady znaczników POST i PUT.

  • Wysyłając żądanie POST do odpowiedzi częściowej, musisz podać takie same dane jak opisano w artykule Wstawianie nowego wpisu. Ten przykład żąda częściowej odpowiedzi, która zawiera tylko tytuł nowo utworzonego wpisu: 
    POST /myFeed?fields=title
      
...data...

    Serwer odpowiada:

    200 OK

<?xml version='1.0' encoding='utf-8'?>
<entry xmlns='http://www.w3.org/2005/Atom'>
  <title type='text'>Entry 1</title>
</entry>
  • Wysyłając żądanie PUT do odpowiedzi częściowej, nadal musisz podawać zmodyfikowaną wersję pełnej reprezentacji zasobów zgodnie z opisem w sekcji Aktualizowanie wpisu. Ten przykład żąda częściowej odpowiedzi, która zawiera tylko nową wartość ETag zmodyfikowanego wpisu: 
    PUT /myFeed/1/1?fields=@gd:etag
  
...data...

    Serwer odpowiada:

    200 OK

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

Aktualizowanie określonych pól (eksperymentalne)

Jeśli używany interfejs API obsługuje częściową odpowiedź i zawiera edytowalne pola, możesz również uniknąć przesyłania zbędnych danych podczas modyfikowania wpisu. Częściowa aktualizacja umożliwia wysyłanie danych tylko w przypadku pól, które chcesz zmienić.

Aby użyć częściowej aktualizacji, wyślij żądanie PATCH na ten sam identyfikator URI edycji, którego używasz w usłudze PUT. Dane wysyłane za pomocą PATCH muszą być zgodne z określonymi konwencjami. Jednak ich semantyka jest dostatecznie elastyczna, że możesz zastąpić dane w zasobie docelowym, dodać je do siebie, a nawet usunąć z niego pojedyncze żądanie.

Uwaga: podobnie jak w przypadku tagu PUT, musisz określić tag ETag oryginalnego wpisu, aby mieć pewność, że nie wprowadzasz żadnych zmian w postaci zmiany wprowadzonej przez innych.

Więcej informacji o PATCH i jego semantyce znajdziesz w sekcji Częściowa aktualizacja w dokumencie referencyjnym protokołu.

Przykład żądania częściowej aktualizacji, który zmienia tytuł wpisu:

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>

Po otrzymaniu żądania PATCH serwer najpierw usuwa wszystkie pola określone w atrybucie gd:fields wpisu (jeśli jest podany), a następnie scala wszystkie dane podane w treści żądania z zasobem docelowym. W tym przykładzie element tytułu zostaje najpierw usunięty z zasobu docelowego, a następnie scalana jest wartość nowego tytułu. To żądanie zastąpi stary tytuł nowym.

Pamiętaj jednak, że semantyka elementu PATCH musi scalić częściową reprezentację do istniejącego zasobu. Nie zawsze musisz usuwać dane pole, aby aktualizować jego wartość.

  • Jeśli pole istnieje tylko raz we wpisie docelowym, to po scaleniu pole w częściowej reprezentacji nadpisze odpowiednie pole we wpisie docelowym.
  • Jeśli pole istnieje więcej niż raz we wpisie docelowym, po scaleniu pole częściowe zostanie dodane do wpisu docelowego.

Różnicę między polami, które się powtarzają i nie powtarzają się, znajdziesz w następnym przykładzie, w którym nowy wpis i autor są dodawane do wpisu bez wcześniejszego usunięcia atrybutu atrybutu gd:fields.

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>

Częściowa reprezentacja wpisu nie ma atrybutu gd:fields, więc nie są usuwane żadne pola. Jednak nowe wartości elementów <title> i <author> zostaną scalone z zasobem docelowym:

  • Ponieważ Atom obsługuje tylko 1 tytuł na każdy wpis, nowy tytuł zastępuje istniejącą wartość. 
  • Ponieważ Atom umożliwia stosowanie wielu autorów w pojedynczym wpisie, jest dodawany do listy elementów autora znajdujących się już w zasobie docelowym.

    Uwaga: nie wszystkie interfejsy API są zgodne ze standardem Atom. Na przykład niektóre interfejsy API obsługują tylko jeden element <author> na każdy wpis; inne dziedziczą autora wpisu z poziomu kanału, dzięki czemu pole jest tylko do odczytu.

Po przetworzeniu przez serwer prawidłowego żądania PATCH zwraca kod stanu HTTP 200 i pełną kopię zaktualizowanego wpisu.

Jeśli wolisz, aby serwer zwracał tylko określone elementy lub atrybuty, możesz użyć parametru zapytania fields z atrybutem PATCH, aby zażądać częściowej odpowiedzi.

Dodatkowe materiały

Oto dokumenty innych firm:

Powrót do góry