Blogger API：入門指南

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

事前準備

申請 Google 帳戶

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

熟悉 Blogger

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

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

如果您的應用程式要求存取私人資料，必須由可存取該資料的已驗證使用者對此要求進行授權。

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

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

Blogger API 背景資訊

Blogger 概念

Blogger 的建構基礎是五個基本概念：

網誌：API 的基本概念。網誌包含文章和頁面。這是網誌中繼資訊的容器，例如網誌名稱和說明。
貼文：網誌貼文是網誌作者建立的可發布項目。這項資訊應反映作者目前想向全世界發布的內容。隨著時間推移，網誌文章內容會過時，變得較不相關。
留言：留言區是網誌貼文作者以外的人，對作者撰寫內容的回應。從磚塊到花束，應有盡有。
頁面：頁面是靜態內容的存放位置，例如個人簡介資訊或使用者的聯絡方式。這類資訊通常不會過時，也不會經常變更。
使用者：使用者是指與 Blogger 互動的人，無論是作者、管理員或讀者。公開網誌的讀者可能是匿名使用者，但私人網誌的讀者必須由 Blogger 識別。

Blogger API 資料模型

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

網誌資源：代表網誌。
文章資源：代表一篇文章，每個文章資源都是網誌資源的子項。
留言資源：代表特定貼文的留言，每個留言資源都是貼文資源的子項。
頁面資源：代表靜態網頁，每個頁面資源都是網誌資源的子項。
使用者資源：代表非匿名使用者。這項資訊用於識別網頁、文章或留言的作者。

「blogs」資源有兩種子項資源類型：「pages」和「posts」。
貼文資源可能會有留言資源子項。 — 資源關係總覽

Blogger API 資料模型是以資源群組 (稱為集合) 為基礎：

網誌集錦: <span="apicollection">部落格集合包含使用者有權存取的所有部落格。您可以依使用者列出網誌，或依 ID 擷取單一網誌。</span="apicollection">
貼文集錦: 「文章集合」包含特定「網誌」資源中的所有「文章」資源。
收集留言: 留言集合包含特定貼文資源中的所有留言資源。
網頁集合: 「網頁集合」包含特定「網誌」資源中的所有「網頁」資源。
使用者集合: 使用者集合包含 Blogger 上的所有使用者資源，因此無法列出。使用者可以透過 ID 或使用識別碼 self 擷取自己的使用者資源 (但無法擷取其他人的資源)。

Blogger API 作業

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

作業	說明	REST HTTP 對應
list	列出集合中的所有資源。	集合 URI 的 `GET`。
get	取得特定資源。	資源 URI 的 `GET`。
getByUrl	依網址查詢並取得資源。	`GET`，並將網址做為參數傳入。
getByPath	依路徑查閱資源並取得。	`GET`，並將路徑做為參數傳入。
listByUser	列出使用者擁有的資源。	`GET`。
search	根據查詢參數搜尋資源。	`GET`，並將查詢內容做為參數傳遞。
插入	在集合中建立資源。	集合 URI 的 `POST`。
刪除	刪除資源。	資源 URI 的 `DELETE`。
修補程式	使用 Patch 語意更新資源。	資源 URI 的 `PATCH`。
更新	更新資源。	資源 URI 的 `PUT`。

下表列出各資源類型支援的方法。對私人網誌執行的所有 list 和 get 作業都必須經過驗證。

資源類型	支援的方法
	list	get	getByUrl	getByPath	listByUser	搜尋	插入	刪除	修補程式	update
網誌	否	是	是	否	是	否	不	不	不	否
貼文	是	是	否	是	否	是	是	是	是	是
留言	是	是	否	不	不	不	不	不	不	否
網頁	是	是	否	不	不	不	不	不	不	否
使用者	否	是	否	不	不	不	不	不	不	否

呼叫樣式

您可以透過下列幾種方式叫用 API：

直接使用 REST 或透過 JavaScript 使用 (不需伺服器端程式碼)
使用用戶端程式庫。

REST

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

REST 這個詞是「Representational State Transfer (表現層狀態轉換)」的簡稱。在 Google API 中，這是指使用 HTTP 動詞來擷取及修改 Google 所儲存資料的表示法。

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

在符合 REST 樣式的各種 Google 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 API 中的 REST

支援的 Blogger 作業會直接對應至 REST HTTP 動詞，如「Blogger API 作業」一文所述。

Blogger API URI 的特定格式如下：

https://www.googleapis.com/blogger/v3/users/userId
https://www.googleapis.com/blogger/v3/users/self
https://www.googleapis.com/blogger/v3/users/userId/blogs
https://www.googleapis.com/blogger/v3/users/self/blogs
https://www.googleapis.com/blogger/v3/blogs/blogId
https://www.googleapis.com/blogger/v3/blogs/byurl
https://www.googleapis.com/blogger/v3/blogs/blogId/posts
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/bypath
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/search
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId/comments
https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId/comments/commentId
https://www.googleapis.com/blogger/v3/blogs/blogId/pages
https://www.googleapis.com/blogger/v3/blogs/blogId/pages/pageId

如需 API 中各個支援的作業使用的完整 URI 組合摘要資訊，請參閱 Blogger API 參考資料文件。

範例

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

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

在 code.blogger.com 網誌上取得文章，該網誌的 ID 為 3213900：

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

透過 JavaScript 使用 REST

您可以使用 callback 查詢參數並提供回呼函式，從 JavaScript 叫用 Blogger API。瀏覽器載入指令碼時，系統會執行回呼函式，並將回應提供給回呼函式。這種做法可讓您編寫豐富的應用程式，顯示 Blogger 資料，且不需要伺服器端程式碼。

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

<html>
  <head>
    <title>Blogger 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/v3/blogs/3213900/posts/8398240586497962757?callback=handleResponse&key=YOUR-API-KEY"></script>
  </body>
</html>

資料格式

JSON

JSON (JavaScript Object Notation) 是一種與語言無關的常用資料格式，可透過簡單的文字方式來表示任意資料結構。詳情請參閱 json.org 網站。

Blogger API：入門指南 透過集合功能整理內容 你可以依據偏好儲存及分類內容。