Przewodnik dla programistów: PHP

Interfejs API danych Bloggera umożliwia aplikacjom klienckim wyświetlanie i aktualizowanie treści z Bloggera w postaci kanałów interfejsu API danych Google.

Aplikacja kliencka może używać interfejsu Blogger Data API do tworzenia nowych postów na blogu, edytowania i usuwania dotychczasowych postów oraz wysyłania zapytań dotyczących postów na blogu odpowiadających konkretnym kryteriom.

Znajdziesz w nim nie tylko informacje o możliwościach interfejsu API danych Bloggera, ale także przykłady podstawowych interakcji z interfejsem Data API za pomocą biblioteki klienta Data API. Jeśli chcesz dowiedzieć się więcej o podstawowym protokole, z którego korzysta biblioteka, zapoznaj się z sekcją Protokoł w tym przewodniku.

Spis treści

1. Odbiorcy
2. Pierwsze kroki
   1. Tworzenie konta Bloggera
   2. Uruchamianie przykładowego kodu
   3. Korzystanie z magicznych narzędzi do pobierania i parowania
   4. Inne materiały
3. Uwierzytelnianie w usłudze Blogger
   1. Uwierzytelnianie OAuth
   2. Uwierzytelnianie serwera proxy OAuthSub
   3. Uwierzytelnianie nazwy użytkownika i hasła klienta logowania
4. Pobieranie listy blogów
5. Tworzenie postów
   1. Publikowanie posta na blogu
   2. Tworzenie wersji roboczej posta na blogu
6. Pobieranie postów
   1. Pobieranie wszystkich postów na blogu
   2. Pobieranie postów z parametrami zapytania
7. Aktualizowanie postów
8. Usuwanie postów
9. Komentarze
   1. Tworzenie komentarzy
   2. Pobieranie komentarzy
   3. Usuwanie komentarzy

Odbiorców

Ten dokument jest przeznaczony dla programistów, którzy chcą tworzyć aplikacje klienckie PHP, które mogą współpracować z Bloggerem.

W tym dokumencie zakładamy, że rozumiesz ogólne pomysły związane z protokołem interfejsów API danych Google.

Więcej informacji o klasach i metodach dostępnych w bibliotece klienta znajdziesz w dokumentacji interfejsu API biblioteki klienta klienta PHP. Ogólne informacje o interfejsie API danych Bloggera znajdziesz w przewodniku po protokołach.

Pierwsze kroki

Aby uzyskać pomoc w konfigurowaniu biblioteki klienta, przeczytaj Przewodnik dla początkujących.

Biblioteka klienta Zend wymaga PHP w wersji 5.1.4 lub nowszej. Jest on dostępny w ramach platformy Zend, a także w osobnym pliku do pobrania. Aby wchodzić w interakcje z Bloggerem, używaj biblioteki klienckiej w wersji 1.0.0 lub nowszej.

Tworzenie konta w Bloggerze

Jeśli chcesz, możesz założyć konto w Bloggerze na potrzeby testów. Blogger korzysta z kont Google, więc jeśli masz już konto Google, masz wszystko gotowe.

Uruchamianie przykładowego kodu

W pełni działający działający przykładowy klient, który zawiera cały przykładowy kod widoczny w tym dokumencie, jest dostępny w repozytorium SVG w Zend Framework. Przykład znajdziesz w lokalizacji /framework/standard/trunk/demos/Zend/Gdata/Blogger.php. Przykład zawiera wszystkie funkcje opisane w tym dokumencie. Może być uruchomiony tylko z poziomu wiersza poleceń:

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

Zanim uruchomisz ten przykładowy kod lub utworzysz własny kod za pomocą ramki Zend, może być konieczne ustawienie include_path i wczytanie odpowiednich klas. Ścieżka „include” można ustawić przy użyciu ustawienia php.ini lub metody set_include_path. Ten kod prosi o dostęp do klasy podstawowej 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 narzędzi do pobierania i parowania

W bibliotece klienta PHP dodaliśmy ułatwienia dla deweloperów dotyczące magicznych narzędzi ustawiających i pobierania. Dzięki temu można bezpiecznie korzystać z właściwości klasy, korzystając z tradycyjnych metod ustawiania lub pobierania. Jeśli na przykład $gdataObject jest wystąpieniem obiektu w tej bibliotece, te 2 wiersze kodu mają identyczne efekty:

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

Podobnie 2 wiersze kodu mają identyczne skutki:

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

Analogicznie magiczne metody produkcji ułatwiają deklarowanie nowych obiektów. Zamiast zapamiętywać długie nazwy klasy wymagane w ramach konwencji nazewnictwa Zend, możesz utworzyć nową właściwość object, wywołując newObject(); w kliencie usługi Zend. Na przykład poniższe 2 fragmenty zadeklarują nowy obiekt rozszerzenia draft. Więcej informacji o sekcji drafts znajdziesz w sekcji tworzenia posta.

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

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

Magia osadzonych i fabryk jest opcjonalna, użyj więc najlepszego sposobu.

Inne zasoby

Inne zasoby komponentu Zend API w Zend (Zend_Gdata):

