Przewodnik dla programistów: PHP

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.

W tym dokumencie opisujemy możliwości interfejsu Blogger Data API oraz przedstawiamy przykłady podstawowych interakcji interfejsu Data API z wykorzystaniem biblioteki klienta Zend Google Data API. 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

  1. Odbiorcy
  2. Pierwsze kroki
    1. Tworzenie konta Bloggera
    2. Uruchamianie przykładowego kodu
    3. Korzystanie z magicznych zbieraczy i seterów
    4. Inne zasoby
  3. Uwierzytelnianie w usłudze Blogger
    1. Uwierzytelnianie OAuth
    2. Uwierzytelnianie serwera proxy AuthSub
    3. 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ć aplikacje klienckie w języku PHP umożliwiające interakcję z Bloggerem.

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 PHP. 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 Zend wymaga języka PHP w wersji 5.1.4 lub nowszej. Jest ona dostępna w ramach Zend Framework oraz do oddzielnego pliku do pobrania. Aby korzystać z Bloggera, używaj biblioteki klienta w wersji 1.0.0 lub nowszej.

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 repozytorium Zend Framework SVN. Znajdziesz go pod adresem /framework/standard/trunk/demos/Zend/Gdata/Blogger.php. Przykład zawiera wszystkie funkcje opisane w tym dokumencie. Można go uruchomić tylko z poziomu wiersza poleceń:

php Blogger.php -- --user=[email_address] --pass=[password]

Zanim uruchomisz ten przykładowy kod lub utworzysz własny kod przy użyciu Zend Framework, konieczne może być ustawienie elementu include_path i wczytanie odpowiednich klas. Ścieżka uwzględniania można ustawić za pomocą ustawienia php.ini lub za pomocą metody set_include_path. Ten kod żąda dostępu do podstawowej klasy Zend_Gdata, klasy Zend_Gdata_Query i klasy uwierzytelniania Zend_Gdata_ClientLogin.

require_once 'Zend/Loader.php';
Zend_Loader::loadClass('Zend_Gdata');
Zend_Loader::loadClass('Zend_Gdata_Query');
Zend_Loader::loadClass('Zend_Gdata_ClientLogin');

Korzystanie z magicznych zbieraczy i seterów

W całej bibliotece klienta PHP dodaliśmy obsługę magicznych seterów/pobierających. Umożliwiają one bezpieczny dostęp do właściwości klasy za pomocą tradycyjnych metod ustawiania/pobierania lub przez dostęp do właściwości. Jeśli na przykład $gdataObject jest instancją obiektu w tej bibliotece, te 2 wiersze kodu mają identyczne efekty:

$gdataObject->setFoo("bar");
$gdataObject->foo = "bar";

Również te 2 wiersze kodu mają identyczne skutki:

$baz = $gdataObject->getFoo();
$baz = $gdataObject->foo;

Podobnie metody stosowane w magicznej fabryce ułatwiają deklaracja nowych obiektów. Zamiast zapamiętywać długie nazwy klas objęte konwencją nazewnictwa Zend, możesz utworzyć nową właściwość object, wywołując newObject(); w kliencie usługi Zend. Na przykład te 2 fragmenty deklarują nowy obiekt rozszerzenia draft. W sekcji Tworzenie postów znajdziesz więcej informacji na temat usługi drafts.

// Traditional instantiation
$gdClient = new Zend_Gdata();
$draft = new Zend_Gdata_App_Extension_Draft();

// Magic factory instantiation
$gdClient = new Zend_Gdata();
$draft = $gdClient->newDraft();

Wzbogacanie i zdobywanie magii jest opcjonalny, więc wybierz metodę, która najbardziej Ci odpowiada.

Inne zasoby

