Najczęstsze pytania

    Przegląd

  1. Co to jest interfejs Google Data API?
  2. Mam prośbę o dodanie funkcji lub zgłoszenie błędu. Gdzie mam publikować posty?
  3. Gdzie mogę zadać pytanie dotyczące konkretnego interfejsu API?
  4. Co to jest JSON?
  5. Czy muszę używać XML-a? Czy są dostępne inne formaty danych?
  6. Dlaczego używasz REST?
  7. Czy masz jakieś wskazówki lub krótkie przykłady kodu dotyczące typowych problemów?
  8. Czy Gmail ma interfejs Data API?

    9. Uwierzytelnianie

  9. Jaka jest nazwa usługi w ClientLogin dla każdego interfejsu Data API?
  10. Czy gdy użytkownik wyloguje się z aplikacji, konieczne jest poinformowanie o tym serwerów interfejsu API?
  11. Czy token uwierzytelniania ClientLogin ma datę ważności?
  12. Mam ogólne pytanie dotyczące kont Google. Dokąd mam się udać?
  13. Jak uwierzytelnić się w interfejsie API?
  14. Jaką wartość należy podać w parametrze zakresu AuthSub/OAuth 1?
  15. Czy istnieją różne typy tokenów AuthSub? Czy tokeny wygasają?
  16. Jaka jest główna różnica między ClientLogin a AuthSub/OAuth 1?
  17. Czy mogę używać uwierzytelniania ClientLogin w aplikacjach internetowych innych firm?
  18. Co to jest CAPTCHA?
  19. Jak wygenerować test CAPTCHA?
  20. Czy w aplikacji internetowej należy używać ClientLogin?
  21. Jak sprawdzić nazwę użytkownika podczas korzystania z AuthSub/OAuth 1?
  22. Jak używać OAuth 1 z bibliotekami klienta interfejsu Google Data API?
  23. Jak używać AuthSub z bibliotekami klienta interfejsu Google Data API?
  24. Jak używać ClientLogin z bibliotekami klienta interfejsu Google Data API?

    25. Biblioteki klienta

  25. W jakich językach programowania Google obsługuje biblioteki klienta?
  26. Jak zgłosić błąd lub przesłać prośbę o dodanie funkcji do jednej z bibliotek klienta Google Data?
  27. Jak włączyć opcje debugowania w bibliotekach klienta?
  28. Gdzie mogę znaleźć dokumenty referencyjne dotyczące klas biblioteki klienta?

    29. Rozwiązywanie problemów

  29. Jakie są dobre narzędzia do debugowania HTTP?
  30. Jak uzyskać informacje o rejestrowaniu HTTP w bibliotece klienta w języku Java?
  31. Jak uzyskać informacje o rejestrowaniu HTTP w bibliotece klienta .NET?
  32. Jak włączyć kodowanie gzip w plikach danych Google?
  33. Dlaczego podczas korzystania z klienta PHP widzę błąd „Unable to Connect to sslv2”?
  34. Jak uzyskać dokument usługi Atom, który opisuje plik danych?

Przegląd

Co to jest interfejs Google Data API?

Interfejs Google Data API to interfejs API oparty na protokole Google Data. Protokół danych Google jest oparty na formatach syndykacji Atom 1.0 i RSS 2.0 oraz na protokole publikowania Atom (APP).

Protokół danych Google rozszerza te standardy na różne sposoby, korzystając z mechanizmów rozszerzeń wbudowanych w te standardy. Kanały są zgodne z formatem dystrybucji Atom lub RSS. Model publikowania jest zgodny z protokołem publikowania Atom.

Protokół ten zawiera też ogólny model plików danych, zapytań i wyników. Możesz go używać do wysyłania zapytań i aktualizacji do dowolnego interfejsu Data API.

Chcę poprosić o dodanie funkcji lub zgłosić błąd. Gdzie mam opublikować post?
Sprawdź nasz tracker problemów. Znajdź swoją prośbę o funkcję i kliknij gwiazdkę, aby ją poprzeć i otrzymywać aktualizacje dotyczące jej stanu.
Gdzie mogę zadać pytanie dotyczące konkretnego interfejsu API?
Jeśli Twój problem nie jest wymieniony na liście lub potrzebujesz dodatkowych wyjaśnień, skorzystaj z grup dyskusyjnych poświęconych poszczególnym interfejsom Google Data API:
Co to jest JSON?

JSON to skrót od JavaScript Object Notation.

