開發人員指南：JavaScript

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

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

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

目錄

  1. 觀眾
  2. 使用條款
  3. 關於支援的環境
  4. 開始使用
    1. 建立 Blogger 帳戶
    2. 取得程式庫
  5. 驗證 Blogger 服務
    1. AuthSub 代理驗證

目標對象

本文件適用於想編寫可與 Blogger 互動的 JavaScript 用戶端應用程式的程式設計師。本文件提供一系列使用 JavaScript 用戶端程式庫進行基本 Data API 互動的範例。

如需 Blogger Data API 參考資訊，請參閱Protocol 參考指南。本文件假設您瞭解 Google Data API 通訊協定背後的一般概念，以及 JavaScript 用戶端程式庫使用的資料模型和控制流程。也假設您已瞭解如何以 JavaScript 編寫程式。

如要參考用戶端程式庫提供的類別和方法，請參閱 JavaScript 用戶端程式庫 API 參考資料。

本文件的設計是讓您依序閱讀，每個範例都以先前的範例為基礎。

使用條款

您同意在使用 JavaScript 用戶端程式庫時遵守 Google JavaScript 用戶端程式庫使用條款。

關於支援的環境

目前，我們只支援在瀏覽器網頁中執行的 JavaScript 用戶端應用程式。目前支援的瀏覽器為 Firefox 1.5 以上版本，以及 Internet Explorer 6.0 以上版本。

JavaScript 用戶端程式庫會處理與服務伺服器的所有通訊。如果您是經驗豐富的 JS 開發人員，可能會想問：「那麼同源政策呢？」JavaScript 用戶端程式庫可讓用戶端從任何網域傳送 Google Data API 要求，同時符合瀏覽器安全性模型。

開始使用

您必須先完成一些設定，才能取得程式庫，進而編寫 JavaScript 用戶端應用程式。

建立 Blogger 帳戶

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

取得程式庫

用戶端必須先向伺服器要求用戶端程式庫程式碼，才能使用用戶端程式庫。

首先，請在 HTML 文件的 <head> 區段中使用 <script> 標記，擷取 Google AJAX API 載入器：

<script type="text/javascript" src="https://www.google.com/jsapi"></script>

如要在擷取載入器後取得 Google Data API 用戶端程式庫，請在 JavaScript 設定程式碼中使用下列程式碼行，且必須從 HTML 文件的 <head> 部分呼叫 (或從 HTML 文件的 <head> 部分使用 <script> 標記所包含的 JavaScript 檔案呼叫)：

google.load("gdata", "1.x");

google.load() 的第二個參數是 JavaScript 用戶端程式庫的版本號碼。我們的版本編號系統是以 Google 地圖 API 的系統為藍本。以下是可能的版本號碼及其意義：

"1"
主要版本 1 的倒數第二個修訂版本。
"1.x"
主要版本 1 的最新修訂版本。
"1.s"
主要版本 1 的最新穩定修訂版。我們會根據開發人員提供的意見回饋，不時宣告某個版本的用戶端程式庫為「穩定版」。但這類穩定版本可能不提供最新功能。
"1.0"、"1.1"等
程式庫的特定版本，包含指定的主要和次要修訂版本號碼。

呼叫 google.load() 後，您必須告知載入器等待網頁載入完成，然後再呼叫程式碼：

google.setOnLoadCallback(getMyBlogFeed);

其中 getMyBlogFeed() 是我們將在本文件後續章節中定義的函式。請採用這個方法，而不要將 onload 處理常式附加至 <body> 元素。

向 Blogger 服務進行驗證

您可以使用 Blogger Data API 存取公開和私人動態消息。公開動態饋給不需要任何驗證，但為唯讀。如果您想修改網誌，則您的用戶端必須先驗證，才能要求私人動態饋給。

JavaScript 用戶端程式庫使用 AuthSub 驗證系統。如要進一步瞭解一般使用 Google Data API 的驗證方式，請參閱驗證說明文件。

AuthSub Proxy 驗證

需要對使用者進行 Google 帳戶驗證的網頁應用程式，會使用 AuthSub 代理驗證。網站操作員和用戶端程式碼無法存取 Blogger 使用者的使用者名稱和密碼；而是取得特殊的 AuthSub 權杖，讓用戶端可代表特定使用者採取行動。