Inne zasoby dotyczące komponentu Google Data API w Zend Framework (Zend_Gdata):

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 być uwierzytelniany za pomocą jednej z 3 metod: uwierzytelniania OAuth, uwierzytelniania serwera proxy AuthSub lub uwierzytelniania nazwy użytkownika i hasła ClientLogin.

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 klienta o nazwie $gdClient.

Uwierzytelnianie OAuth

Dokumentację dotyczącą uwierzytelniania OAuth przy użyciu biblioteki Zend PHP GData znajdziesz w artykule Protokół OAuth w bibliotekach klienta protokołu Google Data Protocol.

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 Zend zawiera funkcję generowania adresu URL strony Google. Poniższy kod umożliwia pobieranie adresu URL strony AuthSubRequest:

function getAuthSubUrl()
{
  $next = getCurrentUrl();
  $scope = 'http://www.google.com/blogger/feeds/';
  $secure = false;
  $session = true;
  return Zend_Gdata_AuthSub::getAuthSubTokenUri($next, $scope, $secure, $session);
}

$authSubUrl = getAuthSubUrl();
echo '<a href=\"$authSubUrl\">login to your Google account</a>';

Metoda getAuthSubTokenUri 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 wynosi 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.php

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.php?token=yourAuthToken

Wartość tokena możesz pobrać za pomocą parametru $_GET['token'].

Ta wartość tokena reprezentuje jednorazowy token AuthSub. W tym przykładzie, ponieważ określono $session = true, token ten można wymienić na token sesji AuthSub za pomocą metody Zend_Gdata_AuthSub::getAuthSubSessionToken, która wywołuje usługę AuthSubSessionToken:

if(! isset($_SESSION['sessionToken']) && isset($_GET['token'])) {
  $_SESSION['sessionToken'] =
      Zend_Gdata_AuthSub::getAuthSubSessionToken($_GET['token']);
}

Fragment kodu najpierw sprawdza, czy token sesji AuthSub jest już dostępny. Jeśli tak nie jest, ale w adresie URL jest podany token jednorazowego użytku, fragment kodu przekazuje ten token jednorazowy do metody getAuthSubSessionToken, a interfejs AuthSub zwraca token sesji. Kod umieszcza następnie wartość tokena sesji w zmiennej sesji $_SESSION['sessionToken'].

Aplikacja może następnie używać wartości tokena sesji w kolejnych interakcjach z Bloggerem. Możesz użyć metody Zend_Gdata_AuthSub::getHttpClient, aby uzyskać obiekt Zend_Http_Client, który ma gotowe ustawienie nagłówka Authorization umożliwiające dołączenie danych logowania AuthSub:

$client = Zend_Gdata_AuthSub::getHttpClient($_SESSION['sessionToken']);

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ą).

Poniższy kod korzysta z metody Zend_Gdata_ClientLogin::getHttpClient do wysłania żądania do usługi ClientLogin, pobrania tokena uwierzytelniania i utworzenia obiektu Zend_Http_Client z odpowiednim nagłówkiem uwierzytelniania. Następnie zwracana przez tę metodę metoda HttpClient jest używana do utworzenia obiektu usługi Zend_Gdata.

Zwróć uwagę, że $accountType ma wartość GOOGLE. Jeśli nie ustawisz tego parametru, użytkownicy G Suite nie będą mogli korzystać z interfejsu Blogger API. 

$user = 'user@example.com';
$pass = 'secretPasswd';
$service = 'blogger';

$client = Zend_Gdata_ClientLogin::getHttpClient($user, $pass, $service, null,
        Zend_Gdata_ClientLogin::DEFAULT_SOURCE, null, null,
        Zend_Gdata_ClientLogin::CLIENTLOGIN_URI, 'GOOGLE');
$gdClient = new Zend_Gdata($client);

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 metadane z uwierzytelnionego obiektu $gdClient, a następnie wyświetla tytuł każdego bloga.

