Przewodnik dla programistów: Java

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

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 omówieniem możliwości interfejsu API danych Bloggera w tym dokumencie przedstawiamy przykłady podstawowych interakcji interfejsu Data API z wykorzystaniem biblioteki klienta w języku Java. Jeśli chcesz dowiedzieć się więcej o bazowym protokołie używanym w bibliotece, zapoznaj się z sekcją Protokół w tym przewodniku dla programistów.

Spis treści

  1. Odbiorcy
  2. Pierwsze kroki
    1. Tworzenie konta Bloggera
    2. Uruchamianie przykładowego kodu
  3. Uwierzytelnianie w usłudze Blogger
    1. Uwierzytelnianie serwera proxy AuthSub
    2. Uwierzytelnianie za pomocą nazwy użytkownika i hasła ClientLogin
  4. Pobieram listę blogów
  5. Tworzenie postów
    1. Publikowanie posta na blogu
    2. Tworzenie wersji roboczej posta na blogu
  6. Pobieram posty
    1. Pobieranie wszystkich postów na blogu
    2. Pobieranie postów przy użyciu 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ć klienckie aplikacje w Javie obsługujące Bloggera.

Zakładamy w nim, że rozumiesz ogólne koncepcje protokołu interfejsów API danych Google.

Informacje o klasach i metodach udostępnianych przez bibliotekę klienta znajdziesz w dokumentacji interfejsu API biblioteki klienta Java. Ogólne informacje o interfejsie API danych Bloggera znajdziesz w Przewodniku po protokole.

Pierwsze kroki

Jeśli potrzebujesz pomocy przy konfigurowaniu biblioteki klienta, zapoznaj się z przewodnikiem dla początkujących.

Biblioteka klienta Java wymaga środowiska Java 1.5. Po pobraniu biblioteki klienta w pliku java/lib/gdataclient-1.0.jar znajdziesz klasy, których potrzebujesz, aby rozpocząć.

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ć.

Uruchamianie przykładowego kodu

Pełny działający przykładowy klient, który zawiera cały przykładowy kod pokazany w tym dokumencie, jest dostępny w dystrybucji biblioteki klienta Java w katalogu gdata/java/sample/blogger/BloggerClient.java. Instrukcje kompilacji i wykonywania znajdują się w tym samym katalogu w pliku README.txt.

Przykładowy klient wykonuje kilka operacji na udostępnionym blogu, aby zademonstrować użycie interfejsu Blogger Data API.

Aby skompilować własny kod z przykładów z tego dokumentu, potrzebujesz 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

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. Może uwierzytelniać się z użyciem 2 sposobów: uwierzytelniania serwera proxy AuthSub lub uwierzytelniania ClientLogin przy użyciu nazwy użytkownika i hasła.

Więcej ogólnych informacji o uwierzytelnianiu za pomocą interfejsów API danych Google znajdziesz w dokumentacji uwierzytelniania.

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

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. Szczegółowe informacje znajdziesz w dokumentacji AuthSub.

Gdy użytkownik po raz pierwszy odwiedza Twoją aplikację, nie jest jeszcze uwierzytelniony. W takim przypadku musisz podać informacje i link przekierowujący użytkownika do strony Google, aby uwierzytelnić prośbę o dostęp do jego blogów. Biblioteka klienta w języku Java udostępnia funkcję generowania adresu URL strony Google. Poniższy kod umożliwia pobieranie adresu 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 następujące parametry (odpowiadające parametrom zapytania używanym przez moduł obsługi AuthSubRequest):

dalej
Adres URL strony, na którą Google ma przekierować użytkownika po uwierzytelnieniu.
zakres
Wskazuje, że aplikacja prosi o token dostępu do kanałów Bloggera. Ciąg zakresu, którego chcesz użyć, to http://www.blogger.com/feeds/ (oczywiście zakodowany pod adresem URL).
Bezpieczny
Wskazuje, czy klient prosi o bezpieczny token.
sesja
Wskazuje, czy zwrócony token można wymienić na token wielokrotnego użytku (sesyjny).

Powyższy przykład to wywołanie, które nie wysyła żądania bezpiecznego tokena (wartość secure to false). Powstały 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.

