Blogger JSON API：開始使用

本文將說明如何開始使用 Blogger JSON API。

目錄

  1. 說明
  2. 事前準備
    1. 取得 Google 帳戶
    2. 熟悉 Blogger
    3. 瞭解如何授權要求及識別應用程式
  3. Blogger JSON API 背景
    1. Blogger 概念
    2. Blogger JSON API 資料模型
    3. Blogger JSON API 作業
  4. 通話樣式
    1. REST
  5. 資料格式
    1. JSON

引言

本文件的適用對象為想撰寫可與 Blogger JSON API 互動的應用程式。

Blogger JSON API 擴充了 Blogger Data API 2.0 版。如果您想要從 JSON 格式 (而非 XML 格式) 擷取 Blogger 資料，請使用 Blogger JSON API。如果您想要以 XML 格式擷取資料，請使用 Blogger Data API。

這個版本的 Blogger JSON API 目前為唯讀狀態，不過我們打算新增讀取/寫入等功能。歡迎前往 Blogger 說明論壇提出其他功能要求。

事前準備

建立 Google 帳戶

確認你已設定 Google 帳戶。建議您使用獨立的 Google 帳戶進行開發和測試，避免發生意外資料遺失的情況。如果您已有測試帳戶，則大功告成！請前往 Blogger 使用者介面設定、編輯或查看測試資料。

熟悉 Blogger

如果您不熟悉 Blogger 概念，請先閱讀本文件，並嘗試透過使用者介面開始編寫程式碼。這份文件假設您熟悉 Blogger、網頁程式程式設計和網站資料格式。

瞭解如何授權要求及識別應用程式

應用程式要求存取私人資料時，要求必須由可存取這些資料的已驗證使用者授權。

應用程式要求公開資料時，要求並不需要授權，但必須隨附 ID 等 ID 金鑰。

如要瞭解如何授權要求及使用 API 金鑰，請參閱「使用 API 文件授權」及識別應用程式。

Blogger JSON API 背景

Blogger 概念

Blogger 奠定以下五個基本概念：

  • 網誌：API 的根概念。網誌含有文章和網頁。這是網誌中繼資料 (例如網誌名稱和說明) 的容器。
  • 文章：網誌文章是網誌作者所建立的可發布項目。這項資訊不應即時，而是反映作者現在想向全世界發布的內容。據我們所知，網誌文章隨著時間推移，將會越來越不突兀，
  • 留言：網誌作者以外的留言是作者所撰寫內容的內容。從磚塊到花束，無所不包。
  • 頁面：頁面是靜態內容的位置，例如生物資訊，或是與使用者聯絡的方式。這通常是不具時效性的資訊，而且頻率通常不高。
  • 使用者：使用者是與 Blogger 互動的使用者，可做為作者、管理員或讀取者。如果是公開的網誌，讀者可能會選擇匿名網誌，而私人網誌則必須由 Blogger 辨識。

Blogger JSON API 資料模型

資源是具有專屬 ID 的個別資料實體。Blogger JSON API 支援五種資源：

  • 網誌資源：代表網誌。
  • Posts 資源：代表貼文；每則貼文資源是網誌資源的子項。
  • 留言資源：代表特定貼文的留言；每個留言資源都是貼文資源的子項。
  • Pages 資源：代表靜態網頁；[網頁資源] 是網誌資源的子項。
  • 使用者資源：代表非匿名的使用者。這項資訊可用來識別網頁、貼文或留言的作者。
網誌資源有兩種類型：網頁和文章。 貼文資源可以有留言資源子項。
資源之間的關係總覽

Blogger JSON API 資料模型是以資源集合稱為「集合」：

網誌集合
一個「ltltspanspanquoquot;apicollection">網誌集合」包含使用者有權存取的所有網誌，您可以依使用者列出網誌，或依 ID 擷取單一網誌。</spanoutlinequot;apicollection">
訊息集合
貼文集合包含特定網誌資源中的所有貼文資源。
產品素材資源集合
留言集合包含特定貼文資源中的所有留言資源。
網頁集合
網頁集合是由特定網誌資源中的所有網頁資源組成。
使用者集合
使用者集合是由 Blogger 上的所有使用者資源組成，因此無法列出。使用者可以透過 ID 或使用 ID self 擷取自己的使用者資源 (但其他人不得這麼做)。

