開發人員指南：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 Proxy 驗證

觀眾

這份文件的適用對像是想編寫可與 Blogger 互動的 JavaScript 用戶端應用程式。其中提供一系列使用 JavaScript 用戶端程式庫的基本 Data API 互動範例。

如需 Blogger Data API 參考資料資訊，請參閱通訊協定參考指南。本文假設您瞭解 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 Maps API 使用的版本編號建立而成。以下是可能的版本編號及其代表：

"1"
主要版本 1 的次要版本。
"1.x"
主要版本 1 的最新版本。
"1.s"
主要版本 1 的最新穩定修訂版本。我們會不時參考開發人員提供的意見回饋，將特定版本的用戶端程式庫宣告為「穩定」。但這類穩定版本可能不提供最新功能。
"1.0"、"1.1等
特定版本的程式庫，具有指定的主要和次要修訂版本編號。

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

google.setOnLoadCallback(getMyBlogFeed);

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

驗證 Blogger 服務

使用 Blogger Data API 就能存取公開和私人的動態消息。 公開動態饋給不需要驗證，但處於唯讀狀態。如要修改網誌，則用戶端必須先進行驗證，才能要求私人動態饋給。

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

AuthSub Proxy 驗證

需要驗證使用者提供給 Google 帳戶的網頁應用程式會使用 AuthSub Proxy 驗證。網站運算子和用戶端代碼無法存取 Blogger 使用者的使用者名稱和密碼；用戶端則會取得特殊的 AuthSub 權杖，允許用戶端代表特定使用者採取行動。

以下簡要說明網頁式 JavaScript 用戶端驗證程序的相關事宜：

  1. 用戶端應用程式會呼叫用戶端程式庫提供的 google.accounts.user.login() 方法，並向其傳送「範圍」值，以指出要使用的 Google 服務。Blogger 的範圍是 "http://www.blogger.com/feeds/"。
  2. 用戶端程式庫會將瀏覽器傳送至 Google 的「存取要求」頁面，使用者可在該網站輸入憑證以登入服務。
  3. 如果使用者成功登入，AuthSub 系統會將瀏覽器傳回網路用戶端的網址，並傳送驗證權杖。
  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() 是函式。如果發生 init 錯誤，則函式會收到標準錯誤物件；您可以對該物件執行任何所需操作。

權杖在透過呼叫 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 驗證和 JavaScript 用戶端程式庫」文件。

返回頁首