JSON to lekki format wymiany danych, którego prostota sprawiła, że jest powszechnie używany przez programistów stron internetowych. Jest łatwy do odczytania i zapisania. Możesz go analizować za pomocą dowolnego języka programowania, a jego struktury są bezpośrednio powiązane ze strukturami danych używanymi w większości języków programowania.

Dowiedz się więcej o używaniu formatu JSON w interfejsach Google Data API.

Czy muszę używać XML? Czy są dostępne inne formaty danych?
 Domyślnym formatem danych w interfejsach Google Data API jest XML w postaci pliku danych Atom. Podczas wysyłania żądania pliku danych możesz jednak określić alternatywny format za pomocą parametru zapytania alt.
  • alt=rss
    Dane odpowiedzi są sformatowane jako kanał RSS.
  • alt=json lub alt=json-in-script
     – zwraca reprezentację JSON struktury XML kanału Atom. Dodatkową zaletą formatu JSON jest to, że łatwiej go „przeanalizować” w kodzie klienta JavaScript. Obecnie korzystanie z JSON jest dostępne tylko w trybie tylko do odczytu. Jednak używanie biblioteki klienta JavaScript z usługami Blogger, Kontakty lub Kalendarz umożliwia zarówno odczytywanie, jak i zapisywanie danych.

    Dowiedz się więcej o wysyłaniu żądań dotyczących plików danych JSON i ich używaniu.

  • alt=atom-in-script
    Podobnie jak alt=json-in-script, ale wyniki są zwracane jako ciąg znaków XML kanału Atom, a nie JSON.
  • alt=rss-in-script
    Podobnie jak alt=atom-in-script, ale wyniki są zwracane jako ciąg znaków XML RSS, a nie Atom.

Więcej informacji o formatach alternatywnych znajdziesz w przewodniku po danych Google.

Dlaczego używasz REST?
REST jest prosty, lekki, skalowalny i bardzo dobrze nadaje się do reprezentowania i udostępniania danych.
Czy masz jakieś wskazówki lub krótkie przykłady kodu dotyczące typowych problemów?
Wskazówki dotyczące bibliotek klienta i wysyłania surowych żądań znajdziesz na blogu Google Data API Tips.
Czy Gmail ma interfejs Data API?

Nie, ale możesz użyć kanału Atom Gmaila z AuthSub lub OAuth 1, aby poprosić o dostęp tylko do odczytu nieprzeczytanych wiadomości użytkownika. Zakres powinien być ustawiony na https://mail.google.com/mail/feed/atom/. Przykładowe zapytanie:

GET https://mail.google.com/mail/feed/atom/

Jeśli chcesz zarządzać pocztą, Gmail obsługuje też protokoły IMAP/POP.

Uwierzytelnianie

W dokumentacji interfejsów Google Data API termin „OAuth” odnosi się do protokołu OAuth 1. Szczegółowe informacje o OAuth 2.0 znajdziesz w dokumentacji poszczególnych interfejsów API.

Jaka jest nazwa usługi w ClientLogin dla każdego interfejsu Data API?
„Nazwa usługi” to krótki ciąg znaków, którego system uwierzytelniania ClientLogin używa do identyfikowania usługi Google.
Interfejs API Google Nazwa usługi
Interfejsy Google Analytics Data API analytics
Interfejsy G Suite API
(informacje o domenach i zarządzanie nimi)		 apps
Google Sites Data API jotspot
Blogger Data API blogger
Book Search Data API print
Calendar Data API cl
Google Code Search Data API codesearch
Contacts Data API cp
Content API for Shopping structuredcontent
Documents List Data API writely
Finance Data API finance
Kanał Atom w Gmailu mail
Health Data API health
weaver (piaskownica H9)
Interfejsy API danych Map Google local
Picasa Web Albums Data API lh2
Sidewiki Data API annotateweb
Spreadsheets Data API wise
Webmaster Tools API sitemaps
YouTube Data API youtube

Więcej informacji o innych parametrach używanych w żądaniu ClientLogin znajdziesz w dokumentacji ClientLogin.

