本文件詳細說明瞭使用 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 本冊。
- 我的最愛:可變動的書架。
- 已購買:填入使用者購買的磁碟區。使用者無法手動新增或移除磁碟區。
- 閱讀:可變動的書架。
- 立即閱讀:可變動的書架。
- 閱讀:可變動的書架。
- 已審查:填入使用者已評論的磁碟區。使用者無法手動新增或移除磁碟區。
- 最近檢視的:填入使用者最近透過網路閱讀器開啟的磁碟區。使用者無法手動新增磁碟區。
- 我的電子書:可變動的書架。系統會自動新增購買的書籍,但您可以手動移除這些書籍。
- 專屬書籍:提供個人化磁碟區建議。如果我們沒有為使用者提供建議,這個書架不存在。
- 「我的收藏」
- 「哈利波特」
- 「我的電子書」
- 「切換」
- 「黃昏」
- 《The Girl with the Dragon Tattoo》
Google 為每位使用者提供一組預先定義的書籍櫃,包括:
書櫃範例:
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 動詞指定動作,例如 POST
、GET
、PUT
或 DELETE
。並由下列格式的全域唯一 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 作業中所述。
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。