開發人員指南:PHP

Blogger Data API 可讓用戶端應用程式以 Google Data API 動態消息的形式查看及更新 Blogger 內容。

您的用戶端應用程式可以使用 Blogger Data API 建立新的網誌文章、編輯或刪除現有的網誌文章,以及查詢符合特定條件的網誌文章。

除了提供 Blogger Data API 功能的相關背景資訊,這份文件也提供使用 Zend Google Data API 用戶端程式庫進行基本 Data API 互動的範例。如要進一步瞭解程式庫使用的基礎通訊協定,請參閱本開發人員指南的「通訊協定」一節。

目錄

目標對象

本文件適用於想編寫可與 Blogger 互動的 PHP 用戶端應用程式的程式設計師。

本文件假設您瞭解 Google Data API 通訊協定背後的一般概念。

如要參考用戶端程式庫提供的類別和方法,請參閱 PHP 用戶端程式庫 API 參考資料。如需一般 Blogger Data API 參考資訊,請參閱Protocol 參考指南

開始使用

如需用戶端程式庫設定的相關說明,請參閱入門指南

Zend 用戶端程式庫需要 PHP 5.1.4 以上版本。可在 Zend Framework 中使用,也可以單獨下載。如要與 Blogger 互動,請使用用戶端程式庫的 1.0.0 以上版本。

建立 Blogger 帳戶

建議您註冊 Blogger 帳戶進行測試。Blogger 使用 Google 帳戶,因此只要您已有 Google 帳戶,即可開始使用。

執行程式碼範例

您可以在 Zend Framework SVN 存放區中找到完整的運作範例用戶端,其中包含本文所示的所有程式碼範例。範例位於 /framework/standard/trunk/demos/Zend/Gdata/Blogger.php。範例包含本文件中說明的所有函式。只能透過指令列執行:

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

在執行這個範例或使用 Zend Framework 開發自己的程式碼之前,您可能需要設定 include_path 並載入適當的類別。您可以使用 php.ini 設定set_include_path 方法設定包含路徑。這段程式碼會要求存取核心 Zend_Gdata 類別、Zend_Gdata_Query 類別和驗證類別 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');

使用魔術 getter 和 setter

在整個 PHP 用戶端程式庫中,我們已新增魔法 setter/getter 支援功能,方便開發人員使用。這些方法可讓您使用傳統的 setter/getter 方法,或透過存取屬性,安全地存取類別的屬性。舉例來說,如果 $gdataObject 是這個程式庫中物件的例項,則下列兩行程式碼的效果相同:

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

同樣地,這兩行程式碼的效果也相同:

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

同樣地,魔法工廠方法可讓您更輕鬆地宣告新物件。您不必記住 Zend 命名慣例規定的長類別名稱,只要在 Zend 服務用戶端上呼叫 newObject();,即可建立新的 object。舉例來說,以下兩個程式碼片段都會宣告新的 draft 擴充功能物件。您可以在「建立貼文」一節中,進一步瞭解 drafts

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

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

魔術 setter/getter 和工廠是選用項目,因此請使用最適合您的方法。

其他資源

Zend Framework 的 Google Data API 元件 (Zend_Gdata) 的其他資源:

向 Blogger 服務進行驗證

您可以使用 Blogger Data API 存取公開和私人動態消息。公開動態饋給不需要任何驗證,但為唯讀。如果您想修改網誌,則您的用戶端必須先驗證,才能要求私人動態饋給。可使用以下三種驗證方式:OAuth 驗證、AuthSub 代理驗證或 ClientLogin 使用者名稱/密碼驗證。

如要進一步瞭解一般使用 Google Data API 的驗證方式,請參閱驗證說明文件

本文後續章節中的大部分範例都假設您擁有名為 $gdClient 的已驗證用戶端物件。

OAuth 驗證

如需使用 Zend PHP GData 程式庫進行 OAuth 驗證的說明文件,請參閱「Google Data Protocol 用戶端程式庫中的 OAuth」。

AuthSub Proxy 驗證

需要對使用者進行 Google 帳戶驗證的網頁應用程式,會使用 AuthSub 代理驗證。網站操作員和用戶端程式碼無法存取 Blogger 使用者的使用者名稱和密碼;而是取得特殊的 AuthSub 權杖,讓用戶端可以代表特定使用者採取行動。如需詳細資訊,請參閱 AuthSub 說明文件