Gdy użytkownik się uwierzytelni, system AuthSub przekieruje go na adres URL podany w parametrze zapytania next adresu URL AuthSubRequest. System AuthSub dołącza do tego adresu URL token uwierzytelniania jako wartość parametru zapytania token. Na przykład:

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

Ta wartość tokena reprezentuje jednorazowy token AuthSub. W tym przykładzie, ponieważ określono session = true, token można wymienić na token sesji AuthSub przez wywołanie usługi AuthSubSessionToken w następujący sposób, gdzie urlFromAuthSub to URL, do którego AuthSub dołączył token:

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

Musisz przekazać jednorazowy token do metody exchangeForSessionToken wraz z null (w przypadku trybu niezarejestrowanego) lub kluczem prywatnym (w trybie zarejestrowanym), a interfejs AuthSub zwraca token sesji. Więcej informacji o zarejestrowanych aplikacjach i kluczach prywatnych znajdziesz w sekcji „Signing requests” (Żądania podpisywania) w dokumentacji AuthSub.

Aplikacja może następnie używać tokena sesji w kolejnych interakcjach z Bloggerem. Aby umożliwić bibliotece klienta Java automatyczne wysyłanie tokena sesji z każdym żądaniem, wywołaj metodę setAuthSubToken obiektu GoogleService:

GoogleService.setAuthSubToken(sessionToken, null);

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

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

Użyj uwierzytelniania ClientLogin, jeśli klient jest samodzielnym, „zainstalowanym” klientem „zainstalowanym” przez pojedynczego użytkownika (np. aplikacją komputerową). Wystarczy wywołać metodę setUserCredentials w obiekcie GoogleService, a wszystkie późniejsze interakcje z Bloggerem będą uwierzytelniane:

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

We fragmencie kodu powyżej przekazujemy 2 parametry do konstruktora GoogleService. Pierwszym z nich jest nazwa usługi, z którą chcemy wejść w interakcję. Drugi parametr to nazwa naszej aplikacji w formacie companyName-applicationName-versionID.

Więcej informacji o uwierzytelnianiu ClientLogin, w tym przykładowe żądania i odpowiedzi, znajdziesz w dokumentacji uwierzytelniania zainstalowanych aplikacji.

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

Uwaga: zgodnie z opisem w dokumentacji ClientLogin może się zdarzyć, że żądanie uwierzytelnienia się nie powiedzie i zostanie wykonane zadanie CAPTCHA. Jeśli Google ma uruchamiać i obsługiwać test CAPTCHA, wyślij użytkownikowi adres https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger (a nie adres URL obsługi CAPTCHA podany w dokumentacji ClientLogin).

Pobieranie listy blogów

Interfejs API danych Bloggera to kanał z listą blogów konkretnego użytkownika. Kanał ten jest nazywany „metakanałem”.

Poniższy przykładowy kod pobiera metakanał za pomocą uwierzytelnionego obiektu GoogleService, a następnie wyświetla 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. Jest to domyślny adres URL metakanału; zwraca listę blogów aktualnie uwierzytelnionego użytkownika. Aby uzyskać dostęp do kanału innego użytkownika, możesz w adresie URL metakanału umieścić jego identyfikator w miejscu default. Identyfikator użytkownika to ciąg cyfr na końcu adresu URL profilu użytkownika.

Tworzenie postów

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

Uwaga: ustawianie niestandardowego autora postów nie jest obecnie obsługiwane. Wszystkie nowe posty będą wyświetlane tak, jakby zostały utworzone przez aktualnie uwierzytelnionego użytkownika.

Publikowanie posta na blogu

Do publikowania nowych wpisów w blogu można używać biblioteki klienta Java.

Najpierw utwórz obiekt Entry reprezentujący post na blogu. Następnie możesz ustawić tytuł, treść i inne atrybuty posta na blogu. Na koniec użyj obiektu GoogleService, aby wstawić posta. Oto przykład publikowania nowego posta 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 posta usługi. Następnie metoda zwraca wpis w takiej postaci, w jakiej został on zapisany w Bloggerze. Zwrócony wpis jest taki sam jak ten wysłany przez Ciebie, ale zawiera też różne elementy dodane przez Bloggera, takie jak identyfikator posta.

Jeśli z jakiegoś powodu żądanie się nie powiedzie, Blogger może zwrócić inny kod stanu. Informacje o kodach stanu znajdziesz w dokumentacji protokołu Google Data API.

