開始使用

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

1. 說明
2. 事前準備
   1. 取得 Google 帳戶
   2. 瞭解圖書
   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 Books API 中「我的圖書館」之下的所有作業，這些作業均視為私人項目，需要驗證及授權。此外，任何修改 Google 圖書資料的作業，都只能由擁有該資料的使用者執行。

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

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

Books API 背景

圖書概念

Google 圖書具有四個基本概念：

• 冊別：磁碟區代表 Google 圖書代管書籍或雜誌的資料。也是 Books API 的主要資源。這個 API 中的所有其他資源都包含磁碟區或加上註解。
• Bookshelf：書架是一系列的書籍。Google 圖書為每位使用者提供一組預先定義的書架，其中有些書架完全由使用者管理，其中有些書籍會自動根據使用者的活動填入，而有些則會混雜。使用者可以建立、修改或刪除其他書架，這些書架一律會手動填入書冊。使用者可以將書架設為私人或公開。

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

• 評論：數量評論是由星級評等和/或文字組合而成。每位使用者可以針對每冊提交一次評論。系統也會提供外部來源的評論，並註明出處。
• 讀取位置：讀取位置是指使用者在磁碟區中的上次讀取位置。每位使用者的每個音量都只能有一個閱讀位置。如果使用者之前尚未開啟該磁碟區，則讀取位置不存在。閱讀位置可以儲存詳細位置資訊至字詞解析度。這類資訊一律不會對外公開。

Books API 資料模型

資源是具有專屬 ID 的個別資料實體。根據上述概念，Book API 可以在兩種類型的資源上運作：

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

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

音量集合

數量集合是由 Google 圖書管理的每項磁碟區資源集合。因此，您無法將所有磁碟區資源「列出」，但可「列出」符合特定搜尋字詞的所有磁碟區。

Bookshelf 系列

書架集合包含由 Google 圖書管理的所有書架資源。只有在特定使用者的圖書館中，書架必須一律參照書架。 書架可包含零個或更多冊。

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

• 我的最愛：可變動的書架。
• 已購買：會填入使用者已購買的冊。使用者無法手動新增或移除磁碟區。
• 讀取：可變動的書架。
• 立即閱讀：可變動的書架。
• 具備讀取：可變動的書架。
• 已審查：填入使用者已評論的冊。使用者無法手動新增或移除磁碟區。
• 最近查看：以使用者最近在網路閱讀器中開啟的磁碟區填入資料。使用者無法手動新增磁碟區。
• 我的電子書：可變動的書架。購買的書籍會自動新增，不過你可以手動移除。
• 為你推薦的書籍：提供個人化書冊。如果沒有對使用者的建議，這個書架不存在。

書架範例：

• 「我的收藏」
• 「哈利波特」
• 「我的電子書」
• 「切換」
• 「暮光」
• 「The Girl with the Dragon attoo」(龍刺青的女孩)

Books API 作業

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

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

下表摘要說明各種資源類型支援的作業。套用至使用者私人資料的作業稱為「我的程式庫」作業，而且全都需要驗證。

資源類型	支援的作業
	清單	插入	取得	更新	刪除
數量	是*		是
書架	是*	是，已驗證	是*	是，已驗證	是，已驗證
讀取位置		是，已驗證	是，已驗證	是，已驗證	是，已驗證

*這些作業的 AUTHENTICATED 和未經驗證版本可供使用，經過驗證的要求會在使用者的私人「我的資料庫」資料中運作，未經驗證的要求則只會對公開資料執行。

通話方式

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

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

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

Books API 中的 REST

支援的圖書作業直接對應於 REST HTTP 動詞，如 Books API 作業中所述。

圖書 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

您可以使用 callback 查詢參數和回呼函式，透過 JavaScript 的 REST (也稱為 JSON-P) 叫用 Books API。如此一來，您無需編寫任何伺服器端程式碼，即可編寫內容豐富的應用程式，顯示圖書資料。

注意：您可以使用 access_token 參數傳遞 OAuth 2.0 權杖，來呼叫驗證方法。若要取得與 JavaScript 搭配使用的 OAuth 2.0 權杖，請按照用戶端網頁應用程式使用 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。