W tym dokumencie opisano protokół używany przez interfejsy API danych Google, w tym informacje o wyglądzie zapytania, wynikach i tym podobnych.
Więcej informacji o interfejsach API danych Google znajdziesz w przewodniku Google dla programistów danych oraz w przewodniku po zasadach.
Odbiorcy
Ten dokument jest przeznaczony dla wszystkich, którzy chcą poznać szczegółowe informacje na temat formatu XML i protokołu używanych przez interfejsy API danych Google.
Jeśli chcesz napisać kod, który używa interfejsów API klienta Google Data, nie musisz znać tych szczegółów. Zamiast tego możesz użyć bibliotek klienta dla danego języka.
Jeśli jednak chcesz zrozumieć protokół, przeczytaj ten dokument. Ten dokument może Ci się przydać na przykład w przypadku następujących zadań:
- analizowanie architektury danych Google
- kodowania z użyciem protokołu bez użycia bibliotek klienckich danych Google.
- pisanie biblioteki klienta w nowym języku
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, można wysyłać i odbierać wiadomości z danymi Google przy użyciu dowolnego języka programowania, który pozwala wysyłać żądania HTTP i analizować odpowiedzi oparte na formacie XML.
Szczegóły protokołu
Ta sekcja opisuje format dokumentu danych Google i składnię zapytań.
Format dokumentu
Dane Google, Atom i RSS 2.0 mają ten sam podstawowy model danych: kontener, w którym znajdują się zarówno dane globalne, jak i dowolna liczba wpisów. W przypadku każdego protokołu format jest określany przez schemat podstawowy, ale można go rozszerzyć za pomocą obcych przestrzeni nazw.
Interfejsy API danych Google mogą używać formatu Atom (tylko do odczytu i zapisu) lub RSS (tylko do odczytu).
Atom to domyślny format danych Google. Aby wysłać odpowiedź w formacie RSS, użyj parametru /alt=rss/. Więcej informacji znajdziesz w artykule Zapytania.
Gdy żądasz danych w formacie RSS, dane Google udostępniają kanał (lub inną reprezentację zasobu) w formacie RSS. Jeśli dla danej usługi danych Google nie ma odpowiednika RSS, usługa Google używa danych Atom, oznaczając je odpowiednią przestrzenią nazw, aby wskazać, że jest to rozszerzenie RSS.
Uwaga: większość plików danych Google w formacie Atom używa przestrzeni nazw Atom jako domyślnej przestrzeni nazw, podając atrybut xmlns w elemencie pliku danych. Przykłady znajdziesz w sekcji z przykładami. Dlatego przykłady w tym dokumencie nie określają jednoznacznie atom: w przypadku elementów w formacie Atom.
W tabelach poniżej przedstawiono elementy Atom i RSS elementów schematu. Wszystkie dane, które nie zostały wymienione w tych tabelach, są traktowane jak zwykły kod XML i wyświetlane w obu przypadkach. O ile nie wskazano inaczej, elementy XML w danej kolumnie znajdują się w przestrzeni nazw odpowiadającej tej kolumnie. To podsumowanie korzysta ze standardowego zapisu XPath: ukośniki wskazują hierarchię elementów, a symbol @ oznacza atrybut elementu.
W poniższych tabelach wymagane są wyróżnione elementy.
Poniższa tabela przedstawia elementy pliku danych Google:
| Element schematu kanału | Reprezentacja Atom | Prezentacja RSS |
|---|---|---|
| Tytuł pliku danych | /feed/title |
/rss/channel/title |
| Identyfikator kanału RSS | /feed/id |
/rss/channel/atom:id |
| Link do kanału HTML | /feed/link[@rel="alternate"]\[@type="text/html"]/@href |
/rss/channel/link |
| Opis kanału | /feed/subtitle |
/rss/channel/description |
| Język pliku danych | /feed/@xml:lang |
/rss/channel/language |
| Prawa autorskie kanału | /feed/rights |
/rss/channel/copyright |
| Autor kanału |
(w niektórych przypadkach wymagane; zobacz specyfikację Atom). |
/rss/channel/managingEditor |
| Data ostatniej aktualizacji pliku danych | /feed/updated(format RFC 3339) |
/rss/channel/lastBuildDate(format RFC 822) |
| Kategoria pliku danych | /feed/category/@term |
/rss/channel/category |
| Schemat kategorii pliku danych | /feed/category/@scheme |
/rss/channel/category/@domain |
| Generator plików danych | /feed/generator/feed/generator/@uri |
/rss/channel/generator |
| Ikona pliku danych | /feed/icon |
/rss/channel/image/url (chyba że logo ma też logo – w takim przypadku nie ma ikony). |
| Logo pliku danych | /feed/logo |
/rss/channel/image/url |
Poniższa tabela przedstawia elementy kanału z wynikami wyszukiwania danych Google. Pamiętaj, że dane Google udostępniają w kanałach wyników wyszukiwania niektóre elementy odpowiedzi OpenSearch 1.1.
| Element schematu kanału wyników wyszukiwania | Reprezentacja Atom | Reprezentacja RSS/OpenSearch |
|---|---|---|
| Liczba wyników wyszukiwania | /feed/openSearch:totalResults |
/rss/channel/openSearch:totalResults |
| Indeks początkowy wyniku wyszukiwania | /feed/openSearch:startIndex |
/rss/channel/openSearch:startIndex |
| Liczba wyników wyszukiwania na stronie | /feed/openSearch:itemsPerPage |
/rss/channel/openSearch:itemsPerPage |
Poniższa tabela przedstawia elementy wpisu danych Google:
| Element schematu wpisów | Reprezentacja Atom | Prezentacja RSS |
|---|---|---|
| Entry ID | /feed/entry/id |
/rss/channel/item/guid |
| Identyfikator wersji wpisu | Opcjonalnie umieszczone w edytorze URI (zobacz sekcję Równoczesna optymalizacja w tym dokumencie). | — |
| Tytuł wpisu | /feed/entry/title |
/rss/channel/item/title |
| Link do wpisu | /feed/entry/link |
/rss/channel/item/link/rss/channel/item/enclosure/rss/channel/item/comments |
| Podsumowanie wpisu |
(w niektórych przypadkach wymagane; zobacz specyfikację Atom). |
/rss/channel/item/atom:summary |
| Treść wpisu |
(Jeśli nie ma elementu treści, wpis musi zawierać co najmniej 1 element |
/rss/channel/item/description |
| Autor wpisu |
(w niektórych przypadkach wymagane; zobacz specyfikację Atom). |
/rss/channel/item/author |
| Kategoria wpisu | /feed/entry/category/@term |
/rss/channel/item/category |
| Schemat kategorii wpisów | /feed/entry/category/@scheme |
/rss/channel/item/category/@domain |
| Data publikacji wpisu | /feed/entry/published(RFC 3339) |
/rss/channel/item/pubDate(RFC 822) |
| Data aktualizacji wpisu | /feed/entry/updated(RFC 3339) |
/rss/channel/item/atom:updated(RFC 3339) |
Zapytania
W tej sekcji dowiesz się, jak korzystać z systemu zapytań.
Pytania dotyczące projektowania modeli zapytań
Model zapytań jest celowo bardzo prosty. Podstawowe założenia to:
- Zapytania są podawane jako identyfikatory URI HTTP, a nie jako nagłówki HTTP czy jako część ładunku. Jedną z zalet takiego podejścia jest to, że możesz dodać link do zapytania.
- Predykaty obejmują zakres pojedynczego elementu. Nie ma więc możliwości wysłania zapytania o korelację, na przykład „znajdź wszystkie e-maile od osób, które wysłały mi dzisiaj co najmniej 10 e-maili”.
- Zestaw właściwości, które mogą być wskazywane przez zapytania, jest bardzo ograniczony. Większość zapytań to proste zapytania tekstowe.
- Kolejność wyników zależy od implementacji.
- Protokół można w naturalny sposób zwiększać. Jeśli chcesz udostępnić dodatkowe predykaty lub sortować usługę, możesz to łatwo zrobić, wprowadzając nowe parametry.
Zapytania
Klient wysyła zapytanie do usługi danych Google, wysyłając żądanie HTTP GET. Identyfikator URI zapytania składa się z identyfikatora URI zasobu (w pliku Atom o nazwie FeedURI) i parametrów zapytania. Większość parametrów zapytania jest wyświetlanych jako tradycyjne parametry adresu URL ?name=value[&...]. Parametry kategorii są obsługiwane w różny sposób (patrz poniżej).
Jeśli np. identyfikator URI to http://www.example.com/feeds/jo, możesz wysłać zapytanie z tym identyfikatorem URI:
http://www.example.com/feeds/jo?q=Darcy&updated-min=2005-04-19T15:30:00Z
Usługi danych Google obsługują warunkowe HTTP GET. Ustawienie nagłówka odpowiedzi ostatniej modyfikacji na podstawie wartości elementu <atom:updated> w zwróconym pliku danych lub wpisie. Klient może wysłać tę wartość z powrotem jako wartość nagłówka żądania If-Modified-From, by uniknąć ponownego pobrania treści, jeśli się nie zmieniła. Jeśli treści nie zmieniły się od czasu If-Modified-From, usługa danych Google zwraca odpowiedź HTTP 304 (nie zmodyfikowaną).
Usługa danych Google musi obsługiwać zapytania o kategorię i zapytania alt. Obsługa innych parametrów jest opcjonalna. Jeśli wystąpi standardowy parametr, który nie jest zrozumiały dla danej usługi, wyświetla się odpowiedź 403 Forbidden. Przekazanie nieobsługiwanego parametru niestandardowego powoduje wysłanie odpowiedzi 400 Bad Request. Informacje o innych kodach stanu znajdziesz w sekcji dotyczącej kodów stanu HTTP w tym dokumencie.
Standardowe parametry zapytania znajdziesz w tabeli poniżej. Wszystkie wartości parametrów muszą być zakodowane na potrzeby adresu URL.
| Parametr | Znaczenie | Uwagi |
|---|---|---|
q |
Pełny tekst zapytania |
|
/-/category |
Filtr kategorii |
|
category |
Filtr kategorii |
|
author |
Autor wpisu |
|
alt |
Alternatywny typ reprezentacji |
|
updated-min, updated-max |
Ograniczenia w dniu aktualizacji wpisu |
|
published-min, published-max |
jest ograniczona do daty publikacji wpisu; |
|
start-index |
1 indeks oparty na pierwszym wyniku do pobrania |
|
max-results |
Maksymalna liczba wyników do pobrania | W przypadku każdej usługi, która ma domyślną wartość max-results (aby ograniczyć domyślny rozmiar kanału), możesz podać bardzo dużą liczbę, jeśli chcesz otrzymać cały kanał. |
| entryID | Identyfikator konkretnego wpisu do pobrania |
|
Zapytania dotyczące kategorii
Postanowiliśmy określić nieco nietypowy format dla zapytań dotyczących kategorii. Zamiast zapytania:
http://example.com/jo?category=Fritz&category=2006
wykorzystujemy:
http://example.com/jo/-/Fritz/2006
Takie podejście pozwala zidentyfikować zasób bez używania parametrów zapytania i uzyskać bardziej przejrzyste identyfikatory URI. Wybraliśmy tę kategorię, ponieważ naszym zdaniem najczęstsze zapytania są najczęściej stosowane.
Wadą tego podejścia jest to, że w zapytaniach dotyczących kategorii musisz używać nazwy /-/, aby usługi danych Google odróżniały zapytania kategorii od innych identyfikatorów URI zasobów, takich jak http://example.com/jo/MyPost/comments.
Odpowiedzi na zapytania
Zapytania zwracają kanał Atom, wpis Atom lub kanał RSS, w zależności od parametrów żądania.
Wyniki wyszukiwania zawierają te elementy OpenSearch bezpośrednio pod elementem <feed> lub <channel> (w zależności od tego, czy wyniki to Atom czy RSS):
openSearch:totalResults- Łączna liczba wyników wyszukiwania danego zapytania (niekoniecznie wszystkie widoczne w pliku danych wyników).
openSearch:startIndex- Indeks 1 wyniku pierwszego wyniku.
openSearch:itemsPerPage- Maksymalna liczba elementów na jednej stronie. Dzięki temu klienci mogą generować bezpośrednie linki do dowolnego zestawu kolejnych stron. Jeśli jednak chcesz natrafić na ten numer, zapoznaj się z uwagą na temat
start-indexw tabeli w sekcji Żądania zapytań.
Kanał i odpowiedzi w witrynie Atom mogą zawierać również dowolne z tych elementów danych Atom i Google (oraz inne dane wymienione w specyfikacji Atom):
<link rel="http://schemas.google.com/g/2005#feed" type="application/atom+xml" href="..."/>- Określa identyfikator URI, z którego można pobrać pełny kanał Atom.
<link rel="http://schemas.google.com/g/2005#post" type="application/atom+xml" href="..."/>- Określa postURI kanału Atom (gdzie można publikować nowe wpisy).
<link rel="self" type="..." href="..."/>- Zawiera identyfikator URI zasobu. Wartość atrybutu
typezależy od żądanego formatu. Jeśli tymczasem nie nastąpi zmiana danych, wysłanie tej samej wartości GET do innego identyfikatora URI spowoduje zwrócenie tej samej odpowiedzi. <link rel="previous" type="application/atom+xml" href="..."/>- Określa identyfikator URI poprzedniego fragmentu tego zestawu wyników (jeśli jest on podzielony).
<link rel="next" type="application/atom+xml" href="..."/>- Określa identyfikator URI następnego fragmentu tego zestawu wyników zapytania, jeśli jest on podzielony.
<link rel="edit" type="application/atom+xml" href="..."/>- Określa element EditURI we wpisie Atom (gdzie wysyłasz zaktualizowany wpis).
Oto przykładowa treść odpowiedzi w odpowiedzi na zapytanie:
<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns:atom="http://www.w3.org/2005/Atom"
xmlns:openSearch="http://a9.com/-/spec/opensearchrss/1.0/">
<id>http://www.example.com/feed/1234.1/posts/full</id>
<updated>2005-09-16T00:42:06Z</updated>
<title type="text">Books and Romance with Jo and Liz</title>
<link rel="alternate" type="text/html" href="http://www.example.net/"/>
<link rel="http://schemas.google.com/g/2005#feed"
type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full"/>
<link rel="http://schemas.google.com/g/2005#post"
type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full"/>
<link rel="self" type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full"/>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
<generator version="1.0"
uri="http://www.example.com">Example Generator Engine</generator>
<openSearch:totalResults>2</openSearch:totalResults>
<openSearch:startIndex>0</openSearch:startIndex>
<entry>
<id>http://www.example.com/feed/1234.1/posts/full/4521614025009481151</id>
<published>2005-01-09T08:00:00Z</published>
<updated>2005-01-09T08:00:00Z</updated>
<category scheme="http://www.example.com/type" term="blog.post"/>
<title type="text">This is the title of entry 1009</title>
<content type="xhtml">
<div
xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1009</div>
</content>
<link rel="alternate" type="text/html"
href="http://www.example.com/posturl"/>
<link rel="edit" type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full/4521614025009481151"/>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
</entry>
<entry>
<id>http://www.example.com/feed/1234.1/posts/full/3067545004648931569</id>
<published>2005-01-07T08:00:00Z</published>
<updated>2005-01-07T08:02:00Z</updated>
<category scheme="http://www.example.com/type" term="blog.post"/>
<title type="text">This is the title of entry 1007</title>
<content type="xhtml">
<div
xmlns="http://www.w3.org/1999/xhtml">This is the entry body of entry 1007</div>
</content>
<link rel="alternate" type="text/html"
href="http://www.example.com/posturl"/>
<link rel="edit" type="application/atom+xml"
href="http://www.example.com/feed/1234.1/posts/full/3067545004648931569"/>
<author>
<name>Elizabeth Bennet</name>
<email>liz@gmail.com</email>
</author>
</entry>
</feed>
Jeśli żądany plik danych ma format Atom, a nie zostały określone żadne parametry zapytania i nie zawiera on wszystkich wpisów, w kanale najwyższego poziomu pojawi się ten element: <link rel="next" type="application/atom+xml" href="..."/>. Wskazuje on kanał zawierający następny zbiór wpisów. Kolejne zestawy zawierają odpowiedni element <link rel="previous" type="application/atom+xml" href="..."/>. Klikając wszystkie kolejne linki, klient może pobrać wszystkie wpisy z kanału.
Kody stanów HTTP
W poniższej tabeli opisano różne kody stanu HTTP w kontekście usług danych Google.
| Kod | Objaśnienie |
|---|---|
| 200 OK | Brak błędów. |
| 201 UTWORZONE | Udało się utworzyć zasób. |
| 304 NIE ZMODYFIKOWANO | Zasób nie zmienił się od czasu określonego w nagłówku If-Modified-From. |
| 400 ZŁYCH PROŚB | Nieprawidłowy identyfikator URI lub nagłówek żądania albo nieobsługiwany parametr niestandardowy. |
| 401 NIEAUTORYZOWANYCH | Wymagana jest autoryzacja. |
| 403 Zabronione | Nieobsługiwany parametr standardowy albo uwierzytelnianie lub autoryzacja nie powiodło się. |
| 404 NIE ZNALEZIONO | Nie znaleziono zasobu (np. kanału lub wpisu). |
| 409 ROZWÓJ | Podany numer wersji nie odpowiada numerowi najnowszej wersji zasobu. |
| 500 WEWNĘTRZNY BŁĄD SERWERA | Błąd wewnętrzny. Jest to kod domyślny używany w przypadku wszystkich nierozpoznanych błędów. |
Optymizm równoczesny (wersja)
Czasami ważne jest, aby upewnić się, że wielu klientów nie przypadkiem nie zastępuje innych zmian. Najłatwiej to zrobić, upewniając się, że bieżąca wersja wpisu, który klient zmodyfikował, jest taka sama jak wersja, którą klient wprowadza w bazie. Jeśli drugi klient przeprowadzi aktualizację, zanim zrobi to pierwszy klient, odmawia ona aktualizacji, ponieważ pierwszy klient nie opiera już swoich modyfikacji na najnowszej wersji.
W plikach danych Google, które obsługują wersje, semantykę uzyskujemy, dodając identyfikator wersji do elementu EditURI każdego wpisu. Pamiętaj, że problem dotyczy tylko identyfikatora URI, nie identyfikatora wpisu. W tym schemacie każda aktualizacja powoduje zmianę identyfikatora URI URI, dzięki czemu kolejne aktualizacje na podstawie pierwotnej wersji kończą się niepowodzeniem. Usuwanie jest oczywiście identyczne z aktualizacjami tej funkcji. Usunięcie usługi w starej wersji spowoduje jej usunięcie.
Nie wszystkie pliki danych Google obsługują optymizm równoczesny. Jeśli w kanale, który obsługuje ten format, serwer wykryje konflikt wersji w stanie PUT lub DELETE, zwróci odpowiedź 409 Conflict. Treść odpowiedzi zawiera bieżący stan wpisu (dokument wejścia Atom). Klient powinien rozwiązać konflikt i ponownie przesłać żądanie, korzystając z identyfikatora EditURI z odpowiedzi 409.
Motywacja i uwagi projektowe
Ta metoda optymalizowania na podstawie równoczesności pozwala nam wdrożyć semantykę bez konieczności dodawania nowych identyfikatorów dla wersji, dzięki czemu odpowiedzi danych Google są zgodne z punktami końcowymi Atom Google innych niż Google.
Zamiast określania identyfikatorów wersji moglibyśmy sprawdzić sygnaturę czasową aktualizacji w każdym wpisie (/atom:entry/atom:updated). Jednak istnieją 2 problemy z sygnaturą czasową aktualizacji:
- Działa tylko w przypadku aktualizacji – nie można ich usunąć.
- Wymusza używanie w aplikacjach wartości daty i godziny jako identyfikatorów wersji, co utrudnia modernizację danych Google do wielu istniejących baz danych.
Uwierzytelnianie
Gdy klient próbuje uzyskać dostęp do usługi, może być konieczne podanie danych logowania użytkownika w tej usłudze, aby udowodnić, że jest uprawniony do wykonania danego działania.
Sposób, w jaki klient powinien korzystać z uwierzytelniania, zależy od jego typu:
- Aplikacja komputerowa powinna używać własnego systemu uwierzytelniania Google o nazwie Uwierzytelnianie konta dla zainstalowanych aplikacji (nazywanym też „ClientLogin”). (Klienty nie powinni używać tego systemu).
- Klient sieciowy, np. interfejs innej firmy w usłudze Dane Google, powinien używać uwierzytelniania Google nazywanego Serwerem uwierzytelniania kont w aplikacjach internetowych (nazywanym też „AuthSub”).
W systemie ClientLogin klient komputerowy pyta użytkownika o dane logowania, a następnie wysyła je do systemu uwierzytelniania Google.
Jeśli uwierzytelnianie się powiedzie, system uwierzytelniania zwróci token, którego klient następnie używa (w nagłówku autoryzacji HTTP) do wysyłania żądań danych Google.
Jeśli uwierzytelnianie się nie powiedzie, serwer zwróci kod stanu 403 Forbidden (Dostęp zabroniony) wraz z nagłówkiem WWW-Authenticate zawierającym wyzwanie związane z uwierzytelnianiem.
System AuthSub działa podobnie, z tą różnicą, że nie prosi użytkownika o dane logowania, tylko łączy go z usługą Google, która prosi o dane logowania. Następnie usługa zwraca token, którego może używać aplikacja internetowa. Zaletą tej metody jest to, że Google (zamiast interfejsu internetowego) w bezpieczny sposób obsługuje i przechowuje dane logowania użytkownika.
Szczegółowe informacje o tych systemach uwierzytelniania znajdziesz w artykule Omówienie uwierzytelniania danych Google lub Uwierzytelnianie konta Google.
Stan sesji
Wiele implementacji logiki biznesowej wymaga utrzymywania sesji, aby śledzić stan sesji użytkownika.
Google śledzi stan sesji na 2 sposoby: używając plików cookie lub tokena, który można wysłać jako parametr zapytania. Oba sposoby dają ten sam efekt. Zalecamy, aby klienci obsługiwały jedną z tych metod śledzenia stanu sesji. Jeśli klient nie obsługuje żadnej z tych metod, może nadal korzystać z usług danych Google, ale skuteczność może być niższa niż w przypadku klientów, którzy obsługują te metody. Jeśli klient nie obsługuje tych metod, każde żądanie powoduje przekierowanie, dlatego każde żądanie (i powiązane z nim dane) jest wysyłane do serwera dwukrotnie, co ma wpływ na wydajność zarówno klienta, jak i serwera.
Biblioteki klienta Google obsługują stan sesji, więc jeśli korzystasz z naszych bibliotek, nie musisz nic robić, aby uzyskać pomoc dotyczącą stanu sesji.
Dodatkowe materiały
Oto dokumenty innych firm:
- Porównanie kanałów Atom i RSS z przeplatanymi treściami
- Omówienie Atom od IBM
- Rozszerzenia Dublin Core do RSS
- Definicje metod HTTP 1.1; specyfikacja w
GET,POST,PUTiDELETE - Definicje kodów stanu HTTP 1.1
- Jak utworzyć protokół REST
- Tworzenie usług internetowych w sposób REST
- Wprowadzenie techniczne do kodu XML
- Przestrzenie nazw XML według przykładu