• Dokumentacja
• Informacje o liście adresowej i archiwa
• Informacje o wersji podrzędnej platformy Zend
• Zimowe zrzuty dysku bazowego środowiska

Uwierzytelnianie w usłudze Blogger

Za pomocą interfejsu Blogger Data API masz dostęp do kanałów publicznych i prywatnych. Publiczne kanały nie wymagają uwierzytelniania, ale są tylko do odczytu. Jeśli chcesz zmodyfikować blogi, klient musi uwierzytelnić się przed wysłaniem żądania prywatnych kanałów. Może uwierzytelniać się za pomocą dowolnej z tych 3 metod: OAuth, uwierzytelnianie AuthSub lub ClientLogin – uwierzytelnianie nazwy użytkownika lub hasła.

Więcej ogólnych informacji o uwierzytelnianiu za pomocą interfejsów Google Data API 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ę na temat uwierzytelniania OAuth przy użyciu biblioteki Zend PHP w usłudze Zend PHP znajdziesz w artykule o protokole OAuth w bibliotekach klienta protokołu danych Google.

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 ani hasła użytkownika Bloggera. Zamiast tego klient otrzymuje specjalne tokeny uwierzytelniania, które pozwalają klientowi działać w imieniu konkretnego użytkownika. Więcej informacji znajdziesz w dokumentacji AuthSub.

Gdy użytkownik po raz pierwszy odwiedzi Twoją aplikację, nie zostanie on jeszcze uwierzytelniony. W takim przypadku musisz wyświetlić pewne informacje i link kierujący użytkownika na stronę Google, aby uwierzytelnić prośbę o dostęp do bloga. Biblioteka klienta Zend umożliwia wygenerowanie adresu URL strony Google. Ten 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ą parametrom zapytania używanym przez moduł obsługi AuthSubRequest):

dalej

Adres URL strony, na którą Google ma przekierować użytkownika po uwierzytelnianiu.

zakres

Wskazuje, że aplikacja żąda tokena dostępu do kanałów Bloggera. Zakres zakresu do użycia to http://www.blogger.com/feeds/ (oczywiście zakodowany na potrzeby adresu URL).

Bezpieczny

Wskazuje, czy klient żąda bezpiecznego tokena.

sesja

Wskazuje, czy zwrócony token można wymienić na token wielokrotnego użytku (sesja).

W powyższym przykładzie podano wywołanie, które nie wymaga bezpiecznego tokena (wartość secure wynosi false). Powstały 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 prowadzący do witryny Google i uwierzytelnia się na koncie Google.

Gdy użytkownik się uwierzytelni, system AuthSub przekierowuje go do adresu URL określonego w parametrze zapytania next AuthSubRequest. System AuthSub dodaje do tego adresu URL token uwierzytelniający jako wartość parametru zapytania token. Przykład:

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

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

Ta wartość odpowiada pojedynczemu tokenowi AuthSub. W tym przykładzie, ponieważ określono $session = true, ten token 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 już istnieje. Jeśli jest inny, ale w adresie URL określono token jednorazowy, fragment kodu przekazuje token jednorazowy do metody getAuthSubSessionToken, a interfejs AuthSub zwraca token sesji. Kod umieszcza wartość tokena sesji w zmiennej sesji $_SESSION['sessionToken'].

Aplikacja może następnie użyć wartości tokena sesji w kolejnych interakcjach z Bloggerem. Możesz użyć metody Zend_Gdata_AuthSub::getHttpClient, aby uzyskać obiekt Zend_Http_Client z gotowym nagłówkiem Authorization do uwzględnienia danych logowania AuthSub:

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

Uwierzytelnianie nazwy użytkownika i hasła klienta

