開發人員指南：PHP

Blogger Data API 可讓用戶端應用程式查看及更新 Google Data API 資訊提供形式的 Blogger 內容。

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

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

目錄

1. 觀眾
2. 開始使用
   1. 建立 Blogger 帳戶
   2. 執行程式碼範例
   3. 使用魔術 getter 和 setter
   4. 其他資源
3. 驗證 Blogger 服務
   1. OAuth 驗證
   2. AuthSub Proxy 驗證
   3. ClientLogin 使用者名稱/密碼驗證
4. 擷取網誌清單
5. 建立貼文
   1. 發布網誌文章
   2. 建立網誌文章草稿
6. 擷取訊息
   1. 擷取所有網誌文章
   2. 使用查詢參數擷取貼文
7. 更新貼文
8. 刪除訊息
9. 留言
   1. 建立留言
   2. 擷取註解
   3. 刪除留言

觀眾

本文件的適用對象為想編寫能夠與 Blogger 互動的 PHP 用戶端應用程式的程式設計人員。

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

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

開始使用

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

Zend 用戶端程式庫需要 PHP 5.1.4 以上版本。此套件可包含在 Zend 架構中，並以獨立下載的形式提供。如要與 Blogger 互動，請使用 1.0.0 以上版本的用戶端程式庫。

建立 Blogger 帳戶

你可以註冊 Blogger 帳戶，以便進行測試。Blogger 會使用 Google 帳戶，因此如果您已經有 Google 帳戶，就大功告成了。

執行程式碼範例

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

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

在執行本範例或使用 Zend 架構開發自己的程式碼之前，您可能需要設定 include_path 並載入適當的類別。您可以使用 php.ini 設定或 set_include_path 方法來設定 include 路徑。這個程式碼要求存取核心 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 用戶端程式庫中，我們為 magic setters/getters 新增支援，方便開發人員使用。這些類別可允許透過傳統的 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();

魔術設定器/getter 和工廠為選用，因此請選用最適合您的方法。

其他資源

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

• 參考說明文件
• 郵寄清單資訊與封存
• Zend Framework Subversion 資訊
• Zend 架構夜間快照

驗證 Blogger 服務

您可以使用 Blogger Data API 存取公開和私人動態消息。 公開動態消息不需驗證，但目前處於唯讀狀態。如要修改網誌，則客戶必須先完成驗證，才能要求私人動態消息。它可以使用下列三種方法進行驗證：OAuth 驗證、AuthSub Proxy 驗證或 ClientLogin 使用者名稱/密碼驗證。

如要進一步瞭解 Google Data API 驗證的一般資訊，請參閱驗證說明文件。

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

OAuth 驗證

如需使用 Zend PHP GData 程式庫進行 OAuth 驗證的說明文件，請參閱 Google Data 通訊協定用戶端程式庫中的 OAuth。

AuthSub Proxy 驗證

需要向 Google 帳戶驗證使用者的網頁應用程式會使用 AuthSub Proxy 驗證。網站營運商和用戶端程式碼無法存取 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 = '[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);

如要進一步瞭解 ClientLogin 驗證，包括要求與回應範例，請參閱安裝版應用程式的驗證說明文件。

注意：針對特定工作階段中的所有要求使用相同符記；不要為每個 Blogger 要求取得新符記。

注意：如 ClientLogin 說明文件所述，驗證要求可能會失敗，並要求進行人機驗證 (CAPTCHA) 驗證問題。如要讓 Google 發出並處理人機驗證 (CAPTCHA) 驗證問題，請將使用者傳送至 https://www.google.com/accounts/DisplayUnlockCaptcha?service=blogger (而不是用戶端登入說明文件中的人機驗證 (CAPTCHA) 處理網址)。

擷取網誌清單

Blogger Data API 提供的資訊提供會列出特定使用者的網誌；該資訊提供稱為「中繼資訊提供」。

下列程式碼範例使用經過驗證的 $gdClient 物件擷取中繼動態饋給，然後列印每個網誌的標題。

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 方法使用的網址。這是預設的中繼動態饋給網址，它會傳回目前已驗證使用者的網誌清單。如要存取其他使用者的動態消息，您可以在中繼動態饋給網址中，將使用者 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_Entry、Zend_Gdata_App_Extension_Title 和 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;
}

建立網誌文章草稿

草稿貼文的建立方式與公開貼文相同，但您需要設定項目物件的草稿屬性。您可以加上醒目顯示的程式碼行，將上述文章寫成草稿：

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_Control 和 Zend_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-min 和 published-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);
}

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

注意：published-min 和 published-max 查詢參數目前目前沒有魔術 setter。不過，您可以使用 setStartIndex 和 setMaxResults。

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

categories

指定類別 (也稱為標籤) 來篩選動態饋給結果。舉例來說，http://www.blogger.com/feeds/blogID/posts/default/-/Fritz/Laurie 會傳回同時具有 Fritz 和 Laurie 標籤的項目。

max-results

要傳回的項目數量上限。

Publishing-min、publish-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);
}

返回頁首