開始使用

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

簡介

本文件的適用對象為想編寫可與 Google Books API 互動的應用程式。Google 圖書能夠實現全球書籍的數位化作業。您可以使用 Google Books API 搜尋內容、整理已驗證使用者的個人程式庫,也可以進行修改。

事前準備

取得 Google 帳戶

您需要 Google 帳戶以進行測試。如果您已擁有測試帳戶,則無需進行任何設定。您可以前往 Google 圖書使用者介面設定、編輯或檢視您的測試資料。

熟悉圖書功能

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

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

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

特別是在「Google 圖書 API」中的「我的圖書館」下,所有作業皆屬於私人用途,並且需要驗證和授權。此外,任何修改「Google 圖書」資料的作業只能由擁有這些資料的使用者執行。

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

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

Books API 背景

圖書概念

Google 圖書的建立基礎有四種:

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

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

  • 評論:評論量由星級評等和/或文字的組合而成。每位使用者一個磁碟區只能提交一則評論。您也可以從外部來源取得評論,並妥善進行歸屬。
  • 讀取位置:讀取位置代表使用者磁碟區的最後一個讀取位置,每個磁碟區只能有一個讀取位置。如果使用者之前從未開啟該磁碟區,則讀取位置不存在。讀取位置可將詳細的定位資訊儲存到特定字詞的解析度。且絕對不會公開這項資訊。

Books API 資料模型

資源是具有專屬 ID 的個別資料實體。Books API 會根據上述概念運作兩種資源:

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

Books API 資料模型是以資源集合為基礎,稱為集合:

磁碟區收集
磁碟區集是 Google 圖書管理的所有磁碟區資源的集合。因此,您無法列出所有磁碟區資源,但可以列出符合一組搜尋字詞的所有磁碟區。
書架收藏
書架集合包含由 Google 圖書管理的所有書架資源。請務必一律透過特定使用者的程式庫參照書籍櫃。 書架可包含 0 或 1 本冊。

Google 為每位使用者提供一組預先定義的書籍櫃,包括:

  • 我的最愛:可變動的書架。
  • 已購買:填入使用者購買的磁碟區。使用者無法手動新增或移除磁碟區。
  • 閱讀:可變動的書架。
  • 立即閱讀:可變動的書架。
  • 閱讀:可變動的書架。
  • 已審查:填入使用者已評論的磁碟區。使用者無法手動新增或移除磁碟區。
  • 最近檢視的:填入使用者最近透過網路閱讀器開啟的磁碟區。使用者無法手動新增磁碟區。
  • 我的電子書:可變動的書架。系統會自動新增購買的書籍,但您可以手動移除這些書籍。
  • 專屬書籍:提供個人化磁碟區建議。如果我們沒有為使用者提供建議,這個書架不存在。

書櫃範例:

  • 「我的收藏」
    • 「哈利波特」
  • 「我的電子書」
    • 「切換」
    • 「黃昏」
    • 《The Girl with the Dragon Tattoo》

Books API

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

Operation 說明 REST HTTP 對應
list 列出集合中指定資源的子集。 集合 URI 上的 GET
插入 將新資源插入集合 (建立新資源)。 集合 URI 上的 POST,您可以在其中傳入新資源的資料。
取得 取得特定資源。 資源 URI 上的 GET
更新 更新特定資源。 資源 URI 中的 PUT,您可以在其中傳入已更新資源的資料。
刪除 刪除特定資源。 資源 URI 中的 DELETE,用於傳入待刪除資源的資料。

下表匯總了各種資源支援的作業。套用至使用者私人資料的操作稱為「我的程式庫」作業,且這些作業都需要進行驗證

資源類型
支援的作業
list [清單] insert get update [更新] delete (刪除)。
數量 是*
書架 是* 是,已驗證 是* 是,已驗證 是,已驗證
讀取位置 是,已驗證 是,已驗證 是,已驗證 是,已驗證

*作業的「已驗證」和未經驗證的版本都可用,其中經過驗證的要求會針對使用者的私人「我的資料庫」資料執行,而未驗證的要求只會對公開資料執行。

呼叫樣式

叫用 API 的方法有好幾種:

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

REST

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

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

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

在 Google 的 RESTful API 中,用戶端會使用 HTTP 動詞指定動作,例如 POSTGETPUTDELETE。並由下列格式的全域唯一 URI 指定資源:

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

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

HTTP 1.1 標準說明文件中的方法定義可能非常實用;其中包含 GETPOSTPUTDELETE 的規格。

Books API 中的 REST

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

Books API URI 的具體格式如下:

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

其中 resourceID 是磁碟區或書架資源 ID 的 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 參考資料文件。

以下舉幾個範例說明如何在 Book API 中的運作方式。

搜尋拼布:

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

取得音量 s1gVAAAAYAAJ 的資訊:

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

來自 JavaScript 的 REST

您可以使用 JavaScript 的 REST (也稱為 JSON-P) 叫用 Books API,同時使用 callback 查詢參數和回呼函式。這可讓您編寫顯示書籍資料的豐富應用程式,而無需編寫任何伺服器端程式碼。

注意:如要呼叫經過驗證的方法,請使用 access_token 參數傳送 OAuth 2.0 憑證。如要取得與 JavaScript 搭配使用的 OAuth 2.0 憑證,請按照適用於用戶端網路應用程式的 OAuth 2.0 一文的說明操作。在 API 主控台的「API 存取」分頁中,請務必為網路應用程式設定用戶端 ID,並在取得憑證時使用這些 OAuth 2.0 憑證。

下列範例使用此方法顯示「harry potter」的搜尋結果:

<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 物件標記法) 是一種常見的語言專用資料格式,可透過簡單的文字表示任意資料結構。詳情請參閱 json.org