Czy gdy użytkownik wyloguje się z aplikacji, konieczne jest poinformowanie o tym serwerów interfejsu API?
Nie, nie musisz informować interfejsu Google Data API, gdy użytkownik wyloguje się z aplikacji. Jeśli jednak aplikacja nie potrzebuje już wydanego tokena AuthSub, powinna go unieważnić.
Czy token uwierzytelniania ClientLogin ma datę ważności?
Token ClientLogin może być ważny przez 2 tygodnie od daty wydania, ale ten limit zależy od usługi i może być krótszy.
Mam ogólne pytanie dotyczące kont Google. Gdzie mam się udać?
Odwiedź Centrum pomocy kont Google.
Jak uwierzytelnić się w interfejsie API?
Żądanie HTTP musi zawierać nagłówek Authorization, który zawiera token uzyskany za pomocą ClientLogin, AuthSub lub OAuth 1.
Jaką wartość należy podać w parametrze zakresu AuthSub/OAuth 1?
Parametr scope jest wymagany przez AuthSub i OAuth 1 do identyfikowania usług Google, do których Twoja aplikacja będzie mieć dostęp. Szczegółowe informacje o OAuth 2.0 znajdziesz w dokumentacji konkretnego interfejsu API.

Interfejs API Google Nazwa usługi ClientLogin
Google Analytics Data API https://www.google.com/analytics/feeds/
Google Sites Data API http(s)://sites.google.com/feeds/
Blogger Data API http://www.blogger.com/feeds/
Book Search Data API http://www.google.com/books/feeds/
Calendar Data API http(s)://www.google.com/calendar/feeds/
Contacts Data API http(s)://www.google.com/m8/feeds/
Content API for Shopping https://www.googleapis.com/auth/structuredcontent
Documents List Data API http(s)://docs.google.com/feeds/
Finance Data API http://finance.google.com/finance/feeds/
Kanał Atom w Gmailu https://mail.google.com/mail/feed/atom/
Health Data API https://www.google.com/health/feeds/
https://www.google.com/h9/feeds/ (piaskownica H9)
Interfejs Maps Data API http://maps.google.com/maps/feeds/
Picasa Web Albums Data API http://picasaweb.google.com/data/
Portable Contacts API http://www-opensocial.googleusercontent.com/api/people
Sidewiki Data API http://www.google.com/sidewiki/feeds/
Spreadsheets Data API http(s)://spreadsheets.google.com/feeds/
Webmaster Tools API http://www.google.com/webmasters/tools/feeds/
YouTube Data API http://gdata.youtube.com
Czy istnieją różne typy tokenów AuthSub? Czy tokeny wygasają?
Istnieją 2 typy tokenów AuthSub. Pierwszy to token jednorazowy, który jest przekazywany do aplikacji internetowej za pomocą parametru zapytania „token”. Ten token wygasa przy pierwszym użyciu w usłudze, dla której został wydany, lub po wymianie na token sesji.

Tokeny sesji nie tracą ważności, chyba że zostaną wyraźnie unieważnione przez użytkownika lub wywołanie interfejsu API AuthSubRevokeToken. Token jednorazowy można wymienić na token sesji tylko wtedy, gdy w oryginalnym adresie URL AuthSubRequest parametr zapytania session=1 został określony.
Jaka jest główna różnica między ClientLogin a AuthSub/OAuth 1?

AuthSub jest przeznaczony dla aplikacji internetowych. Dzięki temu dane logowania użytkownika są bezpiecznie przesyłane bezpośrednio z przeglądarki internetowej użytkownika na serwery Google, a nie przez witrynę innej firmy.

Uwierzytelnianie ClientLogin jest przeznaczone dla zainstalowanych aplikacji na komputery. Wymaga to od aplikacji wysyłającej żądanie przekazywania do Google danych logowania użytkownika w jego imieniu.

Zapoznaj się z dokumentacją interfejsu Google Account Authentication API.

