開發人員指南：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() 是我們會在本文件後續章節中定義的函式。請使用這個方法，不要將 onload 處理常式附加至 <body> 元素。

驗證 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 錯誤，您的函式會收到標準 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」驗證功能文件。

返回頁首