開發人員指南：JavaScript

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

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

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

目錄

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

目標對象

本文件適用於想編寫可與 Blogger 互動的 JavaScript 用戶端應用程式的程式設計師。這個 API 提供一系列 使用 JavaScript 用戶端程式庫進行基本的資料 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 帳戶，即可開始使用。

取得程式庫

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

請先在<script> 您 HTML 文件的 <head> 部分，擷取 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() 是稍後會定義的函式 一節。請使用這個方法，而不是 onload 處理常式已附加至 <body> 元素。

驗證 Blogger 服務

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

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

AuthSub 代理程式驗證

需要驗證使用者 Google 帳戶的網頁應用程式，會使用 AuthSub 代理驗證。網站操作員和用戶端程式碼無法存取 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 要求，因此您的頁面必須包含與頁面同網域代管的圖片。可以是任何圖片，即使是 單一像素透明圖片，但網頁上必須有圖片。如果發生以下情況： 如果您希望圖片不顯示在網頁中，可以使用 style 將圖片放置在 <img> 標記外 算繪區域例如：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()，會檢查瀏覽器 系統支援用戶端的 IP 位址。如果發生錯誤，則為用戶端程式庫 向使用者顯示錯誤訊息若您想要處理這類錯誤 然後你可以明確呼叫 請google.gdata.client.init(handleInitError)，再建立 服務，其中 handleInitError() 代表函式。如果發生初始化錯誤，函式會收到標準的 Error 物件，您可以對該物件執行任何操作。

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

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

如果您未呼叫 logout()，那麼儲存 權杖的有效期限為兩年，除非使用者自行刪除。該 Cookie 會保留 因此使用者只要關閉瀏覽器再重新開啟 返回您的客戶，並保持登入狀態。

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

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

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

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

返回頁首