Przewodnik dla programistów: Java

Ważne: to jest starsza wersja tej strony. Aby pobrać najnowszą wersję, użyj linków w pasku nawigacyjnym po lewej stronie.

Interfejs Blogger Data API umożliwia aplikacjom klienckim wyświetlanie i aktualizowanie treści Bloggera w postaci plików danych Google Data API.

Za pomocą interfejsu Blogger Data API aplikacja klienta może tworzyć nowe posty na blogu, edytować i usuwać istniejące posty oraz wysyłać zapytania o posty spełniające określone kryteria.

Ten dokument zawiera informacje o możliwościach interfejsu Data API w Bloggerze oraz przykłady podstawowych interakcji z interfejsem Data API za pomocą biblioteki klienta w języku Java. Jeśli chcesz dowiedzieć się więcej o podstawowym protokole używanym przez bibliotekę, zapoznaj się z sekcją dotyczącą protokołu w tym przewodniku dla deweloperów.

Spis treści

  1. Odbiorcy
  2. Pierwsze kroki
    1. Tworzenie konta w Bloggerze
    2. Uruchamianie przykładowego kodu
  3. Uwierzytelnianie w usłudze Blogger
    1. Uwierzytelnianie proxy AuthSub
    2. Uwierzytelnianie za pomocą nazwy użytkownika i hasła w ClientLogin
  4. Pobieranie listy blogów
  5. Tworzenie postów
    1. Publikowanie posta na blogu
    2. Tworzenie szkicu posta na blogu
  6. Pobieranie postów
    1. Pobieranie wszystkich wpisów na blogu
    2. Pobieranie postów za pomocą parametrów zapytania
  7. Aktualizowanie postów
  8. Usuwanie postów
  9. Komentarze
    1. Tworzenie komentarzy
    2. Pobieranie komentarzy
    3. Usuwanie komentarzy

Odbiorcy

Ten dokument jest przeznaczony dla programistów, którzy chcą pisać aplikacje klienta na platformę Java, które mogą wchodzić w interakcje z Bloggerem.

W tym dokumencie zakładamy, że rozumiesz ogólne założenia protokołu interfejsów Google Data API.

Informacje referencyjne o klasach i metodach biblioteki klienta znajdziesz w dokumentacji biblioteki klienta interfejsu API w języku Java. Ogólne informacje o interfejsie Blogger Data API znajdziesz w przewodniku po protokole.

Pierwsze kroki

Więcej informacji o konfigurowaniu biblioteki klienta znajdziesz w przewodniku Pierwsze kroki.

Biblioteka klienta Java wymaga wersji Java 1.5. Po pobraniu biblioteki klienta w pliku java/lib/gdataclient-1.0.jar znajdziesz klasy, których potrzebujesz na początek.

Tworzenie konta w Bloggerze

Możesz założyć konto Blogger na potrzeby testowania. Blogger korzysta z kont Google, więc jeśli masz już konto Google, nie musisz nic więcej robić.

Uruchamianie przykładowego kodu

Pełnotekstowy działający przykładowy klient zawierający cały przykładowy kod pokazany w tym dokumencie jest dostępny w bibliotece klienta Java w katalogu gdata/java/sample/blogger/BloggerClient.java. Instrukcje kompilacji i wykonania znajdują się w tym samym katalogu w pliku README.txt.

Przykładowy klient wykonuje kilka operacji na podanym blogu, aby zademonstrować korzystanie z interfejsu Blogger Data API.

Aby skompilować przykłady z tego dokumentu w swój własny kod, musisz użyć tych instrukcji import:

import com.google.gdata.client.*;
import com.google.gdata.data.*;
import com.google.gdata.util.*;
import java.io.IOException;
import java.net.URL;

Uwierzytelnianie w usłudze Blogger

Za pomocą interfejsu Blogger Data API możesz uzyskać dostęp do plików danych publicznych i prywatnych. Publiczne kanały nie wymagają uwierzytelniania, ale są tylko do odczytu. Jeśli chcesz zmodyfikować blogi, Twój klient musi się uwierzytelnić, zanim poprosi o pliki danych prywatnych. Może on uwierzytelniać się na 2 sposoby: za pomocą uwierzytelniania proxy AuthSub lub uwierzytelniania nazwą użytkownika i hasłem ClientLogin.

Więcej informacji o uwierzytelnianiu za pomocą interfejsów Google Data API znajdziesz w dokumentacji dotyczącej uwierzytelniania.

