本頁面由 Cloud Translation API 翻譯而成。

使用 API

簡介

本文件適用於想編寫可與 Books API 互動的應用程式的開發人員。Google 圖書的使命是將全球書籍內容數位化，讓使用者更容易在網路上找到這些書籍。圖書 API 可用於搜尋及存取內容，以及建立及查看與該內容相關的個人化內容。

如果您不熟悉 Google 圖書的概念，請先閱讀「開始使用」一文，再開始撰寫程式碼。

授權要求和識別應用程式

您的應用程式傳送至 Books API 的每項要求，都必須向 Google 識別您的應用程式。有兩種方法可以識別您的應用程式：使用 OAuth 2.0 憑證 (也用來授權要求) 和/或使用應用程式的 API 金鑰。下列內容說明如何決定使用的方法：

如果要求需要經過授權 (例如要求個人的私人資料)，則應用程式必須為此要求提供 OAuth 2.0 憑證。應用程式也可以提供 API 金鑰，但並非必須。
如果要求不需要經過授權 (例如要求公開資料)，則應用程式必須為此要求提供 OAuth 2.0 憑證及/或 API 金鑰，視何種方式對您來說比較方便而定。

關於授權通訊協定

您的應用程式必須使用 OAuth 2.0 對要求進行授權，系統不支援其他授權通訊協定。如果您的應用程式採用使用 Google 帳戶登入功能，系統會為您處理部分授權事項。

使用 OAuth 2.0 對要求進行授權

向 Books API 發出的非公開使用者資料要求都必須獲得已驗證使用者的授權。

OAuth 2.0 授權程序 (或「流程」) 的細節會根據您編寫的應用程式類型而有所不同。下列一般程序適用於所有應用程式類型：

建立應用程式後，請透過 Google API 控制台註冊應用程式。接著 Google 會向您提供稍後需要的資訊，例如用戶端 ID 和用戶端密碼。
在 Google API 控制台中啟用 Books API。(如果 API 控制台裡沒有列出該 API，則可略過這個步驟)。
當應用程式需要存取使用者資料時，會向 Google 要求特定的存取範圍。
Google 會向使用者顯示同意畫面，請對方授權您的應用程式要求部分資料。
如果使用者同意，Google 即會授予短期存取權杖給您的應用程式。
您的應用程式向使用者要求資料，並且在要求中附上存取權杖。
如果 Google 判定您的要求與權杖有效，便會傳回您要求的資料。

部分流程包含額外步驟，例如使用「更新權杖」來取得新的存取權杖。如要進一步瞭解各類應用程式的流程，請參閱 Google 的 OAuth 2.0 說明文件。

以下列出 Books API 的 OAuth 2.0 範圍資訊：

https://www.googleapis.com/auth/books

如要透過 OAuth 2.0 要求存取權，您的應用程式需要範圍資訊，以及 Google 在您註冊應用程式時提供的資訊 (例如用戶端 ID 和用戶端密碼)。

提示：Google API 用戶端程式庫可以為您處理部分授權程序，且適用於多種程式設計語言；詳情請參閱程式庫和範例頁面。

取得並使用 API 金鑰

向 Books API 發出的公開資料要求都必須附有 ID，可以是 API 金鑰或是存取權杖。

要取得 API 金鑰：

在 API 控制台中開啟「憑證」頁面。
此 API 支援兩種憑證。請建立適用於您專案的憑證：
- OAuth 2.0：每當您的應用程式要求私人使用者資料時，必須同時傳送 OAuth 2.0 憑證。您的應用程式會先傳送用戶端 ID，並可能傳送用戶端密碼以獲取憑證。您可以為網路應用程式、服務帳戶或已安裝的應用程式產生 OAuth 2.0 憑證。
  
  詳情請參閱 OAuth 2.0 說明文件。
- API 金鑰：沒有提供 OAuth 2.0 憑證的要求必須傳送 API 金鑰。金鑰可用來識別專案，並為您提供 API 存取權、配額和報表。
  
  API 支援數種類型的 API 金鑰限制。如果您還沒有所需的 API 金鑰，請依序點選「Create credentials」 >「API key」，以在主控台中建立 API 金鑰。在您將金鑰使用在實際工作環境中之前，可以點選「Restrict key」(限制金鑰) 並選擇其中一項「Restrictions」(限制)以限制金鑰的使用。

為確保您 API 金鑰的安全，請遵循安全使用 API 金鑰的最佳做法。

