Przewodnik dla programistów: PHP

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 Blogger Data API oraz przykłady podstawowych interakcji z interfejsem Data API przy użyciu biblioteki klienta Zend Google Data API. 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. Używanie magicznych metod dostępu i ustawienia
   4. Inne materiały
3. Uwierzytelnianie w usłudze Blogger
   1. Uwierzytelnianie OAuth
   2. Uwierzytelnianie proxy AuthSub
   3. 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 klienckie PHP, 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 PHP. 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 Zend wymaga PHP w wersji 5.1.4 lub nowszej. Jest on dostępny w ramach Zend Framework, a także jako oddzielny plik do pobrania. Aby korzystać z Bloggera, użyj biblioteki klienta w wersji 1.0.0 lub nowszej.

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łny działający przykładowy klient zawierający cały przykładowy kod pokazany w tym dokumencie jest dostępny w repozytorium SVN Zend Framework. Plik znajduje się w katalogu /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ład lub napiszesz własny kod za pomocą Zend Framework, konieczne może być ustawienie zmiennej include_path i załadowanie odpowiednich klas. Ścieżka include może być ustawiana za pomocą ustawienia php.ini lub za pomocą metody set_include_path. Ten kod prosi o dostęp do podstawowej klasy Zend_Gdata, klasy Zend_Gdata_Query oraz 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');

Używanie magicznych metod get i set

W całej bibliotece klienta PHP dodano obsługę magicznych setterów/getterów, aby ułatwić pracę programistom. Dzięki nim można bezpiecznie uzyskiwać dostęp do właściwości klasy za pomocą tradycyjnych metod setter/getter lub przez dostęp do właściwości. Jeśli na przykład $gdataObject jest wystąpieniem obiektu w tej bibliotece, te 2 wiersze kodu mają identyczne działanie:

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

Te 2 wiersze kodu mają też identyczne działanie:

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

Podobnie magiczne metody fabryki ułatwiają deklarowanie nowych obiektów. Zamiast zapamiętywać długie nazwy klas wymagane przez konwencję nazewnictwa Zend, możesz utworzyć nową klasę object, wywołując funkcję newObject(); w kliencie usługi Zend. Na przykład oba podane niżej fragmenty kodu deklarują nowy obiekt rozszerzenia draft. Więcej informacji o drafts znajdziesz w sekcji Tworzenie posta.

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

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

Magiczne metody setter/getter i fabryk są opcjonalne, więc użyj tego podejścia, które najbardziej Ci odpowiada.

Inne zasoby

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

• Dokumentacja referencyjna
• Informacje o liście adresowej i archiwach
• Informacje o Subversion w Zend Framework
• Zrzuty Zend Framework w wersji Nightly

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 się uwierzytelnić za pomocą dowolnego z 3 podejść: uwierzytelniania OAuth, uwierzytelniania serwera proxy AuthSub lub uwierzytelniania ClientLogin za pomocą nazwy użytkownika i hasła.

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

uwierzytelnianie OAuth,

Dokumentację dotyczącą uwierzytelniania OAuth za pomocą biblioteki Zend PHP GData znajdziesz w artykule OAuth w bibliotekach klienta interfejsu Google Data Protocol.

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 Zend udostępnia funkcję generowania adresu URL strony Google. Poniższy kod pobiera adres 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 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). 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.

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

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

Ta wartość tokena reprezentuje token AuthSub jednorazowego użytku. W tym przykładzie, ponieważ określono parametr $session = true, token ten można zamienić 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ż obecny. Jeśli nie, ale w adresie URL podany jest token jednorazowego użytku, fragment kodu przekazuje do metody getAuthSubSessionToken token jednorazowego użytku, a interfejs AuthSub zwraca token sesji. Następnie kod umieszcza wartość tokenu sesji w zmiennej sesji $_SESSION['sessionToken'].

