本文件詳細說明使用 Google Books API 所需的背景知識。
簡介
本文件可協助開發人員編寫可與 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 圖書管理的所有書架資源。只有在特定使用者的圖書館中,書架必須一律參照書架。 書架可包含零個或更多冊。
- 我的最愛:可變動的書架。
- 已購買:會填入使用者已購買的冊。使用者無法手動新增或移除磁碟區。
- 讀取:可變動的書架。
- 立即閱讀:可變動的書架。
- 具備讀取:可變動的書架。
- 已審查:填入使用者已評論的冊。使用者無法手動新增或移除磁碟區。
- 最近查看:以使用者最近在網路閱讀器中開啟的磁碟區填入資料。使用者無法手動新增磁碟區。
- 我的電子書:可變動的書架。購買的書籍會自動新增,不過你可以手動移除。
- 為你推薦的書籍:提供個人化書冊。如果沒有對使用者的建議,這個書架不存在。
- 「我的收藏」
- 「哈利波特」
- 「我的電子書」
- 「切換」
- 「暮光」
- 「The Girl with the Dragon attoo」(龍刺青的女孩)
Google 為每位使用者提供一組預先定義的書架:
書架範例:
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。