Ta strona została przetłumaczona przez Cloud Translation API.

Dokumentacja protokołu

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.

Ten dokument opisuje protokół danych Google używany w wielu interfejsach API Google, w tym informacje na temat wyglądu zapytania, wyników itp.

Więcej informacji o protokole Google Data Protocol znajdziesz na stronie przeglądu w przewodniku dla programistów i w artykule Podstawy protokołu.

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 implementujące protokół Google Data Protocol.

Jeśli chcesz napisać kod, który korzysta z jednego z tych interfejsów API, nie musisz znać tych szczegółów. Zamiast tego możesz użyć bibliotek klienckich.

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 protokołu danych Google
kodowania za pomocą protokołu bez konieczności używania bibliotek klienckich.
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.

Dokument nie wymaga konkretnego języka programowania. Wiadomości można wysyłać i odbierać za pomocą dowolnego języka programowania, który pozwala wysyłać żądania HTTP i analizować odpowiedzi XML.

Szczegóły protokołu

Ta sekcja opisuje format dokumentu Google Data Data i składnię zapytań.

Format dokumentu

Protokół Google Data Protocol i Atom 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.

Atom to domyślny format protokołu danych Google. Aby wysłać odpowiedź w innym formacie, użyj parametru zapytania alt. Więcej informacji znajdziesz w artykule Zapytania.

Uwaga: większość kanałów Google Data Protocol w formacie Atom używa przestrzeni nazw Atom jako domyślnej przestrzeni nazw, podając atrybut xmlns w elemencie pliku danych, tak jak w przykładach podanych w sekcji Protocol Basics. Dlatego przykłady w tym dokumencie nie określają jednoznacznie atom: w przypadku elementów w formacie Atom.

W tabelach poniżej znajdziesz elementy Atom przedstawiające elementy schematu. Wszystkie dane, które nie zostały wymienione w tych tabelach, są traktowane jak zwykły kod XML. O ile nie wskazano inaczej, elementy XML w danej kolumnie znajdują się w przestrzeni nazw Atom.

Uwaga: w tym podsumowaniu zastosowano standardową notację XPath: ukośniki pokazują hierarchię elementów, a znak @ wskazuje atrybut elementu.

W poniższych tabelach wymagane są wyróżnione elementy.

Tabela przedstawia elementy kanału danych Google:

Element schematu kanału	Reprezentacja Atom
Tytuł pliku danych	`/feed/title`
Identyfikator kanału RSS	`/feed/id`
Link do kanału HTML	`/feed/link[@rel="alternate"]`\ `[@type="text/html"]/@href`
Opis kanału	`/feed/subtitle`
Język pliku danych	`/feed/@xml:lang`
Prawa autorskie kanału	`/feed/rights`
Autor kanału	`/feed/author/name` `/feed/author/email` (w niektórych przypadkach wymagane; zobacz specyfikację Atom).
Data ostatniej aktualizacji pliku danych	`/feed/updated` (format RFC 3339)
Kategoria pliku danych	`/feed/category/@term`
Schemat kategorii pliku danych	`/feed/category/@scheme`
Generator plików danych	`/feed/generator` `/feed/generator/@uri`
Ikona pliku danych	`/feed/icon`
Logo pliku danych	`/feed/logo`

Poniższa tabela przedstawia elementy kanału wyników wyszukiwania Google Data Protocol. Pamiętaj, że protokół udostępnia niektóre elementy odpowiedzi OpenSearch 1.1 w kanałach wyników wyszukiwania.

Element schematu kanału wyników wyszukiwania	Reprezentacja Atom
Liczba wyników wyszukiwania	`/feed/openSearch:totalResults`
Indeks początkowy wyniku wyszukiwania	`/feed/openSearch:startIndex`
Liczba wyników wyszukiwania na stronie	`/feed/openSearch:itemsPerPage`

Tabela zawiera elementy wpisu dotyczącego protokołu danych Google:

Element schematu wpisów	Reprezentacja Atom
Entry ID	`/feed/entry/id`
Tytuł wpisu	`/feed/entry/title`
Link do wpisu	`/feed/entry/link`
Podsumowanie wpisu	`/feed/entry/summary` (w niektórych przypadkach wymagane; zobacz specyfikację Atom).
Treść wpisu	`/feed/entry/content` (Jeśli nie ma elementu treści, wpis musi zawierać co najmniej 1 element `<link rel="alternate">`).
Autor wpisu	`/feed/entry/author/name` `/feed/entry/author/email` (w niektórych przypadkach wymagane; zobacz specyfikację Atom).
Kategoria wpisu	`/feed/entry/category/@term`
Schemat kategorii wpisów	`/feed/entry/category/@scheme`
Data publikacji wpisu	`/feed/entry/published` (RFC 3339)
Data aktualizacji wpisu	`/feed/entry/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 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

Protokół danych Google obsługuje warunkowe HTTP GET. Interfejsy API, które implementują protokół, ustawiają nagłówek odpowiedzi Last-Modified na podstawie wartości elementu <atom:updated> w zwróconym pliku 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 zwraca odpowiedź HTTP 304 (nie zmodyfikowano).

Interfejsy API, które implementują protokół danych Google, muszą obsługiwać 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
`alt`	Alternatywny typ reprezentacji	Jeśli nie określisz parametru `alt`, usługa zwróci kanał Atom. To odpowiednik `alt=atom`. `alt=rss` zwraca kanał wyników RSS 2.0 (tylko do odczytu). Gdy żądasz danych z usługi w formacie RSS, usługa udostępnia kanał (lub inne reprezentowanie zasobu) w formacie RSS. Jeśli w usłudze API danych nie ma odpowiednika w usłudze RSS, usługa używa właściwości Atom, dodając do niej odpowiednią przestrzeń nazw, aby wskazać, że jest to rozszerzenie RSS. `alt=json` zwraca plik danych w formacie JSON. Więcej informacji `alt=json-in-script` żąda odpowiedzi, która opakowuje JSON w tagu skryptu. Więcej informacji `alt=atom-in-script` Wysyła żądanie Atom, które opakowuje ciąg XML z tagu skryptu. `alt=rss-in-script` Wysyła żądanie RSS, które opakowuje ciąg znaków XML z tagu skryptu. `alt=atom-service` Żąda dokumentu usługi Atom opisującego kanał.
`author`	Autor wpisu	Usługa zwraca wpisy, w przypadku których imię i nazwisko autora lub adres e-mail pasują do ciągu zapytania.
`category`	Filtr zapytań kategorii	Alternatywny sposób na filtrowanie kategorii. Te 2 metody są równoważne. Aby wstawić `OR` między terminami, użyj kreski pionowej (\|) zakodowanej w adresie URL jako `%7C`. Na przykład: `http://www.example.com/feeds?category=Fritz%7CLaurie` zwraca wpisy pasujące do każdej kategorii. Aby wstawić znak `AND` między wyszukiwanymi hasłami, użyj przecinka (,). Na przykład `http://www.example.com/feeds?category=Fritz,Laurie` zwraca wpisy pasujące do obu kategorii.
`/-/category`	Filtr zapytań kategorii	Każdą kategorię należy podać w postaci identyfikatora URI zasobu w formacie `/categoryname/` – jest to wyjątek od tradycyjnego formularza `name=value`. Wymień wszystkie kategorie przed innymi parametrami zapytania. Wyróżnij pierwszą kategorię za pomocą atrybutu `/-/`, aby określić, że jest to kategoria. Jeśli na przykład w kanale Jana są kategorie wpisów Fritz, możesz o to poprosić: `http://www.example.com/feeds/jo/-/Fritz`. Dzięki temu implementacja może odróżnić identyfikatory URI zapytania określone na podstawie kategorii od identyfikatorów URI zasobów. Możesz tworzyć zapytania dotyczące wielu kategorii, podając wiele parametrów kategorii rozdzielonych ukośnikami. Usługa zwraca wszystkie wpisy pasujące do wszystkich kategorii (np. `AND`). Na przykład: `http://www.example.com/feeds/jo/-/Fritz/Laurie` zwraca wpisy pasujące do obu kategorii. Aby wstawić `OR` między terminami, użyj znaku kreski pionowej (`\|`) zakodowanej w adresie URL jako `%7C`. Na przykład: `http://www.example.com/feeds/jo/-/Fritz%7CLaurie` zwraca wpisy pasujące do każdej kategorii. Wpis pasuje do określonej kategorii, jeśli należy do kategorii, która ma pasujące hasło lub etykietę zgodnie ze specyfikacją Atom. (Ogólnie „hasło” to wewnętrzny ciąg znaków używany przez oprogramowanie do identyfikowania kategorii, a „etykieta” to zrozumiały dla człowieka ciąg znaków wyświetlany użytkownikowi w interfejsie). Aby wykluczyć wpisy pasujące do danej kategorii, użyj formularza `/-categoryname/`. Aby wyszukać kategorię, która ma schemat, np. `<category scheme="urn:google.com" term="public"/>`, musisz umieścić nawiasy klamrowe przed nazwą kategorii. na przykład: `/{urn:google.com}public`. Jeśli schemat zawiera ukośnik (`/`), powinien być zakodowany jako URL w formacie `%2F`. Aby dopasować kategorię, która nie ma schematu, użyj pustej pary nawiasów klamrowych. Jeśli nie określisz nawiasów klamrowych, kategorie w obrębie dowolnego schematu będą pasować. Te funkcje możesz połączyć. Na przykład: `/A%7C-{urn:google.com}B/-C` oznacza `(A OR (NOT B)) AND (NOT C)`.
entryID	Identyfikator konkretnego wpisu do pobrania	Jeśli podasz identyfikator wpisu, nie możesz podać żadnych innych parametrów. Forma identyfikatora wpisu jest określana przez usługę. W przeciwieństwie do większości innych parametrów zapytania identyfikator wpisu jest określany jako część identyfikatora URI, a nie jako para nazwa=wartość. Przykład: `http://www.example.com/feeds/jo/entry1`.
`fields`	Filtr odpowiedzi	Zwraca tylko żądane pola, a nie pełne informacje o zasobach. Na przykład: http://www.example.com/feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit'])) Po otrzymaniu tego żądania serwer zwraca odpowiedź, która zawiera tylko elementy linku i wpisu. Dodatkowo zwrócone elementy wejściowe to częściowe wpisy, które zawierają tylko tag ETag, identyfikator, został zaktualizowany i edytować relacje z linkami. Wartość w tych polach musi być zakodowana na potrzeby adresu URL, tak jak w przypadku wszystkich wartości parametrów zapytania. Więcej informacji znajdziesz w sekcji Odpowiedź częściowa. Ten parametr jest obecnie funkcją eksperymentalną.
`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ł.
`prettyprint`	Zwraca odpowiedź XML z identycznymi znakami podziału wiersza	W przypadku zasady `prettyprint=true` plik XML zwracany przez serwer będzie czytelny dla człowieka (coś zostaje wydrukowany). Domyślny: `prettyprint=false`
`published-min`, `published-max`	jest ograniczona do daty publikacji wpisu;	Użyj formatu sygnatury czasowej RFC 3339. na przykład: `2005-08-09T10:57:00-08:00`. Dolna granica jest integralna, a górna – jedyna.
`q`	Pełny tekst zapytania	Podczas tworzenia zapytania wyświetl wyszukiwane hasła rozdzielone spacjami w formacie `q=term1 term2 term3`. (tak jak w przypadku wszystkich wartości parametrów zapytania, spacje muszą być zakodowane na potrzeby adresu URL). Usługa zwraca wszystkie wpisy, które pasują do wszystkich wyszukiwanych słów (na przykład `AND`). Podobnie jak w przypadku wyszukiwarki Google, usługa wyszukuje pełne słowa (i powiązane słowa z tym samym rdzeniem), a nie podłańcuchy. Aby wyszukać dokładne wyrażenie, umieść je w cudzysłowie: `q="exact phrase".` Aby wykluczyć wpisy pasujące do danego hasła, użyj formularza `q=-term`. Wielkość znaków nie jest rozróżniana. Przykład: aby znaleźć wszystkie hasła, które zawierają dokładne wyrażenie „Elizabeth Bennet” i słowo „Darcy”, ale nie zawierają słowa „Austen”, użyj tego zapytania: `?q="Elizabeth Bennet" Darcy -Austen`
`start-index`	1 indeks oparty na pierwszym wyniku do pobrania	Pamiętaj, że nie jest to ogólny mechanizm kursora. Jeśli po raz pierwszy wyślesz zapytanie z `?start-index=1&max-results=10`, a potem wyślesz kolejne za pomocą `?start-index=11&max-results=10`, usługa nie może zagwarantować, że wyniki będą równoważne wynikowi `?start-index=1&max-results=20`, bo między zapytaniami mogły wystąpić operacje wstawienia i usunięcia.
`strict`	Ścisłe sprawdzanie parametru zapytania	Ustaw `strict=true`, aby sprawdzić, czy poszczególne parametry zapytania są rozpoznawane przez usługę. Jeśli nie rozpoznamy parametru, zostanie zwrócony błąd. Domyślny: `strict=false`
`updated-min`, `updated-max`	Ograniczenia w dniu aktualizacji wpisu	Użyj formatu sygnatury czasowej RFC 3339. na przykład: `2005-08-09T10:57:00-08:00`. Dolna granica jest integralna, a górna – jedyna. W niektórych przypadkach (np. w przypadku korzystania z interfejsu API danych Kalendarza w wersji 2.1 lub nowszej) określenie zbyt `updated-min`, które znajduje się w przeszłości, powoduje zwrócenie stanu HTTP 410 (brak).

Zapytania dotyczące kategorii

Postanowiliśmy udostępnić nieco nietypowy format dla zapytań dotyczących kategorii. Zamiast wymagać zapytań takich jak to:

http://example.com/jo?category=Fritz&category=2006

umożliwiliśmy:

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ę opcję w przypadku kategorii, ponieważ naszym zdaniem są najpopularniejsze.

Wadą tego podejścia jest to, że w tego typu zapytaniach wymagamy użycia atrybutu /-/, aby usługi mogły odróżniać zapytania od 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-index w tabeli w sekcji Żądania zapytań.

Kanał i odpowiedzi Atom mogą zawierać również dowolne z tych elementów Atom i Data API (a także inne elementy 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 type zależ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="http://www.w3.org/2005/Atom"
        xmlns:openSearch="http://a9.com/-/spec/opensearch/1.1/"
        xmlns:gd='http://schemas.google.com/g/2005'
        gd:etag='W/"C0QBRXcycSp7ImA9WxRVFUk."'>
  <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 gd:etag='W/"C0QBRXcycSp7ImA9WxRVGUo."'>
    <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 gd:etag='W/"C0QBRXrurSp7ImA9WxRVGUo."'>
    <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 tabeli poniżej opisujemy, co oznaczają różne kody stanu HTTP w kontekście interfejsów API danych.

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.
410 GONE	Historia żądanych zmian nie jest już dostępna na serwerze. Więcej informacji znajdziesz w dokumentacji poszczególnych usług.
500 WEWNĘTRZNY BŁĄD SERWERA	Błąd wewnętrzny. Jest to kod domyślny, który jest używany w przypadku wszystkich nierozpoznanych błędów serwera.

Obsługa wersji zasobu (ETag)

Czasami musisz mieć możliwość odwołania się do konkretnej wersji konkretnego wpisu.

Jest to szczególnie ważne w 2 przypadkach:

„Pobieranie warunkowe”, w którym klient wysyła żądanie, a serwer wysyła wpis tylko wtedy, gdy zmienił się on od czasu, gdy klient ostatnio go o to poprosił.
Zadbaj o to, aby wielu klientów nie przypadkiem nie zastępowało swoich zmian. Interfejsy API danych wykonują tę czynność przez aktualizowanie i usuwanie, jeśli klient określi stary identyfikator wersji wpisu.

Interfejsy Google Data API obsługują oba te przypadki przy użyciu ETags (standardowej części HTTP).

ETag to identyfikator określający konkretną wersję danego wpisu. Serwer dołącza tag ETag do wpisów i elementów kanału, które wysyła do klientów. Gdy wpis lub kanał ulega zmianie, zmienia się też tag ETag.

Interfejsy API danych Google udostępniają znaczniki ETag w 2 miejscach: w nagłówku HTTP ETag oraz w atrybucie gd:etag elementów <feed> i <entry>.

W interfejsach API danych Google tag ETag jest zwykle ciągiem liter i cyfr. Czasami zawiera też łączniki i kropki. Zwykle jest on ujęty w cudzysłowy. (cudzysłowy są częścią ETagu). Oto przykładowy tag ETag z wpisu do interfejsu Data API: "S0wCTlpIIip7ImA0X0QI".

Istnieją 2 rodzaje ETagów: silne i słabe. Intensywne tagi ETag określają konkretną wersję konkretnego wpisu i mogą być używane do zastępowania zmian innych klientów. Słabe tagi ETag w kontekście interfejsów API danych Google są używane tylko do warunkowego pobierania. Słaby tag ETag zawsze zaczyna się od W/. Na przykład: W/"D08FQn8-eil7ImA9WxZbFEw."

Nie wszystkie interfejsy API danych Google obsługują silne tagi ETag. W pozostałych przypadkach silne tagi ETag będą używane tylko w przypadku wpisów. Tagi ETag w plikach danych są zawsze słabe.

Oto przykład kanału (w tym niektóre nagłówki HTTP) pobranego z usługi, która obsługuje silne tagi ETag:

GData-Version: 2.0
ETag: W/"C0QBRXcycSp7ImA9WxRVFUk."
...
<?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."'>
  ...
  <entry gd:etag='"CUUEQX47eCp7ImA9WxRVEkQ."'>
    ...
  </entry>
</feed>

Biblioteki klienta, które obsługują wersje 2 interfejsów API danych, w przejrzysty sposób obsługują znaczniki ETag. Te informacje są przeznaczone dla klientów, którzy nie korzystają z bibliotek klienta, oraz dla czytelników zainteresowanych obsługą wersji na poziomie protokołu.

Uwaga: informacje o systemie obsługi wersji zasobów używanym w wersji 1.0 interfejsów API danych znajdziesz w przewodniku po wersji 1.0.

Pobieranie warunkowe

Jeśli chcesz pobrać pobrany wcześniej wpis, możesz zwiększyć wydajność, informując serwer, aby wysyłał tylko te wpisy, które zostały zmienione od czasu ostatniego pobrania.

Aby przeprowadzić tego rodzaju pobieranie warunkowe, wyślij żądanie HTTP GET zawierające nagłówek HTTP If-None-Match. W nagłówku określ tag ETag wpisu.

Oto przykład nagłówka If-None-Match:

If-None-Match: W/"D08FQn8-eil7ImA9WxZbFEw."

Gdy serwer otrzyma to żądanie, sprawdza, czy żądana pozycja ma taki sam tag ETag jak określony przez Ciebie tag ETag. Jeśli tagi ETags pasują, wpis się nie zmienił, a serwer zwraca kod stanu HTTP 304 Not Modified.

Jeśli tagi ETag nie są zgodne, oznacza to, że wpis został zmodyfikowany od czasu ostatniego żądania, a serwer zwraca wpis.

Aktualizowanie wpisów

Najłatwiejszym sposobem na zastąpienie zmian wprowadzonych przez innego klienta jest zaktualizowanie serwera tak, aby gdy klient wysyłał zaktualizowany wpis, wersja utworzona przez niego jest taka sama jak bieżąca wersja przechowywana przez serwer. Jeśli drugi klient zaktualizuje oprogramowanie przed aktualizacją, zostanie ona odrzucona, ponieważ klient nie określa już modyfikacji na podstawie najnowszej wersji.

Gdy klient pobiera dane z usługi, która obsługuje silne tagi ETag, każdy wpis ma tag ETag, który jako unikalny identyfikator wersji odpowiada tej wersji tego wpisu.

Uwaga: aktualizowanie ETagów działa tylko w przypadku silnych tagów ETag. W przypadku usług, które udostępniają słabe tagi ETag, wszystkie aktualizacje są skuteczne niezależnie od tego, czy ktoś inny zaktualizował wpis od czasu jego pobrania. Najnowsza aktualizacja zawsze zastępuje wszystkie wcześniejsze aktualizacje. Nie wysyłaj więc słabej wartości ETag podczas aktualizowania lub usuwania. Jeśli tak, pojawi się komunikat o błędzie.

Gdy klient wysyła aktualizację usługi strong-ETags, musi określić, która wersja wpisu jest aktualizowana. Możesz to zrobić na 2 sposoby:

Użyj nagłówka HTTP If-Match.
Użyj atrybutu gd:etag w elemencie <atom:entry>.

Zalecamy, aby w miarę możliwości korzystać z metody If-Match.

Aby zaktualizować wpis za pomocą If-Match, zacznij od pozyskania tego wpisu. Wprowadź odpowiednie zmiany we wpisie, a następnie utwórz nowe żądanie PUT ze zmodyfikowanym wpisem. (Szczegółowe informacje o adresach URL do użycia znajdziesz w dokumentacji poszczególnych usług).

Zanim wyślesz PUT, dodaj nagłówek HTTP If-Match zawierający tag ETag z pierwotnego wpisu:

If-Match: "S0wCTlpIIip7ImA0X0QI"

Następnie wyślij żądanie PUT.

Jeśli aktualizacja się powiedzie, serwer zwróci kod stanu HTTP 200 OK i kopię zaktualizowanego wpisu.

Jeśli aktualizacja się nie powiedzie, ponieważ podany ETag nie pasuje do bieżącego tagu ETag w wpisie (co sugeruje, że wpis zmienił się na serwerze od ostatniego pobrania), serwer zwraca kod stanu HTTP 412 Precondition Failed.

Jeśli nie możesz łatwo napisać nagłówków HTTP lub masz inny powód, by nie używać nagłówka If-Match, możesz zamiast tego użyć atrybutu gd:etag.

Jeśli nagłówek If-Match nie zostanie wysłany, serwer użyje wartości atrybutu gd:etag zaktualizowanego wpisu jako domniemanej wartości If-Match.

Aby zastąpić system obsługi wersji i zaktualizować wpis niezależnie od tego, czy został on zaktualizowany przez kogoś innego, użyj If-Match: * zamiast określania tagu ETag w nagłówku.

Informacje na temat usług, które obsługują silne znaczniki ETag, znajdziesz w przewodniku po migracji.

Usuwanie wpisów

Usuwanie wpisów, które używają silnych tagów ETag, przypomina ich aktualizowanie.

Aby usunąć wpis z silnym tagiem ETag, najpierw pobierz wpis, który chcesz usunąć, a następnie wyślij żądanie DELETE na adres URL edycji wpisu.

Jeśli chcesz mieć pewność, że nie usuniesz wpisu zmienionego przez innego klienta od czasu jego pobrania, dołącz nagłówek HTTP If-Match zawierający wartość ETag oryginalnego wpisu.

Jeśli chcesz zastąpić system obsługi wersji i usunąć wpis niezależnie od tego, czy został on zaktualizowany przez kogoś innego, użyj If-Match: * zamiast określania tagu ETag w nagłówku.

Jeśli wpis nie ma silnego tagu ETag, żądanie DELETE zawsze zostaje zrealizowane.

Odpowiedź częściowa (funkcja eksperymentalna)

Domyślnie po przetworzeniu żądań serwer wysyła pełną reprezentację zasobu docelowego. Częściowa odpowiedź umożliwia wysyłanie żądań tylko wybranych elementów lub atrybutów, a nie pełnego zasobu. Dzięki temu aplikacja kliencka nie musi przenosić, analizować ani przechowywać niepotrzebnych pól, co pozwala wydajniej wykorzystywać zasoby sieciowe, CPU i pamięć.

Aby dowiedzieć się, czy w przypadku używanej usługi jest dostępna odpowiedź częściowa, zapoznaj się z dokumentacją interfejsu API.

Aby zażądać częściowej odpowiedzi, użyj parametru zapytania fields, aby określić elementy lub atrybuty, które chcesz wyświetlić. Oto przykład:

http://www.example.com/feeds?fields=link,entry(@gd:etag,id,updated,link[@rel='edit']))

Odpowiedź serwera zawiera tylko elementy linku i wpisu dla pliku danych. Elementy wpisu zawierają tylko tag ETag, ID, zaktualizowany i edytuj link. Składnia parametrów zapytania fields jest opisana w poniższych sekcjach. Więcej informacji o odpowiedziach znajdziesz w artykule Obsługa częściowych odpowiedzi.

Uwaga: parametru zapytania fields możesz używać w każdym żądaniu zwrotu danych. Obejmują one nie tylko parametry GET, ale też POST i PUT (oraz PATCH, która służy do częściowych aktualizacji). Parametr zapytania fields wpływa jednak tylko na dane odpowiedzi. Nie ma wpływu na dane, które należy podać, ani na pola, które zostaną zaktualizowane lub utworzone.

Podsumowanie składni parametru Pola

Format wartości parametru zapytania fields jest oparty na składni XPath, obsługuje jednak tylko część prawidłowych wyrażeń XPath. Podsumowanie obsługiwanej składni znajdziesz poniżej, a dodatkowe przykłady znajdziesz w tej sekcji.

Aby wybrać kilka pól, użyj listy rozdzielonej przecinkami.
Użyj elementu a/b, aby wybrać element b zagnieżdżony w elemencie a. Użyj elementu a/b/c, aby wybrać element c umieszczony w elemencie b.
Użyj prefiksu '@', aby zidentyfikować atrybut o podanej nazwie. Pomiń prefiks '@', aby wskazać element.
Zastosuj warunki pól, aby wybrać elementy spełniające określone kryteria, umieszczając wyrażenia w nawiasach „[ ]” po elemencie, który chcesz ograniczyć.
Na przykład fields=entry[author/name='Elizabeth'] zwraca tylko wpisy w pliku danych, których autorem jest Elżbieta.
Określ selektory pól, aby żądały tylko określonych atrybutów lub elementów podrzędnych, umieszczając wyrażenia w nawiasach „( )” po dowolnym wybranym elemencie.
fields=entry(id,author/email) zwraca na przykład tylko identyfikator i adres e-mail autora każdego wpisu kanału.
Możesz ograniczyć ciągi znaków, używając cudzysłowów podwójnych lub pojedynczych.

Aby uniknąć podwójnego cudzysłowu, powtórz cudzysłów. Na przykład """Hello,"" he said" tworzy ciąg "Hello," he said, a '''Hello,'' he said' tworzy ciąg 'Hello,' he said.
W polach możesz używać symboli wieloznacznych.
Na przykład entry/gd:* wybiera wszystkie elementy podrzędne wpisu w przestrzeni nazw gd, a entry/@gd:* wybiera atrybuty podrzędne w tej samej przestrzeni nazw.

Parametr zapytania fields działa jak filtr wyjściowy. Oznacza to, że odpowiedź częściowa jest obliczana dopiero po przetworzeniu pozostałej części zapytania. Jeśli na przykład określisz parametr zapytania max-results wskazujący, że chcesz wygenerować 20 wyników na stronie, zostaną wygenerowane pierwsze 20 wyników, na podstawie których zostanie obliczona częściowa odpowiedź. Jeśli specyfikacja fields nie pasuje do żadnego z pierwszych 20 wpisów wybranych przez zapytanie, zwracasz pusty plik danych, ale nie zwracasz pierwszych 20 pasujących wpisów.

Uwaga: nie próbuj używać warunków pól do wyboru zapytań. Oznacza to, że nie próbuj pobierać całego pliku danych i stosuj warunki pól, aby odfiltrowywać interesujące Cię elementy z bardzo dużego zbioru danych. Gdy tylko jest to możliwe, używaj innych parametrów zapytania, takich jak start-index i max-results, aby ograniczyć wyniki każdego zapytania do rozmiaru, który ułatwia obsługę. W przeciwnym razie wzrost wydajności spowodowany częściową odpowiedzią może zrównoważyć pogorszenie wydajności spowodowane nieprawidłowym użyciem.

Formatowanie wartości parametru w polach

Z podanych niżej wskazówek dowiesz się, jak utworzyć wartość parametru zapytania fields. Każda wskazówka zawiera przykłady i opisuje, jak wartość parametru wpływa na odpowiedź.

Uwaga: tak jak każda wartość parametru zapytania, wartość parametru fields musi być zakodowana na potrzeby adresu URL. W celu zapewnienia czytelności w poniższych przykładach pominięto kodowanie.

Znajdź pola, które chcesz zwrócić, lub wybierz pola.

Wartość parametru zapytania fields to rozdzielona przecinkami lista elementów lub atrybutów (łącznie nazywanych polami). Każde pole jest określane względem elementu głównego reprezentacji zasobu. Oznacza to, że jeśli pobierasz plik danych, pola są określane względem elementu <feed>, a jeśli pobierasz pojedynczy wpis – pola są określane względem elementu <entry>. Jeśli wybrany element jest (lub jest częścią) elementu cyklicznego w pliku danych, usługa zwraca wszystkie jego wystąpienia.

Oto kilka przykładów na poziomie pliku danych:

Przykłady	Efekt
`entry`	Zwraca wszystkie elementy `<entry>` i ich elementy podrzędne, ale nie inne elementy podrzędne elementu `<feed>`.
`id,entry`	Zwraca zarówno plik danych `<id>`, jak i wszystkie elementy `<entry>`.
`entry/title`	Zwraca element `<title>` we wszystkich wpisach w pliku danych. Gdy zwracany jest zagnieżdżony element, odpowiedź zawiera tagi zamykające dla wszystkich elementów nadrzędnych . Tagi nadrzędne nie zawierają żadnych innych elementów podrzędnych ani atrybutów, chyba że zostaną wybrane wyraźnie.
`entry/author/uri`	Zwraca tylko podelement `<uri>` elementu `<author>` dla wszystkich wpisów w pliku danych.
`entry/*:rating`	Zwraca w przestrzeni nazw tylko elementy podrzędne o lokalnej nazwie `rating` we wszystkich wpisach w pliku danych.

Oto kilka przykładów:

Przykłady	Efekt
`author`	Zwraca element podrzędny `<author>` we wpisie docelowym.
`@gd:etag`	Zwraca atrybut `etag` wpisu docelowego.
`author/uri`	Zwraca podelement `<uri>` elementu `<author>` dla wpisu docelowego.
`media:group/media:*`	Zwraca wszystkie pola podrzędne pola `<media:group>` w przestrzeni nazw `media` dla wpisu docelowego.

Ogranicz odpowiedzi do wybranych pól, które spełniają określone kryteria, lub użyj warunków pól.

Domyślnie, jeśli żądanie określa element, który występuje więcej niż raz, odpowiedź częściowa będzie obejmować wszystkie wystąpienia tego elementu. Za pomocą składni „[ ]” możesz jednak określić, że odpowiedź powinna zawierać tylko elementy o konkretnej wartości atrybutu lub spełniające inne warunki, tak jak w przykładach poniżej. Więcej informacji znajdziesz w sekcji Składnia warunków pola.

Przykłady	Efekt
`entry[link/@rel='edit']`	Zwraca wszystkie wpisy w pliku danych, które zawierają element `<link>` z wartością atrybutu `rel` równą `'edit'`.
`entry/title[text()='Today']`	Zwraca wszystkie elementy `<title>`, które pojawiają się we wpisach w pliku danych, jeśli ich zawartość to `'Today'`.
`entry/author[name='Jo']`	Zwraca wszystkie elementy `<author>` występujące we wpisach w pliku danych, jeśli zawierają element podrzędny `<name>` z treścią `'Jo'`.
`author[name='Jo']`	Zwraca element `<author>` we wpisie docelowym, jeśli zawiera element podrzędny `<name>` z treścią `'Jo'`.

Poproś tylko o wybrane elementy lub użyj selektorów podrzędnych.

Domyślnie, jeśli żądanie określa określone elementy, usługa zwraca elementy w całości. Możesz określić, że odpowiedź powinna zawierać tylko niektóre elementy podrzędne z wybranych elementów. W tym celu użyj składni wyboru podrzędnego „( )”, jak pokazano w poniższych przykładach.

Przykłady	Efekt
`entry/author(uri)`	Zwraca tylko element podrzędny `<uri>` dla autorów we wpisach kanału.
`entry/author[name='Jo'](uri)`	Zwraca tylko podelement `<uri>` elementu `<author>` w przypadku wszystkich wpisów o nazwie autora `'Jo'`.
`entry(link(@rel,@href))`	Zwraca tylko wartości atrybutów `rel` i `href` dla każdego elementu `<link>` we wpisach pliku danych.
`entry(title,link[@rel='edit'])`	Zwraca tylko elementy `<title>` i `<link>`, które mają przypisane atrybuty `rel` do każdego wpisu w pliku danych.
`entry(title,author(uri)`	Zwraca zarówno elementy `<title>`, jak i elementy autora `<uri>`.

Więcej informacji o składni warunku pola

W warunkach możesz używać pól lub pól podrzędnych. Aby wybrane pole zostało uwzględnione w wynikach, warunek musi mieć wartość Prawda.Jeśli nie ma warunku pola, uwzględniane są wszystkie pola wybranego typu.

Wartość tekstowa wybranego pola jest używana do porównań. W tym kontekście, jeśli pole jest elementem, wartością tekstową jest jego zawartość. Jeśli pole jest atrybutem, wartością tekstową jest wartość atrybutu. Jeśli pole nie ma wartości tekstowej, porównanie się nie powiedzie, a pole nie zostanie uwzględnione w wynikach.

Poniższa tabela zawiera operatory XPath obsługiwane w warunkach pól i przykładowe przykłady.

Operator	Składnia	Przykłady
Porównanie ciągów znaków	`=` lub `eq` `!=` lub `ne`	Zwraca cały wpis, jeśli zawiera element `<link>` z atrybutem `rel` ustawionym na „`self'`”: `entry[link/@rel='self']` Zwraca cały wpis, jeśli zawiera element `<title>` z wartością równą `'unknown'`: `entry[title eq 'unknown']` Zwraca cały element `<title>`, jeśli jego zawartość to nie:`'unknown'` `title[text() != 'unknown']`
Porównanie logiczne	`and or not`	Zwraca wszystkie linki, które mają atrybut `rel` ustawiony na `'self'` lub `'edit'`: `link[@rel='self' or @rel='edit']` Zwraca wszystkie linki, które mają atrybut `rel` ustawiony na `'self'`, a atrybut `type` ustawiony na `'application/atom+xml'`: `link[@rel='self' and @type='application/atom+xml']` Zwraca wszystkie linki, które nie mają atrybutu `rel` o wartości `'self'`: `link[not(@rel='self')]` Pamiętaj, że tak jak w przypadku XPath, `not` wygląda jak wywołanie funkcji.
Porównanie liczbowe	`=` lub `eq` `!=` lub `ne` `>` lub `gt` `>`= lub `ge` `<` lub `lt` `<=` lub `le`	Zwraca dowolny element `<gd:rating>` z atrybutem `value`, który można przekształcić w liczbę całkowitą 5: `gd:rating[@value=5]` Zwraca dowolny element `<gd:rating>` z atrybutem `average`, który można przekształcić w element swobodny większy niż 4.3: `gd:rating[@average gt 4.3]`
Porównanie dat	Korzystaj z operatorów porównania liczbowego, tak jak w przykładach.	Aby przeprowadzić porównania dat lub dat i godzin, możesz przesyłać elementy, atrybuty lub literatury ciągów do `xs:date` lub `xs:dateTime`. W `xs:dateTime` domyślna strefa czasowa to UTC, ale najlepiej określić strefę czasową. Zwraca dowolny element `<yt:recorded>` zawierający datę od 1 stycznia 2005 r.: `yt:recorded[xs:date(text())>=xs:date('2005-01-01')]` Zwraca wszystkie wpisy, które zostały zaktualizowane po upływie czasu podanego w strefie czasowej UTC: `entry[xs:dateTime(updated)>xs:dateTime('2008-07-25T08:19:37.549Z')]`
Obecność	Użyj nazwy elementu lub atrybutu zgodnie z przykładami.	Zwraca wszystkie wpisy zawierające link z atrybutem `rel`: `entry[link/@rel]` Zwraca wszystkie elementy `<gd:rating>` z atrybutem `value`: `entry/gd:rating[@value]`
Wartość logiczna	`true()false()`	Wartość logiczna może być przydatna podczas testów, gdy chcesz wymusić spełnienie warunków pola do wartości prawda lub fałsz. Zwraca wszystkie elementy `<link>`: `link[true()]`

Radzenie sobie z odpowiedziami częściowymi

Gdy serwer, który obsługuje częściową odpowiedź, przetwarza prawidłowe żądanie zawierające parametr zapytania fields, wysyła kod stanu HTTP 200 OK wraz z żądanymi atrybutami lub elementami. Jeśli parametr zapytania fields zawiera błąd lub jest nieprawidłowy z innego powodu, serwer zwraca kod stanu HTTP 400 Bad Request.

Głównym elementem odpowiedzi jest <feed> lub <entry>, w zależności od docelowego identyfikatora URI. Zawartość elementu głównego obejmuje tylko wybrane pola pliku danych lub wpisy wraz z tagami zamykającymi dla elementów nadrzędnych.

Wartość parametru żądania fields można cofnąć na 2 sposoby:

Element główny ma atrybut gd:fields , który pokazuje wartość parametru zapytania fields określonego w żądaniu.
Jeśli docelowy identyfikator URI jest plikiem danych, każda możliwa do edytowania pozycja ma atrybut gd:fields, który pokazuje tylko część zaznaczonego pola fields.

Uwaga: aby zobaczyć wartości atrybutu gd:fields w odpowiedzi częściowej, musisz uwzględnić je w specyfikacji parametru zapytania fields. Możesz to zrobić za pomocą właściwości @gd:fields lub używając ogólniejszej metody @gd:*, która zawiera też informacje o tagu ETag.

Poniżej znajduje się przykład zapytania, które powoduje zwracanie przez serwer dokumentu zawierającego tylko atrybuty z przestrzeni nazw gd (na poziomie kanału i wpisu), a także identyfikatora, tytułu i linku edycji każdego wpisu w kanale:

http://example.com/myFeed?fields=@gd:*,id,entry(@gd:*,title,link[@rel='edit'])

Serwer zwraca tę częściową odpowiedź wraz z kodem stanu HTTP 200 Successful:

<?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/"DEAEQH47eCp7IWA9WxBVGUo."'
    gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])>
  <id>http://example.com/myFeed</id>
  <entry gd:etag='"EksPTg1Bfyp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/1/'/>
    <title>This year</title>
  </entry>
  <entry gd:etag='"EksPQA1Cdyp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/2/'/>
    <title>Last year</title>
  </entry>
  <entry d:etag='"EksPQAxHeCp7IWA6WhJT"'
      gd:fields="@gd:*,title,link[@rel='edit']">
    <link rel='edit' href='http://example.com/myFeed/3/'/>
    <title>Today</title>
  </entry>
</feed>

Jeśli wybrane pola nie pasują do siebie, usługa nadal zwraca kod stanu HTTP 200 Successful, ale odpowiedź częściowa to pusty plik danych:

<?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/"DEAEQH47eCp7IWA9WxBVGUo."'
  gd:fields='@gd:*,id,entry(@gd:*,title,link[@rel='edit'])>
</feed>

Częściowa aktualizacja (eksperymentalna)

Usługi Google, które obsługują częściową odpowiedź i materiały, które można edytować, umożliwiają korzystanie z częściowej aktualizacji. W przypadku częściowej aktualizacji wysyłasz tylko pola, które chcesz zaktualizować, zamiast zmodyfikowanej wersji pełnej reprezentacji zasobów. Pozwala to zwiększyć wydajność aplikacji klienckiej podczas aktualizowania oraz częściowej odpowiedzi na pobieranie danych.

Zamiast używać PUT, musisz jednak użyć żądania PATCH podczas częściowej aktualizacji. Znaczenie jest przydatne dla elementu PATCH, dzięki czemu możesz dodawać, zastępować i usuwać określone pola w przypadku konkretnego wpisu – wystarczy jedno żądanie.

Aby sprawdzić, czy dostępna jest częściowa aktualizacja usługi, której używasz, zapoznaj się z jej dokumentacją.

Przesyłanie częściowej prośby o aktualizację

Aby przesłać częściową prośbę o aktualizację, wyślij żądanie HTTP PATCH na ten sam adres URL, którego zwykle używasz w przypadku PUT. Treść żądania PATCH to częściowy element <entry> określający pola, które chcesz dodać lub zmodyfikować. Atrybut gd:fields wpisu wskazuje pola, które chcesz usunąć.

Serwer przetwarza żądania PATCH w określonej kolejności:

Najpierw usuwa się z zasobu reprezentującego pola określone w atrybucie gd:fields.
Składnia atrybutu gd:fields jest taka sama jak w parametrze zapytania fields używanym w żądaniu częściowej odpowiedzi. Więcej informacji znajdziesz w sekcji Obsługiwana składnia.
Następnie scala się z istniejącym zasobem reprezentującym dane podane w treści żądania.
Więcej informacji o scalaniu danych znajdziesz w sekcji Dodawanie i aktualizowanie pól poniżej.

Uwaga: treść żądania PATCH nie jest zwykle zgodna z formatem Atom Syndication Format, więc Content-Type, którego używasz z żądaniem PATCH, to application/xml.

Oto przykład żądania częściowej aktualizacji:

PATCH /myFeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='description'>
  <title>New title</title>
</entry>

To żądanie PATCH wprowadza następujące zmiany w reprezentacji zasobu przechowywanej na serwerze dla wpisu docelowego identyfikatora URI:

Usuwa element <description>.
Aktualizuje element <title>.

Semantyka częściowego żądania aktualizacji

Z instrukcji poniżej dowiesz się, jak skonfigurować żądanie PATCH dotyczące usunięcia, dodania lub zaktualizowania określonych pól we wpisie. Jedno żądanie PATCH może wykonać dowolną kombinację tych operacji.

Usuwanie pól. Użyj atrybutu gd:fields elementu <entry>, aby zidentyfikować pola, które chcesz usunąć z zasobu. Poniżej znajduje się przykład żądania usunięcia tytułu i podsumowania powiązanych z wpisem. Prośba nie powoduje jednak dodania ani aktualizacji innych danych dla danego wpisu.
```
PATCH /myfeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='title,summary'/>
```
Dodawanie lub aktualizowanie pól. W elemencie <entry> określ, jakie dane chcesz dodać lub zaktualizować. Pola te są scalane z dotychczasowymi danymi zasobu po usunięciu wszystkich informacji zgodnie z tymi regułami:
- Pola, które nie są jeszcze dodane, zostaną dodane. Jeśli dane zasobu nie podają wartości dla danego pola, pole zostanie dodane do istniejących danych. Jeśli na przykład wpis nie ma tytułu, a żądanie PATCH zawiera element <title>, do filmu zostanie dodany nowy tytuł.
- Pola, które już istnieją, są zastępowane lub dołączane. Konkretne działanie scalania pól określone już w danych zasobu zależy od jego właściwości:
  - Niepowtarzające się pola są zastępowane. Jeśli dane zasobu określają już wartość elementu niepowtarzającego się, wartość określona w żądaniu PATCH zastępuje istniejącą wartość tego elementu. Na przykład w poniższym przykładzie nowy tytuł zastępuje istniejący.
```
PATCH /myFeed/1/1/
Content-Type: application/xml

  <entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'>
  <title>New Title</title>
</entry>
```
    Bardziej złożony przykład znajdziesz poniżej. W tym przykładzie załóżmy, że wpis może mieć tylko jednego autora, a zasób docelowy ma już wartości imienia i nazwiska oraz adresu e-mail autora. Element <author> ma 2 pola podrzędne, ale w dostępnych danych występuje tylko element <name>. W rezultacie tylko wartość tego pola zostanie zastąpiona. Wartość elementu <email>, której nie ma w danych, pozostaje bez zmian.
```
PATCH /myfeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'>
  <author>
    <name>New Name</name>
  </author>
</entry>
```
  - Powtarzające się pola są dołączane. Jeśli dane zasobu określają już wartość elementu cyklicznego, podany przez Ciebie element jest dodawany do istniejącego zestawu wartości.
    
    Pamiętaj, że czasem możesz chcieć zrobić coś innego niż dodać nowe wystąpienie powtarzającego się elementu. Możesz na przykład wykonać jedną z tych czynności:
    - Zastąp całą listę powtarzających się elementów. Możesz usunąć wszystkie pola powtarzające się, używając atrybutu gd:fields (np. gd:fields='ns:accessControl') i przesłać pełny zestaw pól zastępczych. Wszystkie istniejące elementy są najpierw usuwane, więc zestaw podanych pól nie powoduje konfliktu z dołączonymi wartościami.
    - Zastąp 1 wartość w zestawie istniejących wartości elementu cyklicznego. W takim przypadku po prostu usuń pojedynczy element, określając wartość gd:fields na tyle wąsko, aby uniknąć usunięcia innych wartości, które chcesz zachować. Aby na przykład usunąć tylko kontrolę dostępu z wartością action embed, możesz użyć gd:fields='ns:accessControl[@action="embed"]'. Następnie musisz podać jedno pole, które chcesz zastąpić w treści elementu <entry>:
```
PATCH /myfeed/1/1/
Content-Type: application/xml

<entry xmlns='http://www.w3.org/2005/Atom'
    xmlns:gd='http://schemas.google.com/g/2005'
    gd:fields='ns:accessControl[@action="embed"]>
  <ns:accessControl action="embed" permission="allowed" />
</entry>
```

Przetwarzanie odpowiedzi na częściową aktualizację

Po przetworzeniu prawidłowego częściowego żądania aktualizacji interfejs API zwraca kod odpowiedzi HTTP 200 OK. Domyślnie treść odpowiedzi to pełny wpis zaktualizowany przez Ciebie. Serwer aktualizuje wartości ETag po przetworzeniu żądania PATCH tak samo jak w przypadku PUT.

Jeśli żądanie PATCH spowoduje nowy stan zasobu, który jest składniowo lub semantycznie nieprawidłowy, serwer zwraca kod stanu HTTP HTTP 400 Bad Request lub 422 Unprocessable Entity, a stan zasobu pozostaje bez zmian. Jeśli na przykład spróbujesz usunąć wymagane pole, ale nie zastąpisz go innym, serwer zwróci błąd.

Uwaga: pamiętaj, że musisz wiedzieć, jaki jest związek między poszczególnymi polami. Dodanie zasobu do stanu niespójności może być możliwe po zaktualizowaniu tylko części wspólnych ze sobą wartości. Na przykład czas rozpoczęcia może być późniejszy niż czas zakończenia. Chociaż interfejs API powinien zwracać kod błędu, zalecamy pełne przetestowanie tego rodzaju warunków, aby zapewnić spójność.

Tekst alternatywny, gdy technologia PATCH nie jest obsługiwana

Jeśli zapora sieciowa nie zezwala na PATCH, wykonaj żądanie HTTP POST i ustaw nagłówek zastępowania na PATCH, jak pokazano poniżej:

POST /myfeed/1/1/ X-HTTP-Method-Override: PATCH Content-Type: application/xml ...

Użycie częściowej odpowiedzi z częściową aktualizacją

Możesz użyć odpowiedzi częściowej jako podstawy do kolejnej prośby o częściową aktualizację. Jeśli tak jest, określ parametr zapytania fields zawierający linki do edycji, a także @gd:*. Dzięki temu częściowa odpowiedź zawiera takie informacje jak wartości atrybutów ETag i gd:fields, które są ważne w przypadku kolejnych żądań.

Oto przykład, który zwraca częściową odpowiedź, która może posłużyć jako podstawa do przyszłej częściowej aktualizacji:

http://example.com/myFeed/1/1/?fields=@gd:*,link[@rel='edit'](@href),gd:who

Serwer odpowiada:

<?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='"E0UKRAREeCp7IWA6WhJT"'
    gd:fields="@gd;*,link[@rel='edit'](@href),gd:who">
  <link href='http://example.com/myFeed/1/1/'/>
  <gd:who email='liz@gmail.com'/>
  <gd:who email='jo@gmail.com'/>
  <gd:who email='jane@gmail.com'/>
</entry>

Załóżmy, że chcesz usunąć użytkownika z adresem e-mail 'jane@gmail.com', dodać użytkownika z adresem e-mail 'will@gmail.com' i zmienić adres e-mail użytkownika wymienionego jako 'jo@gmail.com' na 'josy@gmail.com'.

Aby wprowadzić te zmiany, zacznij od wyników poprzedniej odpowiedzi, zmodyfikuj tylko te pola, które zawierają zmodyfikowane fragmenty, i prześlij zmodyfikowany części treści jako treść żądania PATCH. W tym przykładzie niezbędne modyfikacje są następujące:

Usuń pozycję <gd:who email='jane'/> z listy dostępnych elementów.
Dodaj <gd:who email='will@gmail.com'/> do listy dostępnych elementów.
Zastąp <gd:who email='jo@gmail.com'/> wartością <gd:who email='josy@gmail.com'/>.

Żądanie PATCH oparte na oczywistej odpowiedzi częściowej jest widoczne poniżej:

PATCH /myFeed/1/1/
Content-Type: application/xml

<entry gd:fields="@gd:*,link[@rel='edit'](@href),gd:who"
    gd:etag="FE8LQQJJeSp7IWA6WhVa">
  <link href='http://example.com/myFeed/1/1'/>
  <gd:who email='liz@gmail.com'/>
  <gd:who email='josy@gmail.com'/>
  <gd:who email='will@gmail.com'/>
</entry>

Uwaga: ta metoda zależy od atrybutów gd:fields i gd:etag (jeśli są obsługiwane) w częściowej odpowiedzi na wpis. Treść częściowego wpisu musi zawierać wszystkie pola i atrybuty, które znajdowały się w odpowiedzi częściowej – z wyjątkiem tych, które chcesz usunąć. Możesz zaktualizować dowolne pola w treści, dodając nowe wartości. Możesz też dodać dowolne pola, które chcesz dodać.

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 Google, powinien korzystać z specyficznego dla Google systemu uwierzytelniania o nazwie Account Authentication Proxy for Web-Based Applications (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) podczas wysyłania żądań do interfejsu Data API.

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 przy użyciu interfejsów API danych Google lub w dokumentacji uwierzytelniania 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 on nadal korzystać z interfejsów API danych, ale wydajność 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, PUT i DELETE
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
Sekcja ETag specyfikacji HTTP

Powrót do góry