開始使用

本文詳細說明使用 Google Books API 時所需的背景知識。

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

簡介

本文適用於想編寫可與 Google Books API 互動的應用程式的開發人員。Google 圖書的願景是將全球書籍數位化。您可以使用 Google Books API 搜尋內容、整理已驗證使用者的個人圖書館，以及修改圖書館。

事前準備

申請 Google 帳戶

您需要用於測試的 Google 帳戶。如果已有測試帳戶，就一切就緒；你可以前往 Google 圖書使用者介面，設定、編輯或查看測試資料。

熟悉 Google 圖書

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

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

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

具體來說，Google 圖書 API 中「我的圖書館」下的所有作業都視為私人作業，因此需要驗證和授權。此外，只有資料擁有者才能執行任何修改 Google 圖書資料的操作。

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

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

Books API 背景資訊

書籍概念

Google 圖書是以四個基本概念為基礎建構而成：

  • 卷冊：卷冊代表 Google 圖書代管的書籍或雜誌資料。這是 Books API 中的主要資源。這個 API 中的所有其他資源都包含或註解了卷宗。
  • 書架：書架是卷冊的集合。Google 圖書會為每位使用者提供一組預先定義的書架，其中有些完全由使用者管理，有些則會根據使用者活動自動填入內容，有些則是兩者兼具。使用者可以建立、修改或刪除其他書架，但必須手動將書籍加入書架。使用者可以將書架設為私人或公開。

    注意：目前只能透過 Google 圖書網站建立及刪除書架，以及修改書架的隱私權設定。

  • 評論：書籍的評論包含星級評分和/或文字。每集只能提交一篇評論。我們也會提供外部來源的評論，並適當註明出處。
  • 閱讀位置：閱讀位置是指使用者在書籍中上次閱讀的位置。每位使用者只能為每個卷冊設定一個閱讀位置。如果使用者先前未開啟該卷冊，系統就不會儲存閱讀位置。閱讀位置可儲存詳細的位置資訊，精確度可達單字。這項資訊一律為使用者私有。

Books API 資料模型

資源是指具有專屬 ID 的個別資料實體。根據上述概念，Books API 採用兩種資源：

  • 磁碟區資源：代表磁碟區。
  • 書架資源：代表特定使用者的單一書架。

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

收集音量
卷冊集合：Google 圖書管理的所有卷冊資源集合。因此，您無法列出所有卷冊資源，但可以列出符合一組搜尋字詞的所有卷冊。
書架收藏
書架集合包含 Google 圖書管理的所有書架資源。書架一律須參照特定使用者的圖書館。 書架可包含零或多本讀物。

Google 會為每位使用者提供一組預先定義的書架：

  • 我的最愛：可變更的書架。
  • 已購買：填入使用者購買的卷冊。使用者無法手動新增或移除卷宗。
  • 可讀取：可變動的書架。
  • 閱讀中：可變動的書架。
  • 已讀：可變動的書架。
  • 已審查：顯示使用者已審查的書籍。使用者無法手動新增或移除卷宗。
  • 最近瀏覽：顯示使用者最近在網頁閱讀器中開啟的書籍。使用者無法手動新增卷冊。
  • 我的電子書：可變動的書架。系統會自動加入購買的書籍，但你可以手動移除。
  • 為你推薦的書籍：根據個人喜好推薦書籍。如果我們沒有任何建議內容，就不會顯示這個書架。

書架範例：

  • 「我的最愛」
    • 「哈利波特」
  • 「我的電子書」
    • 「切換」
    • 「Twilight」(微光)
    • 《龍紋身的女孩》

Books API 作業

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

作業 說明 REST HTTP 對應
list 列出集合中指定的資源子集。 集合 URI 的 GET。
插入 將新資源插入集合 (建立新資源)。 集合 URI 上的 POST，您可以在其中傳遞新資源的資料。
get 取得特定資源。 資源 URI 的 GET。
更新 更新特定資源。 資源 URI 的 PUT，您可以在其中傳遞更新資源的資料。
刪除 刪除特定資源。 資源 URI 的 DELETE，您可以在其中傳遞要刪除的資源資料。

下表匯總各種資源類型支援的作業。適用於使用者私人資料的作業稱為「我的圖書館」作業，這類作業都需要驗證。

資源類型
支援的作業
list 插入 get update 刪除
數量 是* 是
書櫃 是* 是，代表「已通過驗證」 是* 是，代表「已通過驗證」 是，代表「已通過驗證」
閱讀位置 是，代表「已通過驗證」 是，代表「已通過驗證」 是，代表「已通過驗證」 是，代表「已通過驗證」

*這些作業提供已驗證和未驗證版本，其中已驗證要求會對使用者的私人「我的圖書館」資料執行作業，未驗證要求則只會對公開資料執行作業。

呼叫樣式

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

  • 直接使用 REST
  • 從 JavaScript 使用 REST (不需伺服器端程式碼)

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 的規格說明。

Books API 中的 REST

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

Books API URI 的特定格式如下：

https://www.googleapis.com/books/v1/{collectionName}/resourceID?parameters

其中 resourceID 是卷冊或書架資源的 ID，parameters 則是要套用至查詢的任何參數。詳情請參閱查詢參數參考資料。

resourceID 路徑擴充功能的格式可讓您識別目前正在使用的資源，例如：

https://www.googleapis.com/books/v1/volumes
https://www.googleapis.com/books/v1/volumes/volumeId
https://www.googleapis.com/books/v1/mylibrary/bookshelves
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes
...

請注意，URI 中含有 mylibrary 的作業僅適用於目前已通過驗證的使用者私人程式庫資料。如需 API 中各個支援的作業使用的完整 URI 組合摘要資訊，請參閱 Books API 參考資料文件。

以下是 Books API 的幾個範例，說明這項服務如何運作。

搜尋「縫紉」：

GET https://www.googleapis.com/books/v1/volumes?q=quilting

取得磁碟區 s1gVAAAAYAAJ 的相關資訊：

GET https://www.googleapis.com/books/v1/volumes/s1gVAAAAYAAJ

透過 JavaScript 使用 REST

您可以使用 JavaScript (也稱為 JSON-P) 透過 REST 呼叫 Books API，方法是使用 callback 查詢參數和回呼函式。這樣一來，您不必編寫任何伺服器端程式碼，就能撰寫可顯示圖書資料的豐富應用程式。

注意：您可以透過 access_token 參數傳遞 OAuth 2.0 權杖，呼叫已驗證的方法。如要取得 OAuth 2.0 權杖以搭配 JavaScript 使用，請按照「適用於用戶端網路應用程式的 OAuth 2.0」一文中的操作說明進行。在 API 控制台的「API 存取權」分頁中，請務必為網頁應用程式設定用戶端 ID，並在取得權杖時使用這些 OAuth 2.0 憑證。

以下範例使用這種方法顯示「哈利波特」的搜尋結果：

<html>
  <head>
    <title>Books API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function handleResponse(response) {
      for (var i = 0; i < response.items.length; i++) {
        var item = response.items[i];
        // in production code, item.text should have the HTML entities escaped.
        document.getElementById("content").innerHTML += "<br>" + item.volumeInfo.title;
      }
    }
    </script>
    <script src="https://www.googleapis.com/books/v1/volumes?q=harry+potter&callback=handleResponse"></script>
  </body>
</html>

資料格式

JSON

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