Blogger JSON API 作業

您可以在 Blogger JSON API 中為集合和資源叫用兩種不同的方法，如下表所述。

Operation 說明 REST HTTP 對應
list 列出集合中的所有資源。 集合 URI 上的 GET。
取得 取得特定資源。 資源 URI 上的 GET。

下表列出各資源類型支援的方法。私人網誌的所有清單和 get 作業都需要驗證。

資源類型
支援的方法
清單 get
網誌 是 是
貼文 是 是
留言數 是 是
網頁 是 是
使用者 否 是

呼叫樣式

叫用 API 的方法有好幾種：

REST

REST 是一種軟體架構，可提供簡便且一致的資料要求及修改方法。

REST 為 Representational State Transfer (具象狀態傳輸) 的簡稱。在 Google 的 API 中，這是指使用 HTTP 動詞來擷取及修改 Google 儲存的資料表示法。

在符合 REST 樣式的系統中，資源會儲存在資料儲存庫中。用戶端向伺服器發出執行特定動作 (例如建立、擷取、更新或刪除資源) 的要求後，伺服器就會執行指定動作並傳回回應 (大多採用指定資源表示法的形式)。

在 Google 的 RESTful API 中，用戶端會使用 HTTP 動詞指定動作，例如 POST、GET、PUT 或 DELETE。並由下列格式的全域不重複 URI 指定資源：

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

由於所有 API 資源都有可供 HTTP 存取的專屬 URI，因此 REST 不僅能夠支援資料快取，也非常適合與網路的分散式基礎架構搭配運作。

HTTP 1.1 標準說明文件中的方法定義可能非常實用，其中包含 GET、POST、PUT 和 DELETE 的規格。

Blogger JSON API 中的 REST

支援的 Blogger 作業會直接對應至 REST HTTP 動詞，如 Blogger JSON API 作業中所述。

Blogger JSON API URI 的專屬格式為：

https://www.googleapis.com/blogger/v2/users/userId
https://www.googleapis.com/blogger/v2/users/self
https://www.googleapis.com/blogger/v2/users/userId/blogs
https://www.googleapis.com/blogger/v2/users/self/blogs

https://www.googleapis.com/blogger/v2/blogs/blogId/posts
https://www.googleapis.com/blogger/v2/blogs/blogId/posts/postId
https://www.googleapis.com/blogger/v2/blogs/blogId/posts/postId/comments
https://www.googleapis.com/blogger/v2/blogs/blogId/posts/postId/comments/commentId
https://www.googleapis.com/blogger/v2/blogs/blogId/pages
https://www.googleapis.com/blogger/v2/blogs/blogId/pages/pageId

Blogger JSON API 參考資料文件總結了使用的 URI 完整說明以及 API 中每個支援的作業的結果。

以下舉例說明在 Blogger JSON API 中的運作方式。

列出已驗證使用者有權存取的網誌：

GET https://www.googleapis.com/blogger/v2/users/self/blogs?key=YOUR-API-KEY

請前往 code.blogger.com 網誌 (網誌 ID 3213900) 查看文章：

GET https://www.googleapis.com/blogger/v2/blogs/3213900?key=YOUR-API-KEY

來自 JavaScript 的 REST

您可以使用 callback 的 JavaScript 查詢參數和回呼函式，透過 JavaScript 使用 Blogger JSON API 叫用。這可讓您編寫會顯示 Blogger 資料的豐富應用程式，而無需編寫任何伺服器端程式碼。

以下範例會從 code.blogger.com 網誌擷取文章（將 YOUR-API-KEY 替換成您的 API 金鑰）。

<html>
  <head>
    <title>Blogger JSON API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function handleResponse(response) {
        document.getElementById("content").innerHTML += "<h1>" + response.title + "</h1>" + response.content;
      }
    </script>
    <script
    src="https://www.googleapis.com/blogger/v2/blogs/3213900/posts/8398240586497962757?callback=handleResponse&key=YOUR-API-KEY"></script>
  </body>
</html>

資料格式

JSON

JSON (JavaScript 物件標記法) 是一種常見的語言獨立資料格式，可透過簡單的文字顯示任意資料結構。詳情請參閱 json.org。