Czy mogę używać uwierzytelniania ClientLogin w aplikacjach internetowych innych firm?
Korzystanie z ClientLogin w aplikacjach internetowych innych firm jest dopuszczalne, ale zdecydowanie odradzamy takie rozwiązanie. Zgodnie z zasadami bezpieczeństwa aplikacja internetowa nigdy nie powinna prosić użytkownika o dane logowania (może to być podatne na szpiegowanie). Zamiast tego aplikacja powinna przechowywać dane logowania użytkownika po stronie serwera i mieć jedno „konto usługi”, które jest zawsze używane do uwierzytelniania w Google.
Co to jest CAPTCHA?
CAPTCHA (Completely Automated Public Turing test to tell Computers and Humans Apart) to rodzaj testu typu wywołanie – reakcja, który służy do określania, czy użytkownik jest człowiekiem. Termin ten jest chroniony znakiem towarowym należącym do Carnegie Mellon University. Więcej informacji znajdziesz w Wikipedii. Wdrożyliśmy CAPTCHA w usłudze ClientLogin.
Jak wygenerować test CAPTCHA?
Podczas uwierzytelniania używany jest algorytm własnościowy, który określa, kiedy wymagane jest rozwiązanie CAPTCHA. Wielokrotne próby uwierzytelnienia z nieprawidłowymi danymi logowania często powodują wyświetlenie zadania CAPTCHA.
Czy w aplikacji internetowej należy używać ClientLogin?
Nie. ClientLogin powinny używać aplikacje zainstalowane na sprzęcie należącym do użytkownika. Używanie interfejsu ClientLogin API w aplikacjach internetowych jest niebezpieczne i zdecydowanie odradzane.
Jak mogę sprawdzić nazwę użytkownika podczas korzystania z AuthSub/OAuth 1?
Otrzymujesz od Google tylko token, który przyznaje dostęp do plików danych użytkownika, więc możesz nie znać jego nazwy użytkownika. Może to stanowić problem, jeśli adres URL pliku danych, którego chcesz użyć, zawiera nazwę użytkownika. W takim przypadku możesz użyć specjalnej nazwy użytkownika default, która oznacza „użytkownika, którego tokenu uwierzytelniania używam”.
Jak używać OAuth 1 z bibliotekami klienta interfejsu Google Data API?
Zapoznaj się z artykułem Używanie OAuth 1 z bibliotekami klienta interfejsu Google Data API.
Jak używać AuthSub z bibliotekami klienta interfejsu Google Data API?
Zapoznaj się z artykułem Korzystanie z AuthSub w bibliotekach klienta interfejsu Google Data API.
Jak używać ClientLogin z bibliotekami klienta interfejsu Google Data API?
Zapoznaj się z artykułem Korzystanie z ClientLogin w bibliotekach klienta interfejsu Google Data API.

Biblioteki klienta

W jakich językach programowania Google obsługuje biblioteki klienta?

Biblioteki klienta Java, .NET, Python i Objective-C są oficjalnie obsługiwane przez Google. Dodatkowo nasz partner Zend napisał bibliotekę klienta PHP. Za pomocą tych bibliotek możesz tworzyć żądania protokołu danych Google, wysyłać je do usługi i przetwarzać odpowiedzi serwera. Dostępna jest też biblioteka klienta JavaScript, która obecnie obsługuje tylko Bloggera, Kalendarz i Kontakty Google.

Jeśli napiszesz bibliotekę klienta w języku innym niż Java, .Net, Python lub Objective-C i chcesz się nią podzielić ze społecznością programistów interfejsów API danych Google, opublikuj ją w grupie dyskusyjnej interfejsów API danych Google. Chętnie poznamy Twoją opinię.

Jak zgłosić błąd lub przesłać prośbę o dodanie funkcji w przypadku jednej z bibliotek klienta?

Błędy lub prośby o dodanie funkcji w bibliotekach klienta można zgłaszać w tych miejscach:

Po opublikowaniu błędu utwórz wątek na forum dla deweloperów odpowiedniego interfejsu API.

Jak włączyć opcje debugowania w bibliotekach klienta interfejsu Google Data API?
Informacje o włączaniu debugowania w przypadku niektórych bibliotek klienta znajdziesz w tym artykule: Debugowanie klientów interfejsu Google Data API: sprawdzanie ruchu w programie
Gdzie znajdę dokumenty referencyjne dotyczące klas biblioteki klienta?
Biblioteka klienta Przewodnik informacyjny
Java Javadoc
JavaScript JSdoc
.NET NDoc
PHP phpDoc
Python PyDoc

Rozwiązywanie problemów

Jakie są dobre narzędzia do debugowania HTTP?

Poniżej znajdziesz listę narzędzi, ale możesz też przeczytać artykuł On the Wire: Network Capture Tools for API Developers (W sieci: narzędzia do przechwytywania sieci dla programistów API), w którym szczegółowo opisano przykłady użycia narzędzi WireShark i Fiddler.