以下簡要說明以網路為基礎的 JavaScript 用戶端在驗證程序期間發生的情況：

  1. 用戶端應用程式會呼叫用戶端程式庫提供的 google.accounts.user.login() 方法，並傳遞「範圍」值，指出要使用的 Google 服務。Blogger 的範圍為 "http://www.blogger.com/feeds/"。
  2. 用戶端程式庫會將瀏覽器傳送至 Google 的「存取要求」頁面，使用者可在該頁面輸入憑證，登入服務。
  3. 如果使用者成功登入，AuthSub 系統會將瀏覽器傳回至 Web 用戶端的網址，並傳遞驗證權杖。
  4. JavaScript 用戶端程式庫會將權杖儲存在 Cookie 中，並將控制權傳回至呼叫 google.accounts.user.login() 的用戶端應用程式函式。
  5. 當用戶端應用程式隨後呼叫與 Blogger 互動的用戶端程式庫方法時，用戶端程式庫會自動將權杖附加至所有要求。

注意：JavaScript 用戶端程式庫必須在網頁瀏覽器中提出經過驗證的 Blogger 要求，因此您的頁面必須包含與頁面同網域代管的圖片。可以是任何圖片，甚至是單像素透明圖片，但網頁上必須有圖片。如果您不希望圖片顯示在頁面上，可以使用 <img> 標記的 style 屬性，將圖片放在轉譯區域之外。例如：style="position:absolute; top: -1000px;"

以下是負責處理登入作業的用戶端應用程式程式碼。我們稍後會從其他程式碼呼叫 setupMyService() 函式。

function logMeIn() {
  scope = "http://www.blogger.com/feeds/";
  var token = google.accounts.user.login(scope);
}

function setupMyService() {
  var myService =
    new google.gdata.blogger.BloggerService('exampleCo-exampleApp-1');
  logMeIn();
  return myService;
}

提示：強烈建議您提供登入按鈕或其他使用者輸入機制，提示使用者手動啟動登入程序。相反地，如果您在載入後立即呼叫 google.accounts.user.login()，而未等待使用者互動，那麼使用者一進入網頁時，首先看到的會是 Google 登入頁面。如果使用者決定不登入，Google 就不會將他們重新導向至您的網頁；因此，從使用者的角度來看，他們嘗試造訪您的網頁，但系統並未將他們重新導向至該網頁。這種情況可能會讓使用者感到困惑和沮喪。在本文件的範例程式碼中，我們會在載入後立即呼叫 google.accounts.user.login()，以簡化範例，但我們不建議在實際用戶端應用程式中採用這種做法。

請注意，您不需要對名為 token 的變數執行任何操作；用戶端程式庫會追蹤權杖，因此您不必這麼做。

注意：建立新的 BloggerService 物件時，用戶端程式庫會呼叫名為 google.gdata.client.init() 的方法，該方法會檢查用戶端執行的瀏覽器是否受支援。如果發生錯誤，用戶端程式庫會向使用者顯示錯誤訊息。如果您想自行處理這類錯誤，可以在建立服務前明確呼叫 google.gdata.client.init(handleInitError)，其中 handleInitError() 是您的函式。如果發生初始化錯誤，函式會收到標準的 Error 物件，您可以對該物件執行任何操作。

您必須呼叫 google.accounts.user.logout() 才能撤銷權杖，否則權杖會一直有效：

function logMeOut() {
  google.accounts.user.logout();
}

如果您沒有呼叫 logout()，則儲存權杖的 Cookie 會保留兩年，除非使用者刪除。Cookie 會在瀏覽器工作階段之間保留，因此使用者可以關閉瀏覽器，然後重新開啟並返回您的用戶端，仍可登入。

不過，在某些特殊情況下，權杖可能會在工作階段期間失效。如果 Blogger 拒絕權杖，您的用戶端應透過呼叫 logout() 來移除含有目前權杖的 Cookie，然後再次呼叫 login() 來取得新的有效權杖，藉此處理錯誤狀況。

還有兩種 AuthSub 方法，可能在各種情境中派上用場：

  • google.accounts.user.checkLogin(scope) 會指出瀏覽器目前是否有指定範圍的驗證權杖。
  • google.accounts.user.getInfo() 會提供目前權杖的詳細資訊，供偵錯使用。

如要進一步瞭解如何使用 JavaScript 與 AuthSub 互動，包括權杖管理資訊，以及 checkLogin() 和 getInfo()，請參閱「使用 JavaScript 用戶端程式庫進行「AuthSub」驗證」一文。

返回頁首