取得 API 金鑰後，您的應用程式可以將查詢參數 key=yourAPIKey 附加到所有要求網址。

API 金鑰可以安全地嵌入網址中，不需任何編碼。

Google 圖書 ID

您必須在特定 API 方法呼叫中指定 ID 欄位。Google 圖書中使用的 ID 有三種類型：

卷冊 ID：Google 圖書所知的每個卷冊所擁有的專屬字串。音量 ID 的範例為 _LettPDhwR0C。您可以使用 API 提出要求，讓系統傳回 Volume 資源，藉此取得卷冊 ID；您可以在 id 欄位中找到卷冊 ID。
書架 ID：使用者媒體庫中書架的數值。Google 會為每位使用者提供一些預先定義的展示架，這些展示架的 ID 如下：
- 收藏：0
- 已購買：1
- 待讀取：2
- 目前正在閱讀：3
- 已讀取：4
- 已審查：5
- 最近查看的項目：6
- 我的電子書：7
- 個人書籍：8 如果我們沒有為使用者提供任何建議，則這個書架不存在。
自訂展示版的 ID 大於 1000。書架 ID 對特定使用者而言是唯一的，也就是說，兩位使用者可以擁有同一個 ID 的書架，但指的是不同的書架。您可以使用 API 提出要求，藉此取得 Bookshelf 資源，並在 id 欄位中找到 Bookshelf ID。
使用者 ID：指派給每位使用者的專屬數值。這些值不一定與其他 Google 服務中使用的 ID 值相同。目前，要擷取使用者 ID 的唯一方法，就是從透過已驗證要求擷取的 Bookshelf 資源中，擷取 selfLink。使用者也可以從 Google 圖書網站取得自己的使用者 ID。使用者無法透過 API 或 Books 網站取得其他使用者的使用者 ID；其他使用者必須明確分享這項資訊，例如透過電子郵件。

Google 圖書網站上的 ID

您在 Books API 中使用的 ID 與 Google 圖書網站上使用的 ID 相同。

磁碟區 ID

在網站上查看特定卷冊時，您可以在 id 網址參數中找到卷冊 ID。範例如下：
```
https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard
```

Bookshelf ID

在網站上查看特定書櫃時，您可以在 as_coll 網址參數中找到書櫃 ID。範例如下：

https://books.google.com/books?hl=en&as_coll=0&num=10&uid=11122233344455566778&source=gbs_slider_cls_metadata_0_mylibrary

使用者 ID

在網站上查看媒體庫時，您可以在 uid 網址參數中找到使用者 ID。範例如下：
```
https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list
```

設定使用者位置

Google 圖書會尊重與使用者所在位置相關的著作權、合約和其他法律限制。因此，部分使用者可能無法存取特定國家/地區的書籍內容。舉例來說，某些書籍僅在美國提供「預覽」功能，我們會為其他國家/地區的使用者略去這類預覽連結。因此，API 結果會根據伺服器或用戶端應用程式的 IP 位址進行限制。

使用磁碟區

執行搜尋

如要執行卷宗搜尋，請將 HTTP GET 要求傳送至下列 URI：

https://www.googleapis.com/books/v1/volumes?q=search+terms

這項要求只有一個必要參數：

q：搜尋含有此文字字串的冊次。您可以在搜尋字詞中指定特殊關鍵字，以便在特定欄位中進行搜尋，例如：
- intitle: 傳回結果，其中標題中會出現此關鍵字後方的文字。
- inauthor: 傳回結果，其中作者中會找到此關鍵字後面的文字。
- inpublisher: 傳回結果，其中包含在發布者中找到此關鍵字後面的文字。
- subject: 會傳回結果，其中包含此關鍵字後方的文字，並列在音訊的類別清單中。
- isbn: 傳回的結果中，關鍵字後面的文字為 ISBN 編號。
- lccn: 傳回的結果中，此關鍵字後方的文字為美國國會圖書館卡片編號。
- oclc: 傳回的結果中，此關鍵字後方的文字為國際線上圖書館電腦中心編號。

要求

以下是搜尋 Daniel Keyes 的「Flowers for Algernon」的範例：

GET https://www.googleapis.com/books/v1/volumes?q=flowers+inauthor:keyes&key=yourAPIKey

注意：執行搜尋作業不需要驗證，因此您不需要在 GET 要求中提供 Authorization HTTP 標頭。不過，如果呼叫時已完成驗證，每個 Volume 都會包含使用者專屬資訊，例如購買狀態。

回應

如果要求成功，伺服器會傳回 200 OK HTTP 狀態碼和音量結果：

200 OK

{
 "kind": "books#volumes",
 "items": [
  {
   "kind": "books#volume",
   "id": "_ojXNuzgHRcC",
   "etag": "OTD2tB19qn4",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/_ojXNuzgHRcC",
   "volumeInfo": {
    "title": "Flowers",
    "authors": [
     "Vijaya Khisty Bodach"
    ],
   ...
  },
  {
   "kind": "books#volume",
   "id": "RJxWIQOvoZUC",
   "etag": "NsxMT6kCCVs",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/RJxWIQOvoZUC",
   "volumeInfo": {
    "title": "Flowers",
    "authors": [
     "Gail Saunders-Smith"
    ],
    ...
  },
  {
   "kind": "books#volume",
   "id": "zaRoX10_UsMC",
   "etag": "pm1sLMgKfMA",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/zaRoX10_UsMC",
   "volumeInfo": {
    "title": "Flowers",
    "authors": [
     "Paul McEvoy"
    ],
    ...
  },
  "totalItems": 3
}

選用查詢參數

除了標準查詢參數之外，您也可以在執行卷宗搜尋時使用下列查詢參數。

下載格式

您可以使用 download 參數，將傳回的結果限制為具有可用下載格式 epub 的卷，方法是將設為 epub 值。

以下範例會搜尋可下載 EPUB 的書籍：

GET https://www.googleapis.com/books/v1/volumes?q=pride+prejudice&download=epub&key=yourAPIKey

篩選

您可以使用 filter 參數，將其設為下列其中一個值，進一步限制傳回的結果：

partial：傳回至少可預覽部分文字的結果。
full：只會傳回所有文字皆可見的結果。
free-ebooks - 只會傳回免費 Google 電子書的結果。
paid-ebooks：只會傳回價格已定義的 Google 電子書。
ebooks：只會傳回 Google 電子書的結果，不論是付費或免費。非電子書的例子包括可供試閱但無法購買的發布商內容，或雜誌。

以下範例會將搜尋結果限制為免費電子書：

GET https://www.googleapis.com/books/v1/volumes?q=flowers&filter=free-ebooks&key=yourAPIKey

分頁

您可以在要求的參數中指定兩個值，藉此分頁顯示音量清單：

startIndex：在集合中開始的位置。第一個項目的索引為 0。
maxResults：要傳回的結果數上限。預設值為 10，最大允許值為 40。

列印類型

您可以使用 printType 參數，將傳回的結果限制為特定的平面或出版類型，方法是將其設為下列其中一個值：

all - 不限制列印類型 (預設)。
books：只會傳回圖書結果。
magazines：傳回雜誌結果。

以下範例將搜尋結果限制為雜誌：

GET https://www.googleapis.com/books/v1/volumes?q=time&printType=magazines&key=yourAPIKey

投影

您可以使用 projection 參數搭配下列任一值，指定要傳回的預先定義 Volume 欄位組合：

full：傳回所有 Volume 欄位。
lite - 只會傳回特定欄位。如要瞭解包含哪些欄位，請參閱資料夾參考資料中標有雙星號的欄位說明。

以下範例會傳回含有有限銷量資訊的搜尋結果：

GET https://www.googleapis.com/books/v1/volumes?q=flowers&projection=lite&key=yourAPIKey

排序

根據預設，音訊搜尋要求會傳回 maxResults 結果，其中 maxResults 是分頁 (上述) 中使用的參數，依關聯性排序。

您可以將 orderBy 參數設為下列其中一個值，藉此變更排序順序：

relevance：依搜尋字詞關聯性順序傳回結果 (這是預設值)。
newest：依最近發布日期 (從最近到最久以前) 傳回結果。

以下範例會依發布日期列出結果，由最新到最舊：

GET https://www.googleapis.com/books/v1/volumes?q=flowers&orderBy=newest&key=yourAPIKey

擷取特定音量

您可以向 Volume 資源 URI 傳送 HTTP GET 要求，擷取特定磁碟區的資訊：

https://www.googleapis.com/books/v1/volumes/volumeId

將 volumeId 路徑參數替換為要擷取的音量 ID。如要進一步瞭解冊次 ID，請參閱「Google 圖書 ID」一節。

要求

以下是取得單一卷的 GET 要求範例：

GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?key=yourAPIKey

注意：擷取音量資訊不需要驗證，因此您不必在 GET 要求中提供 Authorization HTTP 標頭。不過，如果呼叫時已進行驗證，則 Volume 會包含使用者專屬資訊，例如購買狀態。

回應

如果要求成功，伺服器會傳回 200 OK HTTP 狀態碼和要求的 Volume 資源：

200 OK

{
 "kind": "books#volume",
 "id": "zyTCAlFPjgYC",
 "etag": "f0zKg75Mx/I",
 "selfLink": "https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC",
 "volumeInfo": {
  "title": "The Google story",
  "authors": [
   "David A. Vise",
   "Mark Malseed"
  ],
  "publisher": "Random House Digital, Inc.",
  "publishedDate": "2005-11-15",
  "description": "\"Here is the story behind one of the most remarkable Internet
  successes of our time. Based on scrupulous research and extraordinary access
  to Google, ...",
  "industryIdentifiers": [
   {
    "type": "ISBN_10",
    "identifier": "055380457X"
   },
   {
    "type": "ISBN_13",
    "identifier": "9780553804577"
   }
  ],
  "pageCount": 207,
  "dimensions": {
   "height": "24.00 cm",
   "width": "16.03 cm",
   "thickness": "2.74 cm"
  },
  "printType": "BOOK",
  "mainCategory": "Business & Economics / Entrepreneurship",
  "categories": [
   "Browsers (Computer programs)",
   ...
  ],
  "averageRating": 3.5,
  "ratingsCount": 136,
  "contentVersion": "1.1.0.0.preview.2",
  "imageLinks": {
   "smallThumbnail": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=5&edge=curl&source=gbs_api",
   "thumbnail": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=1&edge=curl&source=gbs_api",
   "small": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=2&edge=curl&source=gbs_api",
   "medium": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=3&edge=curl&source=gbs_api",
   "large": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=4&edge=curl&source=gbs_api",
   "extraLarge": "https://books.google.com/books?id=zyTCAlFPjgYC&printsec=frontcover&img=1&zoom=6&edge=curl&source=gbs_api"
  },
  "language": "en",
  "infoLink": "https://books.google.com/books?id=zyTCAlFPjgYC&ie=ISO-8859-1&source=gbs_api",
  "canonicalVolumeLink": "https://books.google.com/books/about/The_Google_story.html?id=zyTCAlFPjgYC"
 },
 "saleInfo": {
  "country": "US",
  "saleability": "FOR_SALE",
  "isEbook": true,
  "listPrice": {
   "amount": 11.99,
   "currencyCode": "USD"
  },
  "retailPrice": {
   "amount": 11.99,
   "currencyCode": "USD"
  },
  "buyLink": "https://books.google.com/books?id=zyTCAlFPjgYC&ie=ISO-8859-1&buy=&source=gbs_api"
 },
 "accessInfo": {
  "country": "US",
  "viewability": "PARTIAL",
  "embeddable": true,
  "publicDomain": false,
  "textToSpeechPermission": "ALLOWED_FOR_ACCESSIBILITY",
  "epub": {
   "isAvailable": true,
   "acsTokenLink": "https://books.google.com/books/download/The_Google_story-sample-epub.acsm?id=zyTCAlFPjgYC&format=epub&output=acs4_fulfillment_token&dl_type=sample&source=gbs_api"
  },
  "pdf": {
   "isAvailable": false
  },
  "accessViewStatus": "SAMPLE"
 }
}

存取資訊

accessInfo 部分特別有助於判斷電子書可用的功能。epub 是文字重排格式的電子書，epub 區段會包含 isAvailable 屬性，指出這類電子書是否可用。如果書籍有試閱內容，或是使用者已購買書籍，或在使用者所在位置屬於公共領域，則會提供下載連結。Google 圖書的 pdf 代表電子書的掃描頁面版本，並提供類似的詳細資料，例如是否可供使用和下載連結。Google 建議在電子書閱讀器和智慧型手機上使用 epub 檔案，因為掃描的頁面可能難以在這些裝置上閱讀。如果沒有 accessInfo 區段，則該書籍無法做為 Google 電子書。

選用查詢參數

除了標準查詢參數之外，您也可以在擷取特定卷時使用下列查詢參數。

投影

您可以使用 projection 參數搭配下列任一值，指定要傳回的預先定義 Volume 欄位組合：

full：傳回所有 Volume 欄位。
lite - 只會傳回特定欄位。如要瞭解包含哪些欄位，請參閱資料夾參考資料中標有雙星號的欄位說明。

以下範例會傳回單一音量有限的資訊：

GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?projection=lite&key=yourAPIKey

使用書架

擷取使用者的公開書架清單

您可以傳送 HTTP GET 要求至 URI，並使用下列格式擷取使用者的公開書架清單：

https://www.googleapis.com/books/v1/users/userId/bookshelves

將 userId 路徑參數替換為您要擷取書架的使用者 ID。如要進一步瞭解使用者 ID，請參閱「Google 圖書 ID」一節。

要求

範例如下：

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves&key=yourAPIKey

由於使用者無須經過驗證即可擷取有關公開書架的資訊，因此您不必在 GET 要求中提供 Authorization HTTP 標頭。

回應

如果要求成功，伺服器會傳回 200 OK HTTP 狀態碼和書架清單：

200 OK

{
 "kind": "books#bookshelves",
 "items": [
  {
   ...
  },
  {
   "kind": "books#bookshelf",
   "id": 3,
   "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
   "title": "Reading now",
   "description": "",
   "access": "PUBLIC",
   "updated": "2011-02-02T20:34:20.146Z",
   "created": "2011-02-02T20:34:20.146Z",
   "volumeCount": 2,
   "volumesLastUpdated": "2011-02-02T20:34:20.110Z"
  },
  ...
 ]
}

選用查詢參數

擷取使用者公開書架清單時，您可以使用標準查詢參數。

擷取特定公開書架

您可以傳送 HTTP GET 要求至 URI，格式如下，藉此擷取特定的公開書櫃：

https://www.googleapis.com/books/v1/users/userId/bookshelves/shelf

將 userId 和 shelf 路徑參數替換為指定使用者和要擷取的書架的 ID。詳情請參閱「Google 圖書 ID」一節。

要求

範例如下：

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3?key=yourAPIKey

由於使用者無須經過驗證即可擷取有關公開書架的資訊，因此您不必在 GET 要求中提供 Authorization HTTP 標頭。

回應

如果要求成功，伺服器會傳回 200 OK HTTP 狀態碼和書架資源：

200 OK

{
  "kind": "books#bookshelf",
  "id": 3,
  "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
  "title": "Reading now",
  "description": "",
  "access": "PUBLIC",
  "updated": "2011-02-02T20:34:20.146Z",
  "created": "2011-02-02T20:34:20.146Z",
  "volumeCount": 2,
  "volumesLastUpdated": "2011-02-02T20:34:20.110Z"
}

選用查詢參數

擷取特定公開書櫃時，您可以使用標準查詢參數。

擷取公開書架上的書籍清單

您可以傳送 HTTP GET 要求，並使用下列格式的 URI，擷取使用者公開書櫃中的書籍清單：

https://www.googleapis.com/books/v1/user/userId/bookshelves/shelf/volumes

要求

範例如下：

GET https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3/volumes?key=yourAPIKey

將 userId 和 shelf 路徑參數替換為指定使用者和要擷取的書架的 ID。詳情請參閱「Google 圖書 ID」一節。

由於使用者無須經過驗證即可擷取有關公開書架的資訊，因此您不必在 GET 要求中提供 Authorization HTTP 標頭。

回應

如果要求成功，伺服器會傳回 200 OK HTTP 狀態碼，以及使用者的書架清單：

200 OK

{
 "kind": "books#volumes",
 "items": [
  {
   "kind": "books#volume",
   "id": "AZ5J6B1-4BoC",
   "etag": "kIzQA7IUObk",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/AZ5J6B1-4BoC",
   "volumeInfo": {
    "title": "The Girl Who Kicked the Hornet's Nest",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2010-05-25",
    ...
  },
  {
   "kind": "books#volume",
   "id": "UvK1Slvkz3MC",
   "etag": "otKmdbRgdFQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/UvK1Slvkz3MC",
   "volumeInfo": {
    "title": "The Girl who Played with Fire",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2009-07-28",
    ...
  },
  {
   "kind": "books#volume",
   "id": "OBM3AAAAIAAJ",
   "etag": "xb47kTr8HsQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/OBM3AAAAIAAJ",
   "volumeInfo": {
    "title": "The Sign of Four",
    "authors": [
     "Sir Arthur Conan Doyle"
    ],
    "publishedDate": "1890",
    ...
  }
 ],
 "totalItems": 3
}

選用查詢參數

除了標準查詢參數之外，您也可以在擷取公開書櫃中的書籍清單時使用下列查詢參數。

分頁

您可以在要求的參數中指定兩個值，藉此分頁顯示音量清單：

startIndex：在集合中開始的位置。第一個項目的索引為 0。
maxResults：要傳回的結果數上限。預設值為 10，最大允許值為 40。

使用「我的媒體庫」中的書架

所有「我的媒體庫」要求都會套用至經過驗證的使用者資料。

擷取我的書架清單

您可以傳送 HTTP GET 要求至 URI，並使用下列格式擷取已驗證使用者的所有書櫃清單：

https://www.googleapis.com/books/v1/mylibrary/bookshelves

要求

範例如下：

GET https://www.googleapis.com/books/v1/mylibrary/bookshelves?key=yourAPIKey
Authorization: /* auth token here */

注意：使用者必須經過驗證，才能擷取「我的圖書館」書架的清單。因此，您必須在 GET 要求中提供 Authorization HTTP 標頭。

回應

如果要求成功，伺服器會傳回 200 OK HTTP 狀態碼，以及目前已驗證使用者的所有書架清單：

200 OK

{
 "kind": "books#bookshelves",
 "items": [
  {
   "kind": "books#bookshelf",
   "id": 0,
   "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/0",
   "title": "Favorites",
   "access": "PRIVATE",
   "updated": "2011-04-22T04:03:15.416Z",
   "created": "2011-04-22T04:03:15.416Z",
   "volumeCount": 0,
   "volumesLastUpdated": "2011-04-22T04:03:17.000Z"
  },
  {
   "kind": "books#bookshelf",
   "id": 3,
   "selfLink": "https://www.googleapis.com/books/v1/users/1112223334445556677/bookshelves/3",
   "title": "Reading now",
   "access": "PUBLIC",
   "updated": "2010-11-11T19:44:22.377Z",
   "created": "2010-11-11T19:44:22.377Z",
   "volumeCount": 1,
   "volumesLastUpdated": "2010-11-11T19:44:22.341Z"
  }
 ]
}

選用查詢參數

擷取已驗證使用者書架清單時，您可以使用標準查詢參數。

擷取書架上的書籍清單

您可以傳送 HTTP GET 要求至 URI，並使用下列格式，擷取已驗證使用者書櫃中的書籍清單：

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

將 shelf 路徑參數替換為書架的 ID。如要進一步瞭解書架 ID，請參閱「Google 圖書 ID」一節。

要求

範例如下：

GET https://www.googleapis.com/books/v1/mylibrary/bookshelves/7/volumes?key=yourAPIKey
Authorization: /* auth token here */

注意：使用者必須經過驗證，才能擷取「我的媒體庫」叢書的清單。因此，您必須透過 GET 要求提供 Authorization HTTP 標頭。

回應

如果要求成功，伺服器會傳回 200 OK HTTP 狀態碼和書櫃書籍清單：

200 OK

{
 "kind": "books#volumes",
 "items": [
  {
   "kind": "books#volume",
   "id": "AZ5J6B1-4BoC",
   "etag": "kIzQA7IUObk",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/AZ5J6B1-4BoC",
   "volumeInfo": {
    "title": "The Girl Who Kicked the Hornet's Nest",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2010-05-25",
    ...
  },
  {
   "kind": "books#volume",
   "id": "UvK1Slvkz3MC",
   "etag": "otKmdbRgdFQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/UvK1Slvkz3MC",
   "volumeInfo": {
    "title": "The Girl who Played with Fire",
    "authors": [
     "Stieg Larsson"
    ],
    "publisher": "Knopf",
    "publishedDate": "2009-07-28",
    ...
  },
  {
   "kind": "books#volume",
   "id": "OBM3AAAAIAAJ",
   "etag": "xb47kTr8HsQ",
   "selfLink": "https://www.googleapis.com/books/v1/volumes/OBM3AAAAIAAJ",
   "volumeInfo": {
    "title": "The Sign of Four",
    "authors": [
     "Sir Arthur Conan Doyle"
    ],
    "publishedDate": "1890",
    ...
  }
 ],
 "totalItems": 3
}

選用查詢參數

除了標準查詢參數之外，您也可以在擷取已驗證使用者書架上的書籍清單時，使用下列查詢參數。

分頁

您可以在要求的參數中指定兩個值，藉此分頁顯示音量清單：

startIndex：在集合中開始的位置。第一個項目的索引為 0。
maxResults：要傳回的結果數上限。預設值為 10。

將書籍加入我的書櫃

如要將書籍加入已驗證使用者的書櫃，請對 URI 傳送格式如下的 HTTP POST 要求：

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

將「shelf」路徑參數替換為書架的 ID。如要進一步瞭解書架 ID，請參閱「Google 圖書 ID」一節。

要求含有一個必要的查詢參數：

volumeId：磁碟區 ID。如要進一步瞭解書籍 ID，請參閱「Google 圖書 ID」一節。

要求

以下範例說明如何將「Flowers for Algernon」加入「我的收藏」書架：

POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/addVolume?volumeId=NRWlitmahXkC&key=yourAPIKey
Authorization: /* auth token here */
Content-Type: application/json
Content-Length: CONTENT_LENGTH

注意：使用者必須經過驗證，才能修改書架，因此您必須在 POST 要求中提供 Authorization HTTP 標頭。不過，這個 POST 不需要任何資料。

回應

如果要求成功，伺服器會傳回 204 No Content HTTP 狀態碼。

選用查詢參數

您可以在將書籍新增至已驗證使用者的書架時，使用標準查詢參數。

從我的書櫃中移除書籍

如要從已驗證使用者的書櫃中移除單集，請使用以下格式，將 HTTP POST 傳送至 URI：

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

將 shelf 路徑參數替換為書架的 ID。如要進一步瞭解書架 ID，請參閱「Google 圖書 ID」一節。

要求含有一個必要的查詢參數：

volumeId：音量 ID。如要進一步瞭解書籍 ID，請參閱「Google 圖書 ID」一節。

要求

以下範例說明如何從「我的最愛」書櫃中移除「Flowers for Algernon」：

POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/removeVolume?volumeId=NRWlitmahXkC&key=yourAPIKey
Authorization: /* auth token here */
Content-Type: application/json
Content-Length: CONTENT_LENGTH

注意：使用者必須經過驗證，才能修改書架，因此您必須在 POST 要求中提供 Authorization HTTP 標頭。不過，這個 POST 不需要任何資料。

回應

如果要求成功，伺服器會傳回 204 No Content 狀態碼。

選用查詢參數

您可以使用標準查詢參數，從已驗證使用者的書架中移除單冊書籍。

清除書架上的所有書籍

如要從已驗證使用者的書櫃中移除所有書籍，請以以下格式將 HTTP POST 傳送至 URI：

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

將 shelf 路徑參數替換為書架的 ID。如要進一步瞭解書架 ID，請參閱「Google 圖書 ID」一節。

要求

以下範例說明如何清除「我的收藏」書架：

POST https://www.googleapis.com/books/v1/mylibrary/bookshelves/0/clearVolumes?key=yourAPIKey
Authorization: /* auth token here */
Content-Type: application/json
Content-Length: CONTENT_LENGTH

注意：使用者必須經過驗證，才能修改書架，因此您必須在 POST 要求中提供 Authorization HTTP 標頭。不過，這個 POST 不需要任何資料。

回應

如果要求成功，伺服器會傳回 204 No Content 狀態碼。

選用查詢參數

如要清除已驗證使用者書架上的所有書籍，您可以使用標準查詢參數。

查詢參數參考資料

本節將列出可搭配 Books API 使用的查詢參數。所有參數值都必須經過網址編碼。

標準查詢參數

適用於所有 Books API 作業的查詢參數，請參閱「系統參數」一文。

API 專屬查詢參數

下表列出僅適用於 Books API 中特定作業的要求參數。

參數	意義	附註	適用性
`download`	依下載可用性限制音量。	目前唯一支援的值是 `epub`。可能需要購買才能下載。	執行搜尋
`filter`	依據音量類型和可用性篩選搜尋結果。	支援的篩選器如下： `filter=partial`：限制結果只顯示至少部分文字可供預覽的音訊叢書。 `filter=full`：限制結果只包含可查看所有文字的音訊書。 `filter=free-ebooks` - 只顯示免費 Google 電子書。 `filter=paid-ebooks`：只顯示有購買價格的 Google 電子書。 `filter=ebooks` - 只顯示 Google 電子書 (付費或免費) 的搜尋結果。非電子書的例子包括出版商提供的試閱內容 (不供販售)，或雜誌。	執行搜尋
`langRestrict`	限制傳回的音量，只傳回標示為指定語言的音量。	將 `langRestrict` 指定為兩個英文字母組成的 ISO-639-1 代碼 (例如「en」或「fr」)，即可將搜尋結果限制為特定語言。	執行搜尋
`maxResults`	此要求可傳回的元素數量上限。	如要要求集合中的所有項目，您可以在要求的參數中指定 `startIndex` 和 `maxResults`，藉此分頁顯示結果。預設：`maxResults=10` 最大允許值：`maxResults=40.`	執行搜尋列出使用者的書架列出使用者書架的書籍列出我的書架列出書架上的書籍
`orderBy`	音量搜尋結果的順序。	根據預設，搜尋要求會傳回 `maxResults` 結果，其中 `maxResults` 是分頁中使用的參數，會依關聯性高低排序。您可以將 `orderBy` 參數設為下列任一值，即可變更排序： `orderBy=relevance`：依相關性高低順序傳回搜尋結果 (這是預設值)。 `orderBy=newest`：依發布日期 (最新到最舊) 傳回搜尋結果。	執行搜尋
`printType`	僅限書籍或雜誌。	支援的值如下： `printType=all` - 傳回所有音量內容類型 (無限制)。此為預設值。 `printType=books` - 只傳回書籍。 `printType=magazines` - 僅退回雜誌。	執行搜尋
`projection`	限制系統只能將音量資訊傳回部分欄位。	支援的投影方式如下： `projection=full`：包含所有音量中繼資料 (預設)。 `projection=lite`：僅包含卷標和存取權中繼資料的主旨。	執行搜尋擷取音量列出使用者書架的書籍列出書架上的書籍
`q`	全文查詢字串。	建立查詢時，請以「+」分隔搜尋字詞，並以 `q=term1+term2_term3` 的格式列出。(您也可以使用空格分隔，但與所有查詢參數值一樣，空格必須經過網址編碼)。API 會傳回符合所有搜尋字詞的所有項目 (例如在字詞之間使用 AND)。與 Google 網頁搜尋一樣，API 會搜尋完整字詞 (以及同字根的相關字詞)，而非子字串。如要搜尋完全相符的詞組，請用引號括住詞組：`q="exact phrase"`。如要排除與特定字詞相符的項目，請使用 `q=-term` 格式。搜尋字詞不區分大小寫。範例：如要搜尋包含確切字詞 `"Elizabeth Bennet"` 和字詞 `"Darcy"` 的所有項目，但不包含字詞 `"Austen"`，請使用以下查詢參數值：`q="Elizabeth+Bennet"+Darcy-Austen` 您可以在搜尋字詞中指定特殊 (區分大小寫) 關鍵字，以便在特定欄位中搜尋，例如： `intitle`：傳回結果，其中標題會出現這個關鍵字後方的文字。 `inauthor`：找出作者中含有此關鍵字後方的文字。 `inpublisher`：如果發布者中出現關鍵字後面的文字，就會傳回結果。 `subject`：傳回結果，其中關鍵字後面的文字會列在書籍的類別清單中。 `isbn`：傳回結果，其中此關鍵字後方的文字是 ISBN 編號。 `lccn`：傳回的結果中，此關鍵字後面的文字為美國國會圖書館控制編號。 `oclc`：傳回結果，其中此關鍵字後方的文字是線上電腦圖書館中心編號。	執行搜尋
`startIndex`	在集合中開始列出結果清單的位置。	如要要求集合中的所有項目，您可以在要求的參數中指定 `startIndex` 和 `maxResults`，藉此分頁顯示結果。第一個項目的索引為 0。	執行搜尋列出使用者的書架列出使用者書架的書籍列出我的書架列出書架上的書籍
`volumeId`	用於識別與要求相關聯的音量。	指定要從書櫃中新增或移除的書籍。	將書籍加入書架從我的書架上移除書籍

使用 API

目錄

簡介

授權要求和識別應用程式

關於授權通訊協定

使用 OAuth 2.0 對要求進行授權

取得並使用 API 金鑰

Google 圖書 ID

Google 圖書網站上的 ID

設定使用者位置

使用磁碟區

執行搜尋

要求

回應

選用查詢參數

下載格式

篩選

分頁

列印類型

投影

排序

擷取特定音量

要求

回應

存取資訊

選用查詢參數

投影

使用書架

擷取使用者的公開書架清單

要求

回應

選用查詢參數

擷取特定公開書架

要求

回應

選用查詢參數

擷取公開書架上的書籍清單

要求

回應

選用查詢參數

分頁

使用「我的媒體庫」中的書架

擷取我的書架清單

要求

回應

選用查詢參數

擷取書架上的書籍清單

要求

回應

選用查詢參數

分頁

將書籍加入我的書櫃

要求

回應

選用查詢參數

從我的書櫃中移除書籍

要求

回應

選用查詢參數

清除書架上的所有書籍

要求

回應

選用查詢參數

查詢參數參考資料

標準查詢參數

API 專屬查詢參數