Przewodnik dla programistów

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.

Misją firmy Google jest porządkowanie światowych zasobów informacji, aby były one powszechnie dostępne i użyteczne. Obejmuje to udostępnianie informacji w kontekstach innych niż przeglądarki oraz korzystanie z usług spoza Google.

Protokół Google do obsługi danych zapewnia deweloperom zewnętrznym bezpieczny zapis nowych aplikacji, które pozwalają użytkownikom na dostęp do danych przechowywanych w wielu usługach Google. Zewnętrzni programiści mogą bezpośrednio korzystać z protokołu danych Google lub dowolnego języka programowania obsługiwanego w bibliotekach klienta.

Odbiorcy

Ten zestaw dokumentów jest przeznaczony dla wszystkich, którzy chcą zrozumieć protokół danych Google. Nawet jeśli chcesz napisać kod, który korzysta z bibliotek klienta danego języka, ten zestaw dokumentów może być przydatny, gdy chcesz sprawdzić, co się dzieje pod warstwą abstrakcji biblioteki.

Jeśli szukasz przewodnika dotyczącego konkretnego interfejsu API, odwiedź katalog API protokołu danych Google.

Jeśli chcesz mieć dostęp do interfejsu API w swoim ulubionym języku programowania, odwiedź stronę pobierania bibliotek klienta.

Wprowadzenie

Wiele usług Google, takich jak Kalendarz czy Arkusze, zapewnia interfejsy API oparte na protokole Google Data Protocol. Jako deweloper może za pomocą tych interfejsów API tworzyć aplikacje klienckie, które zapewniają użytkownikom nowe sposoby uzyskiwania dostępu do danych przechowywanych w tych usługach Google oraz manipulowania nimi.

Uwaga: usługi Google, które udostępniają interfejsy API, są czasami określane jako usługi w tych i innych powiązanych dokumentach.

Jeśli napiszesz kod, który korzysta bezpośrednio z protokołu danych Google, uzyska on dostęp do interfejsu API za pomocą żądań HTTP, takich jak GET lub POST. Żądania te są przechowywane w tej usłudze w formie plików danych. Pliki danych to po prostu listy uporządkowane zawierające dane. W przeszłości podstawowy format pliku danych był do AtomPub XML, ale teraz JSON, czyli JavaScript Object Notation, jest też dostępny jako format alternatywny.

Jeśli nie chcesz pisać kodu, który bezpośrednio wysyła żądania HTTP, możesz zaprogramować aplikację kliencką w jednym z języków programowania dostępnych w zestawie bibliotek klienta. Gdy to zrobisz, szczegóły żądań HTTP będą obsługiwane przez bibliotekę klienta. Kod musisz napisać na poziomie koncepcyjnym, korzystając z metod i klas właściwych dla języka dostępnych w bibliotece klienta.

Więcej informacji o konkretnych językach dostępnych w używanym przez Ciebie API lub jego wersji znajdziesz w dokumentacji konkretnego produktu.

Wersje protokołu

Protokół w wersji 2.0 a protokół 1.0

Pierwsza wersja protokołu Google Data Protocol została opracowana przed utworzeniem protokołu Atom Publishing Protocol. Druga wersja protokołu Google Data Protocol jest w pełni zgodna ze standardem AtomPub RFC 5023.

Wersja 2.0 protokołu Google Data Protocol obsługuje też:

  • Tagi ETag HTTP. Standard sieciowy, który pomaga aplikacjom klienckim lepiej wykorzystywać pamięć podręczną HTTP. Usługi zawarte w bibliotekach klienckich, które obsługują protokół w wersji 2.0, obsługują tagi ETag.
  • Odpowiedź częściowa i Częściowa aktualizacja (funkcja eksperymentalna). Funkcje, które pozwalają przesyłać żądania mniej danych. Żądanie tylko tych informacji, których potrzebujesz, lub wysyłanie aktualizacji zawierających tylko te dane, które naprawdę chcesz zmienić, może znacznie efektywniej korzystać z zasobów sieciowych, procesora i pamięci. Obecnie częściowa odpowiedź i częściowa aktualizacja są dostępne tylko w przypadku niektórych usług. Aby dowiedzieć się, czy Twój interfejs API obsługuje, zapoznaj się z dokumentacją tej usługi.