使用者首次造訪應用程式時,尚未完成驗證程序。在這種情況下,您需要顯示一些資訊和連結,引導使用者前往 Google 頁面,驗證您要求存取其網誌的權限。Zend 用戶端程式庫提供函式,可產生 Google 網頁的網址。以下程式碼會擷取 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>';

getAuthSubTokenUri 方法會採用下列參數 (對應至 AuthSubRequest 處理常式使用的查詢參數):

下一個
Google 應在驗證程序後將使用者重新導向至的網頁網址。
範圍
表示應用程式要求存取 Blogger 動態消息的權杖。要使用的範圍字串是 http://www.blogger.com/feeds/ (當然已編碼為網址)。
安全
指出用戶端是否要求安全權杖。
工作階段
指出是否可以將傳回的權杖換成多用途 (工作階段) 權杖。

上述範例顯示的呼叫不會要求安全權杖 (secure 的值為 false)。產生的要求網址可能如下所示:

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

使用者點選連結前往 Google 網站,並驗證 Google 帳戶。

使用者完成驗證後,AuthSub 系統會將他們重新導向至您在 AuthSubRequest 網址的 next 查詢參數中指定的網址。AuthSub 系統會將驗證權杖附加到該網址,做為 token 查詢參數的值。例如:

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

您可以使用 $_GET['token'] 擷取權杖值。

這個權杖值代表單次使用的 AuthSub 權杖。在這個範例中,由於已指定 $session = true,因此可以使用 Zend_Gdata_AuthSub::getAuthSubSessionToken 方法,將這個權杖換成 AuthSub 工作階段權杖,該方法會呼叫 AuthSubSessionToken 服務:

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

程式碼程式碼片段會先檢查是否已提供 AuthSub 工作階段權杖。如果沒有,但網址中指定了一次性權杖,程式碼片段會將一次性權杖傳遞至 getAuthSubSessionToken 方法,而 AuthSub 介面會傳回工作階段權杖。接著,程式碼會將工作階段權杖值放入工作階段變數 $_SESSION['sessionToken'] 中。

之後,應用程式就能在與 Blogger 的後續互動中使用工作階段權杖值。您可以使用 Zend_Gdata_AuthSub::getHttpClient 方法取得具有 Authorization 標頭預設值的 Zend_Http_Client 物件,以便納入 AuthSub 憑證:

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

ClientLogin 使用者名稱/密碼驗證

如果用戶端是獨立的單一使用者「已安裝」用戶端 (例如桌面應用程式),請使用 ClientLogin 驗證。

以下程式碼會使用 Zend_Gdata_ClientLogin::getHttpClient 方法執行對 ClientLogin 服務的要求、擷取驗證權杖,並使用適當的驗證標頭建立 Zend_Http_Client 物件。接著,這個方法傳回的 HttpClient 會用於建構 Zend_Gdata 服務物件。

請注意,$accountType 已明確設為 GOOGLE。如果未設定這項參數,G Suite 使用者將無法順利使用 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);

如要進一步瞭解 ClientLogin 驗證,包括要求和回應範例,請參閱「已安裝應用程式的驗證」說明文件。

注意:請在特定工作階段中,針對所有要求使用相同的符記;不要為每項 Blogger 要求取得新的符記。

注意:如 ClientLogin 說明文件所述,驗證要求可能會失敗,並要求人機驗證 (CAPTCHA) 挑戰。如果您希望 Google 發出並處理人機驗證挑戰,請將使用者導向 https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger (而非 ClientLogin 說明文件中提供的人機驗證處理網址)。

擷取網誌清單

Blogger Data API 提供的動態饋給會列出特定使用者的網誌,這類動態饋給稱為「metafeed」。

以下程式碼範例會使用已驗證的 $gdClient 物件擷取 metafeed,然後列印每個網誌的標題。

Zend_Gdata_Query 類別會負責建構查詢網址。在這種情況下,您不需要執行額外作業,但 Query 類別的用途將在本文的「根據查詢參數擷取貼文」一節中變得明顯。

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++;
  }
}

請記下 getFeed 方法使用的網址。這是預設的 metafeed 網址,會傳回目前已驗證使用者的部落格清單。如要存取其他使用者的動態饋給,您可以在動態饋給網址中將使用者 ID 代入 default。使用者 ID 是指使用者個人資料網址結尾的數字字串。