Klasa Zend_Gdata_Query zajmuje się tworzeniem adresu URL zapytania. W tym przypadku nie musisz wykonywać żadnych dodatkowych czynności, ale użyteczność klasy Query będzie widoczna w sekcji Pobieranie postów według parametrów zapytania w tym dokumencie.

function printAllBlogs()
{
  $query = new Zend_Gdata_Query('http://www.blogger.com/feeds/default/blogs');
  $feed = $gdClient->getFeed($query);
  printFeed($feed);
}

function printFeed($feed)
{
  $i = 0;
  foreach($feed->entries as $entry) {
    print $i ." ". $entry->title->text . "\n";
    $i++;
  }
}

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.

Fragment kodu poniżej pokazuje, jak wyodrębnić identyfikator bloga z kanału. Identyfikator bloga będzie potrzebny do tworzenia, aktualizowania i usuwania postów oraz komentarzy. Zmienna $index wskazuje, który blog w kanale bloga użytkownika jest używany. Pole id ma postać tag:blogger.com,1999:user-userID.blog-blogID, więc znak split w znaku „-” umieszcza identyfikator bloga w ostatnim elemencie tablicy wynikowej.

$idText = split('-', $feed->entries[$index]->id->text);
$blogID = $idText[2];

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

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

Najpierw utwórz instancję wpisu reprezentującą posta na blogu. Następnie możesz ustawić tytuł, treść i inne atrybuty posta. Na koniec wywołaj metodę insertEntry, aby wstawić posta. Tutaj możesz zobaczyć działające wystąpienia magicznej fabryki z nowymi obiektami Zend_Gdata_Entry, Zend_Gdata_App_Extension_Title i Zend_Gdata_App_Extension_Content.

function createPublishedPost($title='Hello, world!', $content='I am blogging on the internet.')
{
  $uri = 'http://www.blogger.com/feeds/' . $blogID . '/posts/default';
  $entry = $gdClient->newEntry();
  $entry->title = $gdClient->newTitle($title);
  $entry->content = $gdClient->newContent($content);
  $entry->content->setType('text');

  $createdPost = $gdClient->insertEntry($entry, $uri);
  $idText = split('-', $createdPost->id->text);
  $newPostID = $idText[2];

  return $newPostID;
}

Tworzenie wersji roboczej posta na blogu

Wersje robocze postów tworzy się tak samo jak posty publiczne, ale musisz ustawić atrybut wersja robocza obiektu wpisu. Możesz utworzyć wersję roboczą posta podobnego do tego powyżej, dodając wyróżnione wiersze:

function createDraftPost($title='Salutations, world!', $content='Hmm ... not quite right, must rework the title later.')
{
  $uri = 'http://www.blogger.com/feeds/' . $blogID . '/posts/default';
  $entry = $gdClient->newEntry();

  $entry->title = $gdClient->newTitle(trim($title));
  $entry->content = $gdClient->newContent($content);
  $entry->content->setType('text');

  $control = $gdClient->newControl();
  $draft = $gdClient->newDraft('yes');
  $control->setDraft($draft);
  $entry->control = $control;

  $createdPost = $gdClient->insertEntry($entry, $uri);
  $idText = split('-', $createdPost->id->text);
  return $idText[2];
}

W taki sam sposób jak przy ustawianiu tytułu lub treści posta tworzysz nowe obiekty Zend_Gdata_App_Extension_Control i Zend_Gdata_App_Extension_Draft, a następnie przypisujesz je do atrybutu Control wpisu.

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 no, a następnie zaktualizuj posta. Pobieranie i aktualizowanie postów omówimy w dwóch kolejnych 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. W związku z tym przed pobraniem postów z bloga publicznego nie musisz konfigurować danych logowania 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:

function printAllPosts($gdClient, $blogID)
{
  $query = new Zend_Gdata_Query('http://www.blogger.com/feeds/' . $blogID . '/posts/default');
  $feed = $gdClient->getFeed($query);
  printFeed($feed);
}

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 zapytania i przekaż go do metody getFeed.