Twoja aplikacja może następnie używać wartości tokena sesji w kolejnych interakcjach z Bloggerem. Za pomocą metody Zend_Gdata_AuthSub::getHttpClient możesz uzyskać obiekt Zend_Http_Client, który ma wstępnie ustawiony nagłówek Authorization, aby uwzględnić poświadczenia AuthSub:

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

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

Poniższy kod używa metody Zend_Gdata_ClientLogin::getHttpClient do wykonania żądania do usługi ClientLogin, pobrania tokena uwierzytelniania i utworzenia obiektu Zend_Http_Client z odpowiednim nagłówkiem uwierzytelniania. Następnie obiekt HttpClient zwrócony przez tę metodę jest używany do tworzenia obiektu usługi Zend_Gdata.

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

$user = '[e-mail]';
$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 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 $gdClient do pobierania metadanych, a następnie wyświetla tytuł każdego bloga.

Klasa Zend_Gdata_Query odpowiada za tworzenie adresu URL zapytania. W tym przypadku nie trzeba nic robić, ale użyteczność klasy Query stanie się widoczna w sekcji pobieranie postów na podstawie 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. 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.

Fragment kodu poniżej pokazuje, jak wyodrębnić identyfikator bloga z kanału. Aby tworzyć, aktualizować i usuwać posty i komentarze, musisz podać identyfikator bloga. Zmienna $index wskazuje, który blog z kanału RSS jest używany przez użytkownika. Pole id ma postać tag:blogger.com,1999:user-userID.blog-blogID, więc znak split w pozycji „-” umieszcza identyfikator bloga w ostatnim elemencie uzyskanej tablicy.

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

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

Aby publikować nowe wpisy w blogu, możesz użyć biblioteki klienta PHP.

Najpierw utwórz instancję wpisu, która będzie reprezentować post na blogu. Następnie możesz ustawić tytuł, treść i inne atrybuty posta na blogu. Na koniec wywołaj metodę insertEntry, aby wstawić post. Możesz tu zobaczyć, jak działają magiczne instancje fabryki, korzystające z nowych obiektów 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

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

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 podobny sposób jak w przypadku tytułu lub treści wpisu możesz utworzyć nowe obiekty Zend_Gdata_App_Extension_Control i Zend_Gdata_App_Extension_Draft oraz przypisać je do atrybutu kontroli wpisu.

Aby przekształcić istniejący szkic posta na blogu w opublikowany post, pobierz szkic posta, ustaw atrybut szkicu na no, a następnie zaktualizuj 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 ustawiać danych logowania 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:

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 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. W tym celu utwórz obiekt zapytania i przekaż go do metody getFeed.

Aby na przykład wysłać zapytanie dotyczące zakresu dat, ustaw parametry published-min i published-max obiektu zapytania. Ten fragment kodu drukuje tytuł i treści każdego posta na blogu opublikowanego w okresie od podanego czasu rozpoczęcia do podanego czasu 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(), która wyświetla utworzony zakodowany adres URL.

Uwaga: obecnie nie ma magicznych ustawień parametrów zapytań published-min i published-max. Możesz jednak użyć setStartIndex i setMaxResults.

Interfejs Blogger Data API obsługuje te parametry zapytania:

kategorie

Określa kategorie (zwane też etykietami) służące do filtrowania wyników w pliku danych. Na przykład 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.

published-min, published-max

Granice dat publikacji wpisów.

start-index

Indeks pierwszego wyniku, który ma zostać pobrany (dla pobierania stron).

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 save. Podany niżej fragment kodu zmienia tytuł i treść wpisu na blogu, zakładając, że został on 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: 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 $gdClient w ten sposób:

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

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:

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 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 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ż pobrać komentarze do wszystkich postów, korzystając z adresu URL kanału komentarzy bloga:

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

Usuwanie komentarzy

Aby usunąć komentarz, prześlij adres URL edycji komentarza do metody delete obiektu $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