Tworzenie wersji roboczej posta na blogu

Wersje robocze postów tworzy się tak samo jak posty publiczne, ale musisz ustawić atrybut draft obiektu Entry. Możesz utworzyć wersję roboczą posta na blogu, takiego jak ten powyżej, 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);
}

Możesz przekształcić istniejącą wersję roboczą posta na blogu w opublikowanego posta. W tym celu pobierz jego wersję roboczą, ustaw wartość atrybutu wersji roboczej na wartość Fałsz, a następnie zaktualizuj posta. Pobieranie i aktualizowanie postów zostanie omówione w następnych dwóch sekcjach.

Pobieram posty

W poniższych sekcjach opisano, jak pobrać listę postów na blogu z parametrami zapytania i bez nich.

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

Pobieranie wszystkich postów z bloga

Aby pobrać posty użytkownika, wywołaj tę samą metodę getFeed, która została użyta do pobrania metakanału blogów, ale tym razem wyślij adres URL kanału z postami 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 przy użyciu parametrów zapytania

Interfejs API danych Bloggera umożliwia żądanie zbioru wpisów spełniających określone kryteria, na przykład żądania postów na blogu opublikowanych lub zaktualizowanych w wybranym zakresie dat. W tym celu utwórz obiekt Query i przekaż go do metody GoogleService.getQuery.

Aby np. wysłać zapytanie dotyczące zakresu dat, użyj metod setPublishedMin i setPublishedMax obiektu Query. Następujący fragment kodu wyświetla tytuł każdego posta opublikowanego na blogu między podaną godziną rozpoczęcia a 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 utworzony za pomocą tego samego adresu URL kanału postów, który jest używany do pobierania postów.

Interfejs API danych Bloggera obsługuje następujące metody metody Query:

addCategoryFilter
Określ kategorie (nazywane też etykietami), aby filtrować wyniki z pliku danych. Na przykład funkcja http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie zwraca wpisy z etykietami Fritz i Laurie.
setMaxResults
Ustaw maksymalną liczbę elementów do zwrócenia.
setReleaseMin i setPublishMax
Określ granice dat publikacji wpisów.
setStartIndex
Ustaw indeks pierwszego wyniku do pobrania (na potrzeby stronicowania) oparty na 1.
setUpdatedMin, setUpdatedMax
Określ granice dat aktualizacji wpisów. Te parametry zapytania są ignorowane, chyba że parametr orderby ma wartość updated.

Uwaga: obecnie nie ma filtrów dla parametru zapytania orderby. W razie potrzeby nadal możesz jednak używać metody Query.addCustomParameter().

Więcej informacji o parametrach zapytań znajdziesz w Przewodniku po interfejsie API danych Bloggera i w Przewodniku po interfejsach API danych Google.

Aktualizuję posty

Aby zaktualizować istniejącego posta na blogu, najpierw pobierz wpis, który chcesz zaktualizować, następnie zmodyfikuj, a następnie wyślij do Bloggera za pomocą metody update. Ten fragment kodu zmienia tytuł wpisu na blogu przy założeniu, że ten wpis został 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 wartość Entry zawierającą całego zaktualizowanego posta. Aby zaktualizować inne właściwości, ustaw je w obiekcie Entry przed wywołaniem update.

Uwaga: obecnie nie można zmieniać danych o autorze powiązanych z postami.

Usuwam posty

Aby usunąć posta, przekaż jego adres URL edycji do metody delete w obiekcie GoogleService w następujący sposób:

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

Komentarze

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

Tworzenie komentarzy

Aby opublikować komentarz, utwórz obiekt Entry i wstaw go w następujący 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 publikować komentarze tylko na blogu należącym do uwierzytelnionego użytkownika.

Uwaga: ustawianie niestandardowego autora komentarzy nie jest obecnie obsługiwane. Wszystkie nowe komentarze będą wyświetlane tak, jakby zostały utworzone przez aktualnie uwierzytelnionego użytkownika.

Pobieranie komentarzy

Komentarze do konkretnego posta możesz pobrać za pomocą adresu URL kanału komentarzy:

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ż wyświetlić komentarze do wszystkich postów, używając adresu URL kanału komentarzy bloga:

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

Usuwanie komentarzy

Aby usunąć komentarz, przekaż go do metody delete w obiekcie 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