Aby np. wysłać zapytanie dotyczące zakresu dat, ustaw parametry published-min i published-max obiektu zapytania. Ten fragment kodu umożliwia wydrukowanie tytułu i treści każdego posta opublikowanego na blogu między podaną godziną rozpoczęcia a zakończenia:

function printPostsInDateRange($gdClient, $blogID, $startDate='2007-04-01', $endDate='2007-04-25')
{
  $query = new Zend_Gdata_Query('http://www.blogger.com/feeds/' . $blogID . '/posts/default');
  $query->setParam('published-min', $startDate);
  $query->setParam('published-max', $endDate);

  $feed = $gdClient->getFeed($query);
  printFeed($feed);
}

Przydatną metodą debugowania klasy Zend_Gdata_Query jest getQueryUrl(). Pozwala ona wyświetlić zakodowany URL, który został utworzony.

Uwaga: obecnie nie ma żadnych algorytmów magicznych dla parametrów zapytania published-min i published-max. Możesz jednak używać właściwości setStartIndex i setMaxResults.

Interfejs API danych Bloggera obsługuje następujące parametry zapytania:

kategorie
Określa 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.
max-results
Maksymalna liczba wpisów do zwrócenia.
liczba publikacji: minimalna, liczba publikacji – maks.
Granice dat publikacji wpisów.
start-index
Indeks od 1 pierwszego wyniku do pobrania (na potrzeby stronicowania).

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 save. Poniższy fragment kodu zmienia tytuł i treść posta na blogu przy założeniu, że ten wpis został już pobrany z serwera.

public function updatePost($postID, $updatedTitle='Hello, World?',
                           $updatedContent='UPDATE: Still blogging',
                           $isDraft=False)
{
  $query = new Zend_Gdata_Query('http://www.blogger.com/feeds/' . $blogID . '/posts/default/' . $postID);
  $postToUpdate = $dClient->getEntry($query);
  $postToUpdate->title->text = $this->gdClient->newTitle($updatedTitle);
  $postToUpdate->content->text = $this->gdClient->newContent($updatedContent);

  if ($isDraft) {
    $draft = $gdClient->newDraft('yes');
  } else {
    $draft = $gdClient->newDraft('no');
  }

  $control = $gdClient->newControl();
  $control->setDraft($draft);
  $postToUpdate->control = $control;

  $updatedPost = $postToUpdate->save();
  return $updatedPost;
}

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 $gdClient w następujący sposób:

public function deletePost($gdClient, $blogID, $postID)
{
  $uri = 'http://www.blogger.com/feeds/' . $blogID . '/posts/default/' . $postID;
  $gdClient->delete($uri);
}

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 wpisu i wstaw go w następujący sposób:

function createComment($gdClient, $blogID, $postID, $commentText)
{
  $uri = 'http://www.blogger.com/feeds/' . $blogID . '/' . $postID . '/comments/default';

  $newComment = $gdClient->newEntry();
  $newComment->content = $gdClient->newContent($commentText);
  $newComment->content->setType('text');
  $createdComment = $gdClient->insertEntry($newComment, $uri);

  $editLink = split('/', $createdComment->getEditLink()->href);
  $newCommentID = $editLink[8];

  return $newCommentID; 
}

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 function printPostComments($gdClient, $blogID, $postID)
{
  $query = new Zend_Gdata_Query('http://www.blogger.com/feeds/' . $blogID . '/' . $postID . '/comments/default');
  $feed = $gdClient->getFeed($query);
  $printFeed($feed);
}

Możesz też uzyskać 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 $gdClient w ten sposób:

public function deleteComment($gdClient, $blogID, $postID, $commentID)
{
  $uri = 'http://www.blogger.com/feeds/' . $blogID . '/' . $postID . '/comments/default/' . $commentID;
  $gdClient->delete($uri);
}

Powrót do góry