Wireshark
Wireshark to „analizator protokołów sieciowych”. Umożliwia przechwytywanie ruchu w sieci i analizowanie jego zawartości. Jest to bardzo przydatne podczas debugowania ruchu w bibliotekach, w których nie masz bezpośredniego dostępu do strumieni żądań i odpowiedzi HTTP. Ruch między aplikacją a usługami uwierzytelniania nie może być analizowany za pomocą narzędzia Wireshark, ponieważ komunikacja jest szyfrowana za pomocą protokołu SSL. Wireshark może też służyć do analizowania ruchu przechwyconego za pomocą narzędzi takich jak tcpdump. Wireshark jest dostępny u deweloperów zarówno jako kod źródłowy, jak i instalator dla systemu Windows. Pakiety innych firm są dostępne na wielu platformach.
Fiddler
Fiddler to „serwer proxy do debugowania HTTP”. Jeśli możesz skonfigurować kod lub środowisko wykonawcze, aby używać serwera proxy do obsługi ruchu HTTP, Fiddler będzie znajdować się między Twoją aplikacją a usługami danych Google, co umożliwi Ci sprawdzanie ruchu. Fiddler 2 obsługuje SSL. Fiddler jest obecnie dostępny tylko w systemie Windows.
cURL
cURL to narzędzie wiersza poleceń, które może wysyłać żądania HTTP/HTTPS. Jest to bardzo przydatne do szybkiego testowania interakcji z usługą bez konieczności wcześniejszego tworzenia obsługi HTTP w aplikacji klienckiej.
Jak uzyskać informacje o rejestrowaniu HTTP w bibliotece klienta w języku Java?

Biblioteki klienta Java używają pakietu java.util.logging, aby włączyć rejestrowanie żądań HTTP. Umożliwi to włączenie rejestrowania nagłówków żądań i odpowiedzi, a także kodów stanu i adresów URL żądań. Obecnie nie rejestruje pełnych strumieni żądań i odpowiedzi. Nazwa rejestratora używana w przypadku tych logów to com.google.gdata.client.http.HttpGDataRequest.

Jeśli serwery zwrócą kod błędu, zostanie zgłoszony wyjątek. Klasy wyjątków dziedziczą po klasie com.google.gdata.util.ServiceException i zawierają publiczną metodę o nazwie getResponseBody(). Więcej informacji znajdziesz w Javadoc.

Jak uzyskać informacje o rejestrowaniu HTTP w bibliotece klienta .NET?
Biblioteka .NET używa metod śledzenia System.Diagnostics do rejestrowania ścieżki wykonania, jeśli śledzenie jest włączone. W przypadku błędu zgłaszany jest wyjątek GDataRequestException. Wyjątek zawiera ResponseString, które umożliwia dostęp do treści odpowiedzi HTTP.
Jak włączyć kodowanie gzip w plikach danych Google?

Aby odebrać odpowiedź zakodowaną w formacie gzip z jednego z interfejsów Google Data API, musisz wykonać 2 czynności: ustawić nagłówek „Accept-Encoding” i zmodyfikować klienta użytkownika, aby zawierał ciąg znaków „gzip”. Przykład prawidłowo sformułowanych nagłówków:

User-Agent: my program (gzip)
Accept-Encoding: gzip
Dlaczego podczas korzystania z klienta PHP pojawia się błąd „Unable to Connect to sslv2”?

W lipcu 2009 r. zaczęliśmy wyłączać protokół SSLv2 na naszych serwerach jako środek ostrożności mający na celu poprawę bezpieczeństwa. W wcześniejszych wersjach biblioteki klienta PHP wydanych przed lipcem 2007 roku (wersja 1.0.0 i starsze) występuje błąd, który wymusza używanie protokołu SSLv2. Podczas łączenia się z serwerem, na którym protokół SSLv2 jest wyłączony, pojawia się ten błąd:

PHP Fatal error:  Uncaught exception 'Zend_Http_Client_Adapter_Exception' with message 'Unable to Connect to sslv2://www.google.com:443.'

Aby naprawić ten błąd, przejdź na nowszą wersję biblioteki klienta PHP, która jest dostępna na stronie http://framework.zend.com/download.

Jeśli nie możesz przejść na nowszą wersję, możesz rozwiązać ten problem, dodając do aplikacji ten kod, gdzie $gdata to istniejąca instancja Zend_Gdata (lub odpowiedniej klasy podrzędnej):

$gdata->getHttpClient()->setConfig(array('ssltransport' => 'ssl'));
Jak uzyskać dokument usługi Atom opisujący plik danych?

Dokument usługi Atom możesz uzyskać, przekazując w żądaniu parametr alt=atom-service. Uwaga: tylko wersja 2 interfejsów Google Data API zwraca dokument usługi zgodny ze składnią dokumentu usługi AtomPub. Interfejs API danych Google w wersji 1 nadal będzie zwracać dokument usługi, ale będzie on oparty na wcześniejszej wersji roboczej specyfikacji AtomPub (w obu wersjach występują zmiany w składni i przestrzeni nazw).