Większość przykładów w kolejnych sekcjach tego dokumentu zakłada, że masz uwierzytelniony obiekt GoogleService.

Uwierzytelnianie proxy AuthSub

Uwierzytelnianie 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 ani hasła użytkownika Bloggera. Zamiast tego klient uzyskuje specjalne tokeny AuthSub, które umożliwiają mu działanie w imieniu konkretnego użytkownika. Więcej szczegółowych informacji znajdziesz w dokumentacji AuthSub.

Gdy użytkownik po raz pierwszy odwiedza Twoją aplikację, nie został jeszcze uwierzytelniony. W takim przypadku musisz wyświetlić pewne informacje i link, który przekieruje użytkownika na stronę Google, gdzie będzie mógł uwierzytelnić Twoje żądanie dostępu do blogów. Biblioteka klienta Java udostępnia funkcję generowania adresu URL strony Google. Poniższy kod pobiera adres URL strony AuthSubRequest:

String next = "http://www.example.com/welcome.html";
String scope = "http://www.blogger.com/feeds/";
boolean secure = false;
boolean session = true;
String authSubLogin = AuthSubUtil.getRequestUrl(next, scope, secure, session);

Metoda getRequestUrl przyjmuje te parametry (odpowiadające parametrom zapytania używanym przez moduł obsługi AuthSubRequest):

dalej
Adres URL strony, na którą Google powinno przekierować użytkownika po uwierzytelnieniu.
zakres
Wskazuje, że aplikacja prosi o token dostępu do kanałów Bloggera. Użyj ciągu zakresu http://www.blogger.com/feeds/ (oczywiście zakodowanego w formacie URL).
Bezpieczny
Wskazuje, czy klient prosi o token zabezpieczony.
sesja
Wskazuje, czy zwrócony token można zamienić na token wielokrotnego użytku (sesji).

Powyższy przykład pokazuje wywołanie, które nie wymaga bezpiecznego tokena (wartość secure to false). Wygenerowany adres URL żądania może wyglądać tak:

https://www.google.com/accounts/AuthSubRequest?scope=http%3A%2F%2Fwww.blogger.com%2Ffeeds%2F&session=1&secure=0&next=http%3A%2F%2Fwww.example.com%2Fwelcome.html

Użytkownik klika link do witryny Google i uwierzytelnia się na swoim koncie Google.

Po uwierzytelnieniu użytkownika system AuthSub przekieruje go na adres URL określony w parametrze zapytania next adresu URL AuthSubRequest. System AuthSub dołącza do tego adresu URL token uwierzytelniający jako wartość parametru zapytania token. Na przykład:

http://www.example.com/welcome.html?token=yourAuthToken

Ta wartość tokena reprezentuje token AuthSub jednorazowego użytku. W tym przykładzie, gdy podano session = true, token można zamienić na token sesji AuthSub, wywołując usługę AuthSubSessionToken w ten sposób: urlFromAuthSub to adres URL, do którego AuthSub dołączył token:

String token = AuthSubUtil.getTokenFromReply(urlFromAuthSub);
String sessionToken = AuthSubUtil.exchangeForSessionToken(token, null);

Oznacza to, że do metody exchangeForSessionToken przekazujesz token jednorazowego użytku wraz z wartością null (w trybie niezarejestrowanym) lub kluczem prywatnym (w trybie zarejestrowanym). Interfejs AuthSub zwraca token sesji. Więcej informacji o zarejestrowanych aplikacjach i kluczach prywatnych znajdziesz w sekcji „Podpisywanie żądań” dokumentacji AuthSub.

Aplikacja może następnie używać tokena sesji w kolejnych interakcjach z Bloggerem. Aby biblioteka klienta Java automatycznie wysyłała token sesji z każdym żądaniem, wywołaj metodę setAuthSubToken obiektu GoogleService:

GoogleService.setAuthSubToken(sessionToken, null);

Następnie biblioteka klienta automatycznie wysyła token wraz z każdym żądaniem.

uwierzytelnianie za pomocą nazwy użytkownika i hasła ClientLogin

Użyj uwierzytelniania ClientLogin, jeśli Twój klient jest samodzielnym, jednoużytkownikowym klientem „zainstalowanym” (np. aplikacją na komputer). Wystarczy wywołać metodę setUserCredentials obiektu GoogleService, a wszystkie kolejne interakcje z Bloggerem będą uwierzytelniane:

GoogleService myService = new GoogleService("blogger", "exampleCo-exampleApp-1");
myService.setUserCredentials("user@example.com", "secretPassword");