以下程式碼片段示範如何從動態饋給中擷取網誌 ID。您需要網誌 ID,才能對貼文和留言執行建立、更新和刪除作業。$index 變數代表使用者在使用者網誌動態中使用的網誌。id 欄位的格式為 tag:blogger.com,1999:user-userID.blog-blogID,因此 '-' 字元上的 split 會將網誌 ID 放在結果陣列的最後一個元素中。

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

建立貼文

您可以使用 Blogger Data API 建立及發布新的網誌文章,以及建立文章草稿。

注意:目前不支援為貼文設定自訂作者。所有新貼文都會顯示為由目前已驗證的使用者建立。

發布網誌文章

您可以使用 PHP 用戶端程式庫發布新的網誌文章。

首先,請建立項目例項來代表網誌文章。接著,您可以設定網誌文章的標題、內容和其他屬性。最後,請呼叫 insertEntry 方法插入文章。您可以在這裡看到魔術工廠例項化的運作情形,包括新的 Zend_Gdata_EntryZend_Gdata_App_Extension_TitleZend_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;
}

建立網誌文章草稿

草稿文章的建立方式與公開文章相同,但您需要設定項目物件的草稿屬性。您可以建立類似上述的草稿網誌文章,方法是加入醒目顯示的文字行:

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];
}

您可以建立新的 Zend_Gdata_App_Extension_ControlZend_Gdata_App_Extension_Draft 物件,並將其指派給項目的控制項屬性,這與設定文章標題或內容的方式非常相似。

您可以擷取草稿網誌文章、將草稿屬性設為 no,然後更新文章,將現有的草稿網誌文章轉換為已發布的文章。我們將在接下來兩個部分介紹如何擷取及更新貼文。

擷取貼文

以下各節說明如何擷取包含或不包含查詢參數的部落格文清單。

您可以查詢 Blogger 公開動態饋給,無須驗證。因此,您無須先設定憑證或執行 AuthSub 驗證,即可從公開網誌擷取文章。

擷取所有網誌文章

如要擷取使用者的貼文,請呼叫用於擷取網誌中繼動態的 getFeed 方法,但這次請傳送網誌貼文動態的網址:

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

使用查詢參數擷取貼文

您可以使用 Blogger Data API 要求符合指定條件的一組項目,例如要求在特定日期範圍內發布或更新的網誌文章。如要這麼做,請建立查詢物件,並將其傳遞至 getFeed 方法。

舉例來說,如要傳送日期範圍查詢,請設定查詢物件的 published-minpublished-max 參數。下列程式碼片段會列印在指定開始時間和結束時間之間發布的每篇網誌文章的標題和內容:

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);
}

Zend_Gdata_Query 類別的實用偵錯方法是 getQueryUrl(),可顯示已建構的已編碼網址。

注意:目前 published-minpublished-max 查詢參數沒有魔法 setter。不過,您可以使用 setStartIndexsetMaxResults

Blogger Data API 支援下列查詢參數:

類別
指定用於篩選動態饋給結果的類別 (也稱為標籤)。舉例來說,http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie 會傳回標籤為 FritzLaurie 的項目。
max-results
要傳回的項目數量上限。
published-min、published-max
項目發布日期的邊界。
start-index
要擷取的第一個結果的索引 (以 1 為起點) (用於分頁)。

如要進一步瞭解查詢參數,請參閱 Blogger Data API 參考指南Google Data API 參考指南

更新貼文

如要更新現有的網誌文章,請先擷取要更新的項目,然後修改該項目,再使用 save 方法將其傳送至 Blogger。以下程式碼片段會修改部落格文章的標題和內容,假設您已從伺服器擷取文章。

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;
}

注意:目前不支援修改與貼文相關聯的作者資料。

刪除貼文

如要刪除貼文,請將貼文的編輯網址傳遞至 $gdClient 物件的 delete 方法,如下所示:

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

留言

Blogger Data API 可用於建立、擷取及刪除留言。不支援更新留言 (網頁介面也不支援)。

建立註解

如要發布留言,請建立項目物件,並按照下列方式插入:

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; 
}

注意:目前您只能在已驗證使用者擁有的網誌上張貼留言。

注意:目前不支援為留言設定自訂作者。所有新留言都會顯示為由目前已驗證的使用者建立。

擷取留言

您可以透過貼文的留言動態饋給網址,擷取特定貼文的留言:

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);
}

或者,您也可以使用網誌的留言動態消息網址,取得所有貼文的留言:

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

刪除留言

如要刪除留言,請將留言的編輯網址傳遞至 $gdClient 物件的 delete 方法,如下所示:

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

返回頁首