Użyj uwierzytelniania ClientLogin, jeśli klient jest oddzielnym klientem (instalowanym przez klienta (np. aplikacją komputerową).

Poniższy kod wykorzystuje metodę Zend_Gdata_ClientLogin::getHttpClient do wykonywania żądań do usługi ClientLogin, pobierania tokena uwierzytelniania i tworzenia obiektu Zend_Http_Client z odpowiednim nagłówkiem uwierzytelniania. Następnie obiekt HttpClient zwrócony przez tę metodę służy do tworzenia obiektu usługi Zend_Gdata.

Zwróć uwagę, że właściwość $accountType jest wyraźnie ustawiona na GOOGLE. Jeśli nie ustawisz 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ładowych żądaniach i odpowiedziach, znajdziesz w dokumentacji dotyczącej uwierzytelniania zainstalowanych aplikacji.

Uwaga: użyj tego samego tokena dla wszystkich żądań w określonej sesji. Nie zdobywaj nowego tokena dla każdego żądania Bloggera.

Uwaga: jak opisano w dokumentacji ClientLogin, żądanie uwierzytelniania może się nie powieść i zażądać testu CAPTCHA. Jeśli chcesz, aby test CAPTCHA był przeprowadzany i obsługiwany przez tę funkcję, wyślij użytkownika na adres https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger (zamiast na adres URL obsługi CAPTCHA podany w dokumentacji ClientLogin).

Pobieranie listy blogów

Interfejs Blogger Data API zapewnia kanał z listą blogów wybranego użytkownika. Ten kanał jest nazywany „"metafeed."

Przykładowy kod używa uwierzytelnionego obiektu $gdClient do pobrania metatagu, a następnie drukuje każdy tytuł bloga.

Klasa Zend_Gdata_Query odpowiada za utworzenie adresu URL zapytania. W takim przypadku nie musisz nic robić, ale przydatność klasy Query stanie się 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 w metodzie getFeed. Jest to domyślny adres URL metatagu, który zawiera listę blogów aktualnie uwierzytelnionego użytkownika. Aby uzyskać dostęp do kanału innego użytkownika, możesz umieścić w metatagu adres URL identyfikatora użytkownika 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. Będzie on potrzebny do wykonywania operacji tworzenia, aktualizowania i usuwania postów oraz komentarzy. Zmienna $index reprezentuje blog, który jest używany w kanale bloga użytkownika. Pole id przyjmuje postać tag:blogger.com,1999:user-userID.blog-blogID, więc znak split na stronie '-' identyfikator bloga umieszcza w ostatnim elemencie tablicy.

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

Tworzenie postów

Interfejs API danych Bloggera umożliwia tworzenie i publikowanie nowych postów w blogach oraz tworzenie wersji roboczych wpisów.

Uwaga: ustawianie niestandardowego autora postów jest obecnie niemożliwe. Wszystkie nowe wpisy będą wyglądać tak, jakby zostały utworzone przez aktualnie uwierzytelnionego użytkownika.

Publikowanie posta na blogu

Jeśli chcesz opublikować nowy wpis, możesz użyć biblioteki klienta PHP.

Najpierw utwórz instancję wpisu reprezentującą posta na blogu. Następnie możesz ustawić tytuł, treść i inne atrybuty posta na blogu. Na koniec wywołaj metodę insertEntry, aby wstawić posta. Tutaj możesz zobaczyć, jak działają magiczne wystąpienia instancji fabrycznych 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 są tworzone w taki sam sposób jak posty publiczne, ale musisz ustawić atrybut wersji roboczej obiektu wpisu. Możesz utworzyć posta na blogu (tak jak ten powyżej) jako wersję roboczą, 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];
}

Zasadniczo tworzy się tytuły i treści postów oraz tworzysz nowe obiekty Zend_Gdata_App_Extension_Control i Zend_Gdata_App_Extension_Draft i przypisuj je do atrybutu elementu sterującego wpisu.

Możesz zmienić istniejącego posta w blogu w opublikowany post, pobierając wersję roboczą posta, ustawiając atrybut wersji roboczej na no, a następnie aktualizując posta. W kolejnych 2 sekcjach omówimy pobieranie i aktualizowanie postów.

Pobieram posty

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

Do zapytań dotyczących publicznych kanałów Bloggera możesz wysyłać zapytania bez uwierzytelniania. W związku z tym nie musisz ustawiać danych logowania ani uwierzytelniać się w AuthSub przed pobieraniem postów z publicznego bloga.

Pobieranie wszystkich postów na blogu

Aby pobrać posty użytkownika, użyj tej samej metody getFeed w celu pobrania metatagu kanału, ale tym razem wyślij URL kanału:

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 z wykorzystaniem parametrów zapytania

Interfejs API danych Bloggera umożliwia żądanie zestawu wpisów spełniających określone kryteria, takich jak żądania postów opublikowanych na blogu lub opublikowanych w danym zakresie dat. Aby to zrobić, 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 powoduje wyświetlanie tytułu i treści każdego posta na blogu między określonymi godzinami rozpoczęcia i 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 w przypadku klasy Zend_Gdata_Query jest getQueryUrl(), która pokazuje zakodowany adres URL.

Uwaga: obecnie nie ma żadnych magicznych ustawień dla parametrów zapytania published-min i published-max. Możesz jednak użyć 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 pliku danych. Na przykład http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie zwraca wpisy z etykietami Fritz i Laurie.

wyniki-maksymalne

Maksymalna liczba elementów do zwrócenia.

opublikowanych, minut:-max

Limity dat publikacji wpisów.

indeks-początkowy

Indeks oparty na 1 pierwszym wyniku do pobrania (na potrzeby stronicowania).

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

Aktualizowanie postów

Aby zaktualizować istniejącego posta na blogu, najpierw pobierz wpis, który chcesz zaktualizować, zmodyfikuj go, a następnie wyślij do Bloggera za pomocą metody save. Ten fragment kodu powoduje zmianę tytułu i treści posta na blogu przy założeniu, ż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ąć posta, przekaż jego adres URL do metody delete w obiekcie $gdClient. Przykład:

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 (także 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 komentarze można publikować tylko na blogu należącym do uwierzytelnionego użytkownika.

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

Pobieranie komentarzy

Możesz pobrać komentarze do konkretnego posta z 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ż wyświetlić komentarze ze wszystkich postów, korzystając z adresu URL kanału komentarzy:

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

Usuwanie komentarzy

Aby usunąć komentarz, przekaż jego URL edycji do metody delete w obiekcie $gdClient w następujący 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