W tym fragmencie kodu do konstruktora GoogleService przekazujemy 2 parametry. Pierwszy parametr to nazwa usługi, z którą chcemy się komunikować. Drugi parametr to nazwa naszej aplikacji w formie companyName-applicationName-versionID.

Więcej informacji o uwierzytelnianiu za pomocą ClientLogin, w tym przykładowe żądania i odpowiedzi, znajdziesz w dokumentacji Uwierzytelnianie w zainstalowanych aplikacjach.

Uwaga: używaj tego samego tokena do wszystkich żądań w danej sesji. Nie pobieraj nowego tokena dla każdego żądania Bloggera.

Uwaga: jak opisano w dokumentacji ClientLogin, żądanie uwierzytelnienia może zakończyć się niepowodzeniem i wymagać rozwiązania captcha. Jeśli chcesz, aby Google wyświetlał i obsługiwał test CAPTCHA, prześlij użytkownika do https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger(zamiast do adresu URL obsługiwanego przez CAPTCHA podanego w dokumentacji ClientLogin).

Pobieranie listy blogów

Interfejs Blogger Data API udostępnia plik danych, który zawiera listę blogów danego użytkownika. Taki plik danych jest nazywany „metaplikiem danych”.

Poniższy przykładowy kod używa uwierzytelnionego obiektu GoogleService do pobierania metafeedu, a następnie drukuje tytuł każdego bloga.

public static void printUserBlogs(GoogleService myService)
    throws ServiceException, IOException {

  // Request the feed
  final URL feedUrl = new URL("http://www.blogger.com/feeds/default/blogs");
  Feed resultFeed = myService.getFeed(feedUrl, Feed.class);

  // Print the results
  System.out.println(resultFeed.getTitle().getPlainText());
  for (int i = 0; i < resultFeed.getEntries().size(); i++) {
    Entry entry = resultFeed.getEntries().get(i);
    System.out.println("\t" + entry.getTitle().getPlainText());
  }
}

Zapisz adres URL używany przez metodę getFeed. To domyślny URL metafeedu; zwraca listę blogów dla aktualnie uwierzytelnionego użytkownika. Aby uzyskać dostęp do pliku danych innego użytkownika, możesz podać jego identyfikator zamiast znaku default w adresie URL metapliku danych. Identyfikator użytkownika to ciąg cyfr na końcu adresu URL profilu użytkownika.

Tworzenie postów

Interfejs Blogger Data API umożliwia tworzenie i publikowanie nowych wpisów na blogu, a także tworzenie ich wersji roboczych.

Uwaga: nie można obecnie ustawić niestandardowego autora postów. Wszystkie nowe posty będą wyglądać tak, jakby zostały utworzone przez aktualnie uwierzytelnionego użytkownika.

Publikowanie posta na blogu

Możesz używać biblioteki klienta Java do publikowania nowych wpisów na blogu.

Najpierw utwórz obiekt Entry, który będzie reprezentować post na blogu. Następnie możesz ustawić tytuł, treść i inne atrybuty posta na blogu. Na koniec użyj obiektu GoogleService, aby wstawić post. Oto przykład, jak opublikować nowy post na blogu:

public static Entry createPost(
    GoogleService myService, String blogID, String title,
    String content, String userName)
    throws ServiceException, IOException {
  // Create the entry to insert
  Entry myEntry = new Entry();
  myEntry.setTitle(new PlainTextConstruct(title));
  myEntry.setContent(new PlainTextConstruct(content));

  // Ask the service to insert the new entry
  URL postUrl = new URL("http://www.blogger.com/feeds/" + blogID + "/posts/default");
  return myService.insert(postUrl, myEntry);
}

Metoda insert przyjmuje jako parametr adres URL przesyłanego pliku usługi. Następnie metoda zwraca wpis w postaci, w której został zapisany przez Bloggera. Zwrócony wpis jest taki sam jak przesłany, ale zawiera też różne elementy dodane przez Bloggera, takie jak identyfikator wpisu.

Jeśli z jakiegoś powodu nie uda się zrealizować żądania, Blogger może zwrócić inny kod stanu. Informacje o kodach stanu znajdziesz w dokumentacji interfejsu Google Data API.

Tworzenie wersji roboczej posta na blogu

Posty w postaci wersji roboczych są tworzone w taki sam sposób jak posty publiczne, ale musisz ustawić atrybut draft obiektu Entry. Możesz utworzyć post na blogu podobny do tego powyżej jako wersję roboczą, dodając wyróżniony wiersz:

public static Entry createPost(GoogleService myService, String blogId,
    String title, String content, String userName,
    Boolean isDraft)
    throws ServiceException, IOException {
  // Create the entry to insert
  Entry myEntry = new Entry();
  myEntry.setTitle(new PlainTextConstruct(title));
  myEntry.setContent(new PlainTextConstruct(content));
  myEntry.setDraft(isDraft);

  // Ask the service to insert the new entry
  URL postUrl = new URL("http://www.blogger.com/feeds/" + blogID + "/posts/default");
  return myService.insert(postUrl, myEntry);
}

Aby zmienić istniejący szkic posta na opublikowany, możesz pobrać szkic, ustawić atrybut szkic na false, a następnie zaktualizować post. W następnych 2 sekcjach omówimy pobieranie i aktualizowanie postów.

Pobieranie postów

W sekcjach poniżej znajdziesz instrukcje pobierania listy wpisów na blogu z parametrami zapytania i bez nich.

Możesz wysyłać zapytania do publicznego kanału Bloggera bez uwierzytelniania. Dlatego przed pobraniem postów z publicznego bloga nie musisz wywoływać metody setUserCredentials ani przeprowadzać uwierzytelniania AuthSub.

Pobieranie wszystkich wpisów na blogu

Aby pobrać posty użytkownika, wywołaj tę samą metodę getFeed, która służy do pobierania metadanych blogów, ale tym razem prześlij adres URL kanału postów na blogu:

public static void printAllPosts(
    GoogleService myService, String blogId)
    throws ServiceException, IOException {
  // Request the feed
  URL feedUrl = new URL("http://www.blogger.com/feeds/" + blogID + "/posts/default");
  Feed resultFeed = myService.getFeed(feedUrl, Feed.class);

  // Print the results
  System.out.println(resultFeed.getTitle().getPlainText());
  for (int i = 0; i < resultFeed.getEntries().size(); i++) {
    Entry entry = resultFeed.getEntries().get(i);
    System.out.println("\t" + entry.getTitle().getPlainText());
  }
  System.out.println();
}

Pobieranie postów za pomocą parametrów zapytania

Interfejs Blogger Data API umożliwia żądanie zestawu wpisów, które odpowiadają określonym kryteriam, np. żądanie postów na blogu opublikowanych lub zaktualizowanych w określonym przedziale czasowym. Aby to zrobić, utwórz obiekt Query i przekaż go do metody GoogleService.getQuery.

Aby na przykład wysłać zapytanie dotyczące zakresu dat, użyj metod setPublishedMin i setPublishedMax obiektu Query. Poniższy fragment kodu wyświetla tytuł każdego posta na blogu opublikowanego w okresie od podanego czasu rozpoczęcia do podanego czasu zakończenia:

public static void printDateRangeQueryResults(
    GoogleService myService, String blogId,
    DateTime startTime, DateTime endTime)
    throws ServiceException, IOException {
  // Create query and submit a request
  URL feedUrl = new URL("http://www.blogger.com/feeds/" + blogID + "/posts/default");
  Query myQuery = new Query(feedUrl);
  myQuery.setPublishedMin(startTime);
  myQuery.setPublishedMax(endTime);
  Feed resultFeed = myService.query(myQuery, Feed.class);

  // Print the results
  System.out.println(resultFeed.getTitle().getPlainText() +
      " posts between " + startTime + " and " + endTime);
  for (int i = 0; i < resultFeed.getEntries().size(); i++) {
    Entry entry = resultFeed.getEntries().get(i);
    System.out.println("\t" + entry.getTitle().getPlainText());
    System.out.println("\t" + entry.getUpdated().toStringRfc822());
  }
  System.out.println();
}

Zwróć uwagę, że obiekt Query jest tworzony przy użyciu tego samego adresu URL pliku danych postów, który służy do pobierania postów.

Interfejs Blogger Data API obsługuje te metody Query:

addCategoryFilter
Określ kategorie (zwane też etykietami), aby filtrować wyniki w pliku danych. Na przykład http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie zwraca wpisy z etykietami Fritz i Laurie.
setMaxResults
Ustaw maksymalną liczbę zwracanych wpisów.
setPublishedMin, setPublishedMax
Ustaw granice dat publikacji wpisów.
setStartIndex
Ustaw indeks pierwszego wyniku, który ma zostać pobrany (w celu przewijania) (od 1).
setUpdatedMin, setUpdatedMax
Ustaw granice dat aktualizacji wpisów. Te parametry zapytania są ignorowane, chyba że parametr orderby ma wartość updated.