Aktualizowanie aplikacji

Jeśli korzystasz z interfejsu API, który został utworzony na podstawie najnowszej wersji protokołu, w jego dokumentacji znajdziesz opis protokołu w wersji 2.0. Ogólnie zalecamy uaktualnienie aplikacji klienckiej do najnowszej wersji dostępnej dla interfejsu API.

Aktualizowanie klienta opartego na bibliotece

Jeśli aplikacja kliencka używa biblioteki klienta, takiej jak biblioteka klienta w języku Java lub biblioteka klienta .NET, może zawierać wersję interfejsu API, która obsługuje funkcje protokołu w wersji 2.0. Aby się tego dowiedzieć, zapoznaj się z dokumentacją interfejsu API usługi Google, której używasz, aby sprawdzić, czy spełnione są oba te warunki:

  • Istnieje wersja interfejsu API, która obsługuje funkcje Google Data Protocol v2.0.
  • Biblioteka klienta, której używasz, obsługuje też tę wersję API.

Jeśli biblioteka klienta obsługuje tę bibliotekę i chcesz zaktualizować dotychczasową aplikację, wystarczy pobrać i użyć najnowszej wersji biblioteki klienta. Cały kod nadal działa, a biblioteka klienta obsługuje zmiany protokołu v2.0.

Aktualizowanie nieprzetworzonego klienta HTTP

Jeśli aplikacja kliencka została napisana bezpośrednio przy użyciu protokołu Google Data Protocol, musisz wprowadzić te zmiany:

  • Żądania wersji innych niż domyślne. Dodaj nagłówek wersji HTTP (GData-Version: X.0) do każdego wysyłanego żądania HTTP, gdzie X to wersja interfejsu API obsługującego funkcje Google Data Protocol v2.0. Możesz też dodać parametr zapytania (v=X.0) do adresu URL każdego żądania, gdzie X to ponownie prawidłowa wersja interfejsu API. Jeśli nie określisz później wersji, Twoje żądania będą domyślnie wysyłane do najwcześniejszej obsługiwanej wersji interfejsu API.
  • Równoczesna optymalizacja. Jeśli używasz wersji interfejsu API, która obsługuje równoczesne optymalizacje, konieczne może być zaktualizowanie aktualizacji i usunięcie kodu, aby używać ETagów. Aby uzyskać więcej informacji, zapoznaj się z sekcją ETags w dokumentacji referencyjnej Google Data Protocol oraz zapoznaj się z sekcjami „Update and Delete” (Aktualizowanie i usuwanie) w przewodniku dla programistów dotyczącym usługi, z której korzysta aplikacja kliencka.
  • Możesz podać lub edytować identyfikatory URI. Jeśli klient śledzi siebie lub edytuje identyfikatory URI kanałów lub wpisów, pamiętaj, że te identyfikatory mogły się zmienić. Aby uzyskać nowy identyfikator URI, prześlij żądanie ponownie za pomocą starego identyfikatora URI, ale oznacz żądanie jako wersję X.0, gdzie X to wersja interfejsu API obsługującego funkcje Google Data Protocol v2.0. Serwer zwraca nową reprezentację wpisu, w tym nowe identyfikatory URI, które można przechowywać zamiast starych.
  • Identyfikatory URI przestrzeni nazw. Jeśli Twój klient przechowuje lokalnie identyfikatory URI przestrzeni nazw interfejsu Google Data Protocol API lub zakodowano je na stałe, musisz je zaktualizować:
    • Przestrzeń nazw AtomPub (prefiks app) została zmieniona z http://purl.org/atom/app na http://www.w3.org/2007/app.
    • Przestrzeń nazw OpenSearch (prefiks openSearch) została zmieniona z http://a9.com/-/spec/opensearchrss/1.0/ na http://a9.com/-/spec/opensearch/1.1/.