Interfejs API danych Bloggera pozwala aplikacjom klienckim wyświetlać i aktualizować treści z Bloggera w postaci kanałów interfejsu API danych Google.
Aplikacja kliencka Bloggera może używać interfejsu API danych Bloggera do tworzenia nowych postów na blogu, edytowania i usuwania istniejących postów, a także wysyłania zapytań o posty spełniające określone kryteria.
Poza informacjami o możliwościach interfejsu Blogger Data API w tym dokumencie przedstawiamy przykłady podstawowych interakcji interfejsu Data API z wykorzystaniem biblioteki klienta JavaScript. Jeśli chcesz dowiedzieć się więcej o podstawowym protokole używanym w bibliotece, zapoznaj się z sekcją Protokół w tym przewodniku dla programistów.
Spis treści
Odbiorcy
Ten dokument jest przeznaczony dla programistów chcących pisać klienckie aplikacje JavaScript umożliwiające interakcję z Bloggerem. Przedstawiamy w nim serię przykładów podstawowych interakcji interfejsu Data API z wykorzystaniem biblioteki klienta JavaScript.
Informacje referencyjne na temat interfejsu API danych Bloggera znajdziesz w Przewodniku po protokole. W tym dokumencie zakładamy, że rozumiesz ogólne koncepcje protokołu interfejsów API danych Google oraz model danych i przepływ kontroli, używane przez bibliotekę klienta JavaScript. Zakładamy również, że umiesz programować w języku JavaScript.
Informacje o klasach i metodach udostępnianych przez bibliotekę klienta znajdziesz w dokumentacji interfejsu API biblioteki klienta JavaScript.
Tę dokumentację należy czytać po kolei, a każdy z nich opiera się na wcześniejszych przykładach.
Warunki korzystania z usługi
Korzystając z biblioteki klienta JavaScript, zgadzasz się przestrzegać Warunków korzystania z biblioteki klienta JavaScript Google.
Informacje o obsługiwanych środowiskach
Obecnie obsługujemy tylko aplikacje klienckie JavaScript, które działają na stronie internetowej w przeglądarce. Obecnie obsługiwane przeglądarki to Firefox w wersji 1.5 i nowszych oraz Internet Explorer w wersji 6.0 lub nowszej.
Biblioteka klienta JavaScript obsługuje całą komunikację z serwerem usługi. Jeśli jesteś doświadczonym programistą JS, możesz się zastanawiać „Ale co z zasadami dotyczącymi tego samego źródła?”. Biblioteka klienta JavaScript pozwala klientowi wysyłać żądania do interfejsu Google Data API z dowolnej domeny, zachowując przy tym zgodność z modelem zabezpieczeń przeglądarki.
Pierwsze kroki
Zanim napiszesz aplikację kliencką JavaScript, musisz skonfigurować pobieranie biblioteki.
Tworzenie konta w Bloggerze
Aby przeprowadzić testy, możesz założyć konto Bloggera. Blogger korzysta z kont Google, więc jeśli już masz konto Google, nie musisz nic robić.
Szukanie biblioteki
Aby klient mógł korzystać z biblioteki klienta, musi wysłać do serwera żądanie o jego kod.
Zacznij od użycia tagu <script> w sekcji <head> dokumentu HTML, aby pobrać moduł wczytywania interfejsu API Google AJAX:
<script type="text/javascript" src="https://www.google.com/jsapi"></script>
Aby pobrać bibliotekę klienta Google Data API po pobraniu modułu ładującego, użyj następującego wiersza w kodzie konfiguracji JavaScript, który musi zostać wywołany z sekcji <head> dokumentu HTML (lub z pliku JavaScript umieszczonego za pomocą tagu <script> w sekcji <head> dokumentu HTML):
google.load("gdata", "1.x");
Drugi parametr google.load() to żądany numer wersji biblioteki klienta JavaScript.Nasz schemat numerowania wersji jest modelowany na podstawie schematu używanego w interfejsie API Map Google. Oto możliwe numery wersji i ich znaczenie:
"1"- Druga do ostatniej wersji głównej wersji 1.
"1.x"- Najnowsza wersja głównej wersji 1.
"1.s"- Najnowsza stabilna wersja głównej wersji 1. Na podstawie opinii otrzymywanych od deweloperów od czasu do czasu będziemy deklarować jakąś wersję biblioteki klienta jako „stabilną”. Może ona jednak nie mieć najnowszych funkcji.
"1.0","1.1" itp.- Konkretna wersja biblioteki o określonym numerze wersji głównej i drobnej.
Po wywołaniu google.load() musisz nakazać programowi ładującemu, by czekał na zakończenie wczytywania strony, a potem wywołać Twój kod:
google.setOnLoadCallback(getMyBlogFeed);
Gdzie getMyBlogFeed() to funkcja, którą zdefiniujemy w dalszej sekcji tego dokumentu. Użyj tej metody zamiast modułu obsługi onload dołączonego do elementu <body>.
Uwierzytelnianie w usłudze Blogger
Interfejs API danych Bloggera umożliwia dostęp zarówno do publicznych, jak i prywatnych kanałów. Publiczne kanały nie wymagają uwierzytelniania, ale są tylko do odczytu. Jeśli chcesz zmodyfikować blogi, Twój klient musi się uwierzytelnić przed wysłaniem prośby o dostęp do kanałów prywatnych.
Biblioteka klienta JavaScript korzysta z systemu uwierzytelniania AuthSub. Więcej ogólnych informacji o uwierzytelnianiu za pomocą interfejsów API danych Google znajdziesz w dokumentacji uwierzytelniania.
Uwierzytelnianie serwera proxy AuthSub
Uwierzytelnianie serwera proxy AuthSub jest używane przez aplikacje internetowe, które muszą uwierzytelniać użytkowników na kontach Google. Operator witryny i kod klienta nie mają dostępu do nazwy użytkownika i hasła Bloggera. Zamiast tego klient uzyskuje specjalne tokeny AuthSub, które umożliwiają klientowi działanie w imieniu konkretnego użytkownika.
Oto krótkie omówienie tego, co dzieje się podczas uwierzytelniania w przypadku internetowego klienta JavaScript:
- Aplikacja kliencka wywołuje metodę
google.accounts.user.login()podaną przez bibliotekę klienta, przekazując do niej wartość „zakres” wskazującą, której usługi Google należy użyć. W przypadku Bloggera zakres to"http://www.blogger.com/feeds/". - Biblioteka klienta wysyła przeglądarkę na stronę „Żądanie dostępu” Google, na której użytkownik może wpisać swoje dane logowania, aby zalogować się w usłudze.
- Jeśli użytkownik zaloguje się poprawnie, system AuthSub wyśle przeglądarkę z powrotem do adresu URL klienta internetowego, przekazując token uwierzytelniania.
- Biblioteka klienta JavaScript zapisuje token w pliku cookie i zwraca kontrolę do funkcji aplikacji klienckiej o nazwie
google.accounts.user.login(). - Gdy aplikacja kliencka następnie wywołuje metody biblioteki klienta, które wchodzą w interakcję z Bloggerem, biblioteka klienta automatycznie dołącza token do wszystkich żądań.
Uwaga: aby biblioteka klienta JavaScript mogła wysyłać uwierzytelnione żądania Bloggera w przeglądarce, strona musi zawierać obraz hostowany w tej samej domenie co Twoja strona. Może to być dowolny obraz, nawet przezroczysty obraz, ale na stronie musi być jakiś obraz. Jeśli nie chcesz, by obraz pojawiał się na Twojej stronie, możesz użyć atrybutu style tagu <img>, by umieścić go poza obszarem renderowania. Przykład: style="position:absolute; top:
-1000px;"
Oto kod aplikacji klienckiej, który obsługuje logowanie. Wywołaj później funkcję setupMyService() z innego kodu.
function logMeIn() {
scope = "http://www.blogger.com/feeds/";
var token = google.accounts.user.login(scope);
}
function setupMyService() {
var myService =
new google.gdata.blogger.BloggerService('exampleCo-exampleApp-1');
logMeIn();
return myService;
}
Wskazówka: zdecydowanie zalecamy udostępnienie przycisku logowania lub innego mechanizmu wprowadzania danych użytkownika, który umożliwi mu ręczne rozpoczęcie procesu logowania. Jeśli zamiast tego wywołasz google.accounts.user.login() natychmiast po wczytaniu, bez oczekiwania na interakcję użytkownika, pierwszą rzeczą, którą zobaczy po przejściu na Twoją stronę, będzie strona logowania Google. Jeśli użytkownik nie chce się logować, Google nie kieruje go z powrotem na Twoją stronę, więc z jego punktu widzenia próbował on wejść na Twoją stronę, ale został odesłany i nigdy nie został odesłany. Taki scenariusz może być mylący i frustrujący dla użytkowników. W przykładowym kodzie w tym dokumencie natychmiast po załadowaniu będziemy wywoływać funkcję google.accounts.user.login(), by przykład był prosty. Nie zalecamy jednak takiego podejścia w przypadku rzeczywistych aplikacji klienckich.
Ze zmienną o nazwie token nie musisz nic robić. Biblioteka klienta śledzi token, więc Ty nie musisz tego robić.
Uwaga: gdy tworzysz nowy obiekt BloggerService, biblioteka klienta wywołuje metodę o nazwie google.gdata.client.init(), która sprawdza, czy przeglądarka, w której działa klient, jest obsługiwana. Jeśli wystąpi błąd, biblioteka klienta
wyświetli użytkownikowi komunikat o błędzie. Jeśli chcesz samodzielnie naprawić tego typu błędy, możesz jawnie wywołać funkcję google.gdata.client.init(handleInitError) przed utworzeniem usługi, gdzie handleInitError() to Twoja funkcja. Jeśli wystąpi błąd inicjowania, funkcja otrzyma standardowy obiekt Error. Możesz zrobić z nim cokolwiek chcesz.
Token pozostanie ważny, dopóki go nie unieważnisz, wywołując google.accounts.user.logout():
function logMeOut() {
google.accounts.user.logout();
}
Jeśli nie wywołasz logout(), plik cookie, w którym jest przechowywany token, będzie działać przez 2 lata, chyba że użytkownik go usunie. Plik cookie jest zapisywany w różnych sesjach przeglądarki, więc użytkownik może zamknąć przeglądarkę, a następnie ponownie ją otworzyć, a potem wrócić do klienta i nadal być zalogowany.
Istnieją jednak pewne nietypowe okoliczności, w których token może stać się nieprawidłowy podczas sesji. Jeśli Blogger odrzuci token, klient powinien obsłużyć stan błędu, wywołując funkcję logout() w celu usunięcia pliku cookie zawierającego bieżący token, a następnie ponownie wywołując login() w celu uzyskania nowego, prawidłowego tokena.
Istnieją 2 inne metody AuthSub, które mogą okazać się przydatne w różnych kontekstach:
google.accounts.user.checkLogin(scope)informuje, czy przeglądarka ma obecnie token uwierzytelniania dla danego zakresu.google.accounts.user.getInfo()udostępnia szczegółowe informacje o bieżącym tokenie do użycia podczas debugowania.
Szczegółowe informacje o używaniu JavaScriptu do interakcji z AuthSub, w tym informacje o zarządzaniu tokenami oraz checkLogin() i getInfo(), znajdziesz w dokumencie Using „AuthSub” Authentication with the JavaScript Client Library (Używanie uwierzytelniania „AuthSub” w bibliotece klienta JavaScript).