Uwaga: obecnie nie ma ustawień dla parametru zapytania orderby. Jeśli jednak chcesz ustawić tę opcję, możesz użyć metody Query.addCustomParameter().

Więcej informacji o parametrach zapytań znajdziesz w przewodniku po interfejsie Blogger Data API oraz w przewodniku po interfejsach Google Data API.

Aktualizowanie postów

Aby zaktualizować istniejący post na blogu, najpierw pobierasz wpis, który chcesz zaktualizować, a potem go modyfikujesz i wysyłasz do Bloggera za pomocą metody update. Podany niżej fragment kodu zmienia tytuł wpisu na blogu, zakładając, że został on już pobrany z serwera.

public static Entry updatePostTitle(
    GoogleService myService, Entry entryToUpdate, String newTitle)
    throws ServiceException, IOException {
  entryToUpdate.setTitle(new PlainTextConstruct(newTitle));
  URL editUrl = new URL(entryToUpdate.getEditLink().getHref());
  return myService.update(editUrl, entryToUpdate);
}

Powyższy kod zwraca Entry zawierający cały nowo zaktualizowany post. Aby zaktualizować inne właściwości, po prostu ustaw je w obiekcie Entry przed wywołaniem metody update.

Uwaga: modyfikowanie danych autora powiązanych z postami nie jest obecnie obsługiwane.

Usuwanie postów

Aby usunąć post, prześlij adres URL edycji posta do metody delete obiektu GoogleService w ten sposób:

public static void deletePost(
    GoogleService myService, String editLinkHref)
    throws ServiceException, IOException {
  URL deleteUrl = new URL(editLinkHref);
  myService.delete(deleteUrl);
}

Komentarze

Interfejs Blogger Data API umożliwia tworzenie, pobieranie i usuwanie komentarzy. Aktualizowanie komentarzy nie jest obsługiwane (nie jest też dostępne w interfejsie internetowym).

Tworzenie komentarzy

Aby opublikować komentarz, utwórz obiekt Entry i wstaw go w ten sposób:

public static Entry createComment(
    GoogleService myService, String blogID, String postId,
    String commentText)
    throws ServiceException, IOException {
  // Build the comment feed URI
  String commentsFeedUri = "http://www.blogger.com/feeds/" + blogID + "/" + postId + "/comments/default";
  URL feedUrl = new URL(commentsFeedUri);

  // Create a new entry for the comment and submit it to the GoogleService
  Entry myEntry = new Entry();
  myEntry.setContent(new PlainTextConstruct(commentText));
  return myService.insert(feedUrl, myEntry);
}

Uwaga: obecnie możesz dodawać komentarze tylko do bloga należącego do uwierzytelnionego użytkownika.

Uwaga: nie można obecnie ustawić niestandardowego autora komentarzy. Wszystkie nowe komentarze będą wyglądać tak, jakby zostały utworzone przez aktualnie uwierzytelnionego użytkownika.

Pobieranie komentarzy

Komentarze do konkretnego posta możesz pobrać z adresu URL kanału komentarzy do tego posta:

public static void printAllComments(
    GoogleService myService, String blogID, String postId)
    throws ServiceException, IOException {
  // Build comment feed URI and request comments on the specified post
  String commentsFeedUri = "http://www.blogger.com/feeds/" + blogID + "/" + postId + "/comments/default";
  URL feedUrl = new URL(commentsFeedUri);
  Feed resultFeed = myService.getFeed(feedUrl, Feed.class);

  // Display the results
  System.out.println(resultFeed.getTitle().getPlainText());
  for (int i = 0; i < resultFeed.getEntries().size(); i++) {
    Entry entry = resultFeed.getEntries().get(i);
    System.out.println("\t" +
        ((TextContent) entry.getContent()).getContent().getPlainText());
    System.out.println("\t" + entry.getUpdated().toStringRfc822());
  }
  System.out.println();
}

Możesz też pobrać komentarze ze wszystkich postów, korzystając z kanału komentarzy do bloga. Adres URL:

http://www.blogger.com/feeds/blogID/comments/default

Usuwanie komentarzy

Aby usunąć komentarz, prześlij adres URL edycji komentarza do metody delete obiektu GoogleService w ten sposób:

public static void deleteComment(GoogleService myService, String editLinkHref)
    throws ServiceException, IOException {
  URL deleteUrl = new URL(editLinkHref);
  myService.delete(deleteUrl);
}

Powrót do góry