Blogger JSON API：入門指南

重要事項：我們將於 2024 年 9 月 30 日停止支援 2.0 JSON API。為確保能持續運作，請將採用 2.0 JSON API 版本的應用程式更新至最新版 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 版。如果您要從 Blogger 擷取 JSON 格式 (而非 XML) 的資料，請使用 Blogger JSON API。如果您要擷取 XML 格式的資料，請使用 Blogger Data API。

這個版本的 Blogger JSON API 目前僅供讀取；不過，我們計劃新增讀取/寫入功能，以及其他功能。歡迎前往 Blogger 說明論壇要求其他功能。

事前準備

建立 Google 帳戶

確認您已設定 Google 帳戶。我們建議您使用獨立的 Google 帳戶進行開發與測試，以防止意外遺失資料。如果您已有測試帳戶，就可以前往 Blogger 使用者介面設定、編輯或查看測試資料。

熟悉 Blogger

如果不熟悉 Blogger 的概念，請參閱本文件並測試使用者介面，再開始撰寫程式碼。本文假設您已熟悉 Blogger、網頁程式設計概念和網頁資料格式。

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

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

當您的應用程式要求公開資料時，要求不須取得授權，但需要附上 ID，例如 API 金鑰。

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

Blogger JSON API 背景

Blogger 概念

Blogger 奠基於五項基本概念：

  • 網誌：API 的根概念。網誌包含文章和頁面。這是網誌中繼資料 (例如網誌名稱和說明) 的容器。
  • 文章：網誌文章是指網誌作者建立的可發布項目，這項資訊旨在即時反映作者打算向全世界發布的內容。我們知道隨著時間的推移，網誌文章內容的存在時間會逐漸降低，關聯性也會變得較不相關。
  • 留言：留言者以外的使用者會在留言區回應作者撰寫的內容。從磚塊到花束應有盡有。
  • 網頁：網頁是靜態內容的位置，例如傳記資訊或聯絡使用者的方式。這些資訊通常不時更新，而且不會經常變動。
  • 使用者：使用者是指與 Blogger 互動的人，擔任作者、管理員或僅限讀者。如果是公開網誌，讀者可能是匿名讀者，但私人網誌的讀者必須能藉由 Blogger 來識別。

Blogger JSON API 資料模型

「資源」指的是具有專屬 ID 的個別資料實體。Blogger JSON API 可對五種類型的資源運作：

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

Blogger JSON API 資料模型是以一組資源為基礎，稱為集合：

網誌集合
<span="apicollection">網誌集合包含使用者有權存取的所有網誌。您可以依使用者列出網誌，或依 ID 擷取單一網誌。</span="apicollection">
訊息最愛
貼文集合包含特定網誌資源中的所有貼文資源。
留言集合
留言集合包含特定貼文資源中的所有留言資源。
網頁集合
「網頁集合」包含特定網誌資源中的所有網頁資源。
使用者集合
使用者集合包含 Blogger 上的所有使用者資源，因此無法列出。使用者可以依據 ID 或 ID self 擷取自己的使用者資源 (但不包括其他人)。

Blogger JSON API 作業

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

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

下表列出每種資源類型支援的方法。私人網誌中的所有 list 和 get 作業都需要經過驗證。

資源類型
支援的方法
清單 取得
網誌 是 是
貼文 是 是
註解 是 是
網頁 是 是
使用者 否 是

呼叫樣式

叫用 API 的方法有以下幾種：

REST

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

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

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

在 Google 的 RESTful API 中，用戶端會使用 POST、GET、PUT 或 DELETE 等 HTTP 動詞來指定動作。它會透過全域唯一的 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

如需 API 中所用 URI 完整說明，以及各項支援作業的結果，請參閱 Blogger JSON 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

您可以透過 JavaScript 提供的 REST 叫用 Blogger JSON API，方法是使用 callback 查詢參數和回呼函式。如此一來，您就可以編寫各種顯示 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 Object Notation) 是一種與語言無關的常用資料格式，可透過簡單的文字方式呈現任意資料結構。詳情請參閱 json.org。