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

使用 API

簡介

本文件可協助開發人員編寫可與 Books API 互動的應用程式。Google 圖書的目標是將全球圖書內容數位化，讓使用者更容易透過網路找到書籍。Books 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 金鑰)，在控制台中建立 API 金鑰。您可以先設定限制，然後再按一下「Restrict key」(限制金鑰) 並選取其中一個限制，即可對該金鑰設下限制。

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

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

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

Google 圖書 ID

您必須使用特定 API 方法呼叫指定 ID 欄位。Google 圖書會使用以下三種類型的身分證件：

書冊 ID：Google 圖書所知各冊的不重複字串。磁碟區 ID 的範例為 _LettPDhwR0C。您可以使用 API 提出磁碟區 ID，方法是提出傳回磁碟區資源的要求，並在其 id 欄位中尋找磁碟區 ID。
書架 ID - 使用者庫中某個書架的數值。Google 會為每位使用者提供下列 ID 的預先定義書架：
- 我的收藏：0
- 購買日期：1
- 閱讀：2
- 立即閱讀：3
- 已讀：4
- 已審查：5
- 最近檢視： 6
- 我的電子書：7
- 為你推薦的書籍：8 如果沒有提供給使用者的推薦書籍，就不會顯示這個書架。
自訂書架的 ID 大於 1000。對特定使用者而言，書架 ID 是唯一的，意即兩位使用者可以擁有參照不同書架的相同 ID 的書架。您可以使用 API 透過提出傳回 Bookshelf 資源的要求來取得書架 ID；您可以在其 id 欄位中找到書架 ID。
User ID - 指派給每位使用者的不重複數值。這些值不一定等於其他 Google 服務使用的 ID 值。目前擷取使用者 ID 的唯一方法是從使用已驗證的要求擷取的 Bookshelf 資源中，從 selfLink 擷取出使用者 ID。使用者也可以在圖書網站取得自己的使用者 ID。使用者無法透過 API 或圖書網站取得其他使用者的使用者 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
```

書架 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: 傳回此關鍵字後方文字是國會控制號碼 (Library of Congress Control Number) 的結果。
- oclc: 傳回結果，其中這段關鍵字下方的文字是 Online Computer Library Center 編號。

要求

以下舉例說明如何搜尋 Daniel Keyes 的「Flowers for Algernon」：

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

注意：執行搜尋不需要驗證，因此您不必透過 GET 要求提供 Authorization HTTP 標頭。不過，如果呼叫是以驗證方式發出，則每個磁碟區都會包含使用者專屬資訊，例如購買狀態。

回覆

如果要求成功，伺服器會以 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 參數搭配下列其中一個值，指定要傳回的一組預先定義的磁碟區欄位：

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

擷取特定磁碟區

您可以擷取特定磁碟區的資訊，方法是將 HTTP GET 要求傳送至磁碟區資源 URI：

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 標頭。不過，如果呼叫是透過驗證機制發出，磁碟區就會包含使用者專屬資訊，例如購買狀態。

回覆

如果要求成功，伺服器會傳回包含 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 檔案提供給電子書閱讀器和 SmartPhone，因為這類裝置的掃描頁面可能難以閱讀。如果沒有 accessInfo 部分，就表示 Google 電子書未提供該冊。

選用查詢參數

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

投影

您可以使用 projection 參數搭配下列其中一個值，指定要傳回的一組預先定義的磁碟區欄位：

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」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 狀態碼回應，也會傳回 Bookshelf 資源：

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 狀態碼和 Bookshelf 磁碟區清單：

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。

新增磁碟區到我的書架

如要將磁碟區新增至已驗證使用者的書架，請使用下列格式將 HTTP POST 要求傳送至 URI：

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

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

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

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

要求

以下範例說明如何在「Favorites」書架上新增「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」一節。

要求

以下範例說明如何從「Favorites」書架中移除「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`：傳回此關鍵字後方文字是國會控制號碼 (Library of Congress Control Number) 的結果。 `oclc`：傳回此關鍵字後方文字為「線上電腦圖書館中心」號碼的結果。	執行搜尋
`startIndex`	集合中開始結果清單的位置。	針對集合中所有項目的要求，您可以在要求的參數中指定 `startIndex` 和 `maxResults`，將結果分頁。第一個項目的索引為 0。	執行搜尋列出使用者書架列出使用者書架磁碟區列出我的書架列出我的書架磁碟區
`volumeId`	識別與要求相關聯的磁碟區。	指定要在書架中新增或移除的磁碟區。	在我的書架上新增磁碟區移除書架中的磁碟區

使用 API

目錄

簡介

授權要求並識別您的應用程式

關於授權通訊協定

使用 OAuth 2.0 對要求進行授權

取得及使用 API 金鑰

Google 圖書 ID

Google 圖書網站上的 ID

設定使用者位置

使用磁碟區

執行搜尋

要求

回覆

選用查詢參數

下載格式

篩選

分頁

印刷類型

投影

排序

擷取特定磁碟區

要求

回覆

存取權資訊

選用查詢參數

投影

使用書架

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

要求

回覆

選用查詢參數

擷取特定的公開書架

要求

回覆

選用查詢參數

擷取公開書架上的磁碟區清單

要求

回覆

選用查詢參數

分頁

使用「我的圖書館」中的書架

擷取我的書架清單

要求

回覆

選用查詢參數

在我的書架上擷取磁碟區清單

要求

回覆

選用查詢參數

分頁

新增磁碟區到我的書架

要求

回覆

選用查詢參數

從我的書架中移除磁碟區

要求

回覆

選用查詢參數

清除我的書架中的所有磁碟區

要求

回覆

選用查詢參數

查詢參數參考資料

標準查詢參數

API 專屬查詢參數