Sử dụng API

Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Nội dung

Giới thiệu

Tài liệu này dành cho các nhà phát triển muốn viết ứng dụng có thể tương tác với API Sách. Google Sách có sứ mệnh số hoá nội dung sách trên thế giới và giúp mọi người dễ dàng tìm thấy nội dung đó trên Web. API Sách là một cách để tìm kiếm và truy cập nội dung đó, cũng như tạo và xem hoạt động cá nhân hoá nội dung đó.

Nếu chưa hiểu rõ các khái niệm về Google Sách, bạn nên đọc bài viết Bắt đầu trước khi bắt đầu lập trình.

Cấp phép cho các yêu cầu và xác định ứng dụng

Mọi yêu cầu mà ứng dụng của bạn gửi tới Book API cần phải xác định được ứng dụng của bạn cho Google. Có 2 cách để xác định ứng dụng của bạn: sử dụng mã thông báo OAuth 2.0 (cũng đã ủy quyền cho yêu cầu) và/hoặc sử dụng khóa API của ứng dụng. Sau đây là cách xác định tuỳ chọn nào trong số đó để sử dụng:

  • Nếu yêu cầu cần được cho phép (chẳng hạn như yêu cầu về dữ liệu riêng tư của một cá nhân), ứng dụng phải cung cấp mã thông báo OAuth 2.0 theo yêu cầu. Ứng dụng cũng có thể cung cấp khoá API, nhưng không bắt buộc.
  • Nếu yêu cầu không yêu cầu uỷ quyền (chẳng hạn như yêu cầu dữ liệu công khai), thì ứng dụng phải cung cấp khoá API hoặc mã thông báo OAuth 2.0 hoặc cả hai — bất kỳ tuỳ chọn nào thuận tiện nhất cho bạn.

Giới thiệu về giao thức cấp phép

Ứng dụng của bạn phải sử dụng OAuth 2.0 để cấp phép các yêu cầu. Chúng tôi không hỗ trợ giao thức cấp phép nào khác. Nếu ứng dụng của bạn sử dụng chức năng Đăng nhập bằng Google, thì Google sẽ giúp bạn xử lý một số bước trong quá trình cấp phép.

Cấp phép cho các yêu cầu bằng OAuth 2.0

Yêu cầu API Sách cho dữ liệu người dùng không công khai phải được một người dùng đã xác thực cấp phép.

Các chi tiết của quy trình cấp phép đối với OAuth 2.0 sẽ khác nhau đôi chút tuỳ thuộc vào loại ứng dụng bạn đang viết. Quy trình chung sau đây áp dụng cho tất cả các loại ứng dụng:

  1. Khi tạo ứng dụng của mình, bạn sẽ đăng ký ứng dụng bằng Google API Console. Sau đó, Google cung cấp thông tin bạn sẽ cần sau này, chẳng hạn như ID ứng dụng khách và khoá bí mật của ứng dụng.
  2. Kích hoạt API Sách trong Bảng điều khiển API của Google. (Nếu API không được liệt kê trong API Console, thì hãy bỏ qua bước này.)
  3. Khi cần quyền truy cập vào dữ liệu người dùng, ứng dụng sẽ yêu cầu Google cung cấp phạm vi truy cập cụ thể.
  4. Google hiển thị màn hình yêu cầu sự đồng ý cho người dùng để hỏi xem họ có cho phép ứng dụng của bạn yêu cầu một số dữ liệu của họ hay không.
  5. Nếu người dùng đồng ý, thì Google sẽ cấp cho ứng dụng của bạn một mã truy cập ngắn hạn.
  6. Sau đó, ứng dụng yêu cầu dữ liệu người dùng và đính kèm mã truy cập trong yêu cầu.
  7. Nếu xác định rằng yêu cầu của bạn và mã này là hợp lệ, Google sẽ trả về dữ liệu mà ứng dụng yêu cầu.

Một số quy trình cấp phép có các bước bổ sung khác, chẳng hạn như sử dụng mã làm mới để lấy mã truy cập mới. Để biết thông tin chi tiết về quy trình cho các loại ứng dụng khác nhau, hãy xem tài liệu về OAuth 2.0 của Google.

Dưới đây là thông tin về phạm vi truy cập của OAuth 2.0 cho API sách:

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

Để yêu cầu quyền truy cập bằng OAuth 2.0, ứng dụng của bạn cần thông tin về mức truy cập, cũng như thông tin mà Google cung cấp khi bạn đăng ký ứng dụng của mình (chẳng hạn như ID ứng dụng khách và khoá bí mật của ứng dụng).

Mẹo: Thư viện ứng dụng API Google có thể xử lý một số bước trong quy trình cấp phép cho bạn. Thư viện này được cung cấp bằng nhiều ngôn ngữ lập trình. Hãy xem trang về các thư viện và mẫu để biết thêm chi tiết.

Thu nạp và sử dụng khoá API

Các yêu cầu gửi tới API sách dành cho dữ liệu công khai phải đi kèm với giá trị nhận dạng, có thể là khóa API hoặc mã truy cập.

Cách lấy khoá API:

  1. Mở trang Thông tin xác thực trong Bảng điều khiển API.
  2. API này hỗ trợ hai loại thông tin đăng nhập. Tạo thông tin xác thực phù hợp với dự án của bạn:
    • OAuth 2.0: Bất cứ khi nào ứng dụng yêu cầu dữ liệu riêng tư của người dùng, ứng dụng đó phải gửi mã thông báo OAuth 2.0 cùng với yêu cầu đó. Trước tiên, ứng dụng của bạn sẽ gửi một mã ứng dụng và có thể là một mã bí mật của ứng dụng để lấy mã thông báo. Bạn có thể tạo thông tin xác thực OAuth 2.0 cho ứng dụng web, tài khoản dịch vụ hoặc ứng dụng đã cài đặt.

      Để biết thêm thông tin, hãy xem tài liệu về OAuth 2.0.

    • Khoá API: Yêu cầu không cung cấp mã thông báo OAuth 2.0 phải gửi khoá API. Khoá này xác định dự án của bạn và cung cấp quyền truy cập vào API, hạn mức và báo cáo.

      API hỗ trợ một số loại quy định hạn chế đối với khoá API. Nếu khoá API bạn cần chưa tồn tại, hãy tạo khoá API trong Bảng điều khiển bằng cách nhấp vào Tạo thông tin xác thực > khoá API. Bạn có thể hạn chế khoá trước khi sử dụng trong bản phát hành chính thức bằng cách nhấp vào Hạn chế khoá rồi chọn một trong các Hạn chế.

Để bảo mật khoá API, hãy làm theo các phương pháp hay nhất để sử dụng khoá API một cách an toàn.

Sau khi bạn có khóa API, ứng dụng có thể thêm tham số truy vấn key=yourAPIKey vào tất cả URL yêu cầu.

Khóa API an toàn để nhúng vào URL; nó không cần bất kỳ mã hóa nào.

Mã Google Sách

Bạn cần chỉ định các trường mã nhận dạng bằng một số lệnh gọi phương thức API nhất định. Có ba loại mã nhận dạng được sử dụng trong Google Sách:

  • Mã nhận dạng tập – Các chuỗi duy nhất được cung cấp cho từng tập mà Google Sách biết. Ví dụ về mã số là _LettPDhwR0C. Bạn có thể sử dụng API để lấy mã âm lượng bằng cách tạo một yêu cầu trả về tài nguyên Âm lượng; bạn có thể tìm thấy mã âm lượng trong trường id của nó.
  • Mã giá sách – Các giá trị số được cung cấp cho một giá sách trong thư viện của người dùng. Google cung cấp một số giá sách được xác định trước cho mọi người dùng có các mã sau:
    • Mục yêu thích: 0
    • Đã mua: 1
    • Cách đọc: 2
    • Đang đọc: 3
    • Đã đọc: 4
    • Đã xem xét: 5
    • Đã xem gần đây: 6
    • Sách điện tử của tôi: 7
    • Sách dành cho bạn: 8 Nếu chúng tôi không có đề xuất nào cho người dùng, thì kệ này không tồn tại.
    Giá trị tùy chỉnh có mã nhận dạng lớn hơn 1000. Mã nhận dạng giá sách là giá trị duy nhất đối với một người dùng cụ thể, tức là hai người dùng có thể có một giá sách có cùng một mã nhận dạng để tham chiếu đến nhiều giá sách. Bạn có thể sử dụng API để lấy mã giá sách bằng cách tạo một yêu cầu trả về tài nguyên giá sách; bạn có thể tìm thấy mã giá sách trong trường id của giá sách đó.
  • Mã nhận dạng khách hàng – Giá trị số duy nhất được chỉ định cho từng người dùng. Các giá trị này không nhất thiết phải giống với giá trị nhận dạng được dùng trong các dịch vụ khác của Google. Hiện tại, cách duy nhất để truy xuất mã nhận dạng người dùng là trích xuất mã đó từ đường liên kết tự liên kết trong tài nguyên Bookshelf được truy xuất bằng yêu cầu đã xác thực. Người dùng cũng có thể lấy mã nhận dạng khách hàng của riêng mình trên trang web Sách. Người dùng không được lấy mã nhận dạng người dùng cho một người dùng khác qua API hoặc trang web Sách; ví dụ: người dùng còn lại phải chia sẻ rõ ràng thông tin đó qua email.

Mã trên trang web của Google Sách

Mã nhận dạng mà bạn sử dụng với API Sách cũng giống như mã nhận dạng được sử dụng trên trang web Google Sách.

  • Mã tập

    Khi xem một tập đĩa cụ thể trên trang web, bạn có thể tìm thấy ID âm lượng trong thông số URL id. Sau đây là ví dụ:

    https://books.google.com/ebooks?id=buc0AAAAMAAJ&dq=holmes&as_brr=4&source=webstore_bookcard

  • Mã giá sách

    Khi xem một giá sách cụ thể trên trang web, bạn có thể tìm thấy mã giá sách trong tham số URL as_coll. Sau đây là ví dụ:

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

  • Mã nhận dạng khách hàng

    Khi xem thư viện của bạn trên trang web, bạn có thể tìm thấy mã nhận dạng người dùng trong tham số URL uid. Sau đây là ví dụ:

    https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list

Đặt vị trí của người dùng

Google Sách tôn trọng bản quyền, hợp đồng và các quy định hạn chế khác về mặt pháp lý liên quan đến vị trí của người dùng cuối. Do đó, một số người dùng có thể không truy cập được nội dung sách ở một số quốc gia nhất định. Ví dụ: một số sách nhất định là "previewable" chỉ ở Hoa Kỳ; chúng tôi bỏ qua các đường liên kết xem trước như vậy cho người dùng ở các quốc gia khác. Do đó, kết quả API bị hạn chế dựa trên địa chỉ IP của máy chủ hoặc ứng dụng khách của bạn.

Làm việc với số lượng

Tìm kiếm

Bạn có thể tìm kiếm các khối lượng bằng cách gửi yêu cầu HTTP GET đến URI sau:

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

Yêu cầu này có một thông số bắt buộc duy nhất:

  • q – Tìm những đĩa có chứa chuỗi văn bản này. Bạn có thể chỉ định các từ khóa đặc biệt trong các cụm từ tìm kiếm để tìm kiếm trong một số trường cụ thể, chẳng hạn như:
    • intitle: Trả về kết quả mà văn bản theo sau từ khoá này được tìm thấy trong tiêu đề.
    • inauthor: Trả về kết quả khi tìm thấy văn bản sau từ khoá này trong tác giả.
    • inpublisher: Trả về kết quả mà nhà xuất bản tìm thấy sau văn bản này.
    • subject: Trả về kết quả trong đó văn bản theo sau từ khoá này được liệt kê trong danh sách danh mục của tập.
    • isbn: Trả về kết quả mà văn bản sau từ khoá này là số ISBN.
    • lccn: Trả về kết quả mà văn bản theo sau từ khoá này là Số kiểm soát của Thư viện Quốc hội.
    • oclc: Trả về kết quả mà văn bản sau từ khoá này là số của Trung tâm thư viện máy tính trực tuyến.

Yêu cầu

Sau đây là ví dụ về cách tìm kiếm Daniel Keyes&3t; "Flowers for Algernon":

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

Lưu ý: Việc tìm kiếm không yêu cầu xác thực, vì vậy, bạn không phải cung cấp tiêu đề HTTP Authorization kèm theo yêu cầu GET. Tuy nhiên, nếu lệnh gọi được thực hiện bằng tính năng xác thực, thì mỗi Âm lượng sẽ bao gồm thông tin dành riêng cho người dùng, chẳng hạn như trạng thái đã mua.

Phản hồi

Nếu yêu cầu thành công, máy chủ sẽ phản hồi bằng mã trạng thái HTTP 200 OK và kết quả khối lượng:

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
}

Tham số truy vấn tùy chọn

Ngoài các tham số truy vấn chuẩn, bạn có thể sử dụng các tham số truy vấn sau khi thực hiện tìm kiếm theo số lượng.

Định dạng tải xuống

Bạn sử dụng thông số download để hạn chế kết quả được trả về về đĩa có định dạng tải xuống epub sẵn có bằng cách đặt thành giá trị epub.

Ví dụ sau đây tìm kiếm sách có bản tải xuống epub:

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

Bạn có thể sử dụng thông số filter để hạn chế hơn nữa kết quả được trả về bằng cách đặt thông số này thành một trong các giá trị sau:

  • partial – Trả về kết quả trong đó có thể xem trước ít nhất một phần của văn bản.
  • full – Chỉ trả về kết quả trong đó tất cả văn bản đều có thể xem được.
  • free-ebooks – Chỉ trả về kết quả là sách điện tử miễn phí trên Google.
  • paid-ebooks – Chỉ trả về kết quả là sách điện tử của Google kèm theo giá.
  • ebooks – Chỉ trả về những kết quả là Google Sách điện tử, có tính phí hoặc miễn phí. Ví dụ về nội dung không phải sách điện tử sẽ là nội dung dành cho nhà xuất bản ở chế độ xem trước có giới hạn và không phải để bán hoặc tạp chí.

Ví dụ sau đây giới hạn kết quả tìm kiếm trong các kết quả có sẵn dưới dạng sách điện tử miễn phí:

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

Bạn có thể phân trang danh sách tập bằng cách chỉ định hai giá trị trong tham số cho yêu cầu:

  • startIndex – Vị trí trong bộ sưu tập để bắt đầu. Chỉ mục của mục đầu tiên là 0.
  • maxResults – Số lượng kết quả tối đa cần trả về. Giá trị mặc định là 10 và giá trị tối đa cho phép là 40.

Bạn có thể sử dụng thông số printType để hạn chế kết quả được trả về thành một loại ấn bản hoặc bản in cụ thể bằng cách đặt thông số này thành một trong các giá trị sau:

  • all – Không hạn chế theo loại in (mặc định).
  • books – Chỉ trả về kết quả là sách.
  • magazines – Trả về kết quả là tạp chí.

Ví dụ sau sẽ hạn chế kết quả tìm kiếm trong tạp chí:

GET https://www.googleapis.com/books/v1/volumes?q=time&printType=magazines&key=yourAPIKey
Dự đoán

Bạn có thể sử dụng thông số projection với một trong các giá trị sau để chỉ định một tập hợp các trường Âm lượng được xác định trước sẽ trả về:

  • full – Trả về tất cả các trường Âm lượng.
  • lite – Chỉ trả về một số trường nhất định. Xem nội dung mô tả các trường được đánh dấu bằng dấu hoa thị kép trong Tài liệu tham khảo về âm lượng để tìm hiểu xem những trường nào được đưa vào.

Ví dụ sau đây trả về kết quả tìm kiếm chứa thông tin về số lượng hạn chế:

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

Theo mặc định, yêu cầu tìm kiếm khối lượng trả về kết quả maxResults, trong đó maxResults là thông số dùng trong quá trình phân trang (ở trên) được sắp xếp theo mức độ liên quan đến cụm từ tìm kiếm.

Bạn có thể thay đổi thứ tự bằng cách đặt thông số orderBy thành một trong các giá trị sau:

  • relevance – Trả về kết quả theo thứ tự mức độ liên quan của cụm từ tìm kiếm (đây là giá trị mặc định).
  • newest – Trả về kết quả theo thứ tự từ mới nhất đến ít xuất bản gần đây.

Ví dụ sau đây liệt kê kết quả theo ngày xuất bản, mới nhất đến cũ nhất:

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

Đang truy xuất âm lượng cụ thể

Bạn có thể truy xuất thông tin của một ổ đĩa cụ thể bằng cách gửi yêu cầu HTTP GET đến URI tài nguyên của ổ đĩa:

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

Hãy thay tham số đường dẫn volumeId bằng mã của phương tiện để truy xuất. Hãy xem mục Mã Google Sách để biết thêm thông tin về mã tập.

Yêu cầu

Dưới đây là ví dụ về yêu cầu GET nhận một khối lượng duy nhất:

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

Lưu ý: Việc truy xuất thông tin số lượng không yêu cầu xác thực, vì vậy, bạn không phải cung cấp tiêu đề HTTP Authorization kèm theo yêu cầu GET. Tuy nhiên, nếu lệnh gọi được thực hiện bằng quy trình xác thực, Âm lượng sẽ bao gồm thông tin dành riêng cho người dùng, chẳng hạn như trạng thái đã mua.

Phản hồi

Nếu yêu cầu thành công, máy chủ sẽ phản hồi bằng mã trạng thái HTTP 200 OK và tài nguyên Âm lượng được yêu cầu:

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"
 }
}
Thông tin về quyền truy cập

Phần accessInfo đặc biệt quan tâm đến việc xác định các tính năng dành cho sách điện tử. epub là một định dạng sách điện tử định dạng tự ngắt dòng, phần epub sẽ có một thuộc tính isAvailable cho biết có loại sách điện tử này hay không. Sách sẽ có đường liên kết tải xuống nếu có mẫu cho sách hoặc nếu người dùng có thể đọc sách do đã mua sách hoặc do cuốn sách đó đang ở miền công cộng tại vị trí của người dùng. pdf cho Google Sách cho biết phiên bản trang được quét của sách điện tử với các thông tin chi tiết tương tự như sách có sẵn và đường liên kết để tải xuống. Google đề xuất các tệp epub cho máy đọc sách điện tử và điện thoại thông minh, vì các trang được quét có thể khó đọc trên các thiết bị này. Nếu không có phần accessInfo, thì sách sẽ không có sẵn dưới dạng Sách điện tử trên Google.

Tham số truy vấn tùy chọn

Ngoài các tham số truy vấn chuẩn, bạn có thể sử dụng các tham số truy vấn sau khi truy xuất một ổ đĩa cụ thể.

Dự đoán

Bạn có thể sử dụng thông số projection với một trong các giá trị sau để chỉ định một tập hợp các trường Âm lượng được xác định trước sẽ trả về:

  • full – Trả về tất cả các trường Âm lượng.
  • lite – Chỉ trả về một số trường nhất định. Xem nội dung mô tả các trường được đánh dấu bằng dấu hoa thị kép trong Tài liệu tham khảo về âm lượng để tìm hiểu xem những trường nào được đưa vào.

Ví dụ sau đây trả về thông tin ổ đĩa bị hạn chế cho một ổ đĩa:

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

Làm việc với giá sách

Đang truy xuất danh sách giá sách công khai của người dùng

Bạn có thể truy xuất danh sách giá sách công khai của người dùng bằng cách gửi yêu cầu HTTP GET đến URI có định dạng sau:

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

Thay thế thông số đường dẫn userId bằng mã nhận dạng của người dùng có giá sách mà bạn muốn truy xuất. Hãy xem phần Mã Google Sách để biết thêm thông tin về mã nhận dạng khách hàng.

Yêu cầu

Dưới đây là ví dụ:

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

Vì người dùng không phải xác thực để truy xuất thông tin liên quan đến giá sách công khai, nên bạn không cần cung cấp tiêu đề HTTP Authorization với yêu cầu GET.

Phản hồi

Nếu yêu cầu thành công, máy chủ sẽ phản hồi bằng mã trạng thái HTTP 200 OK và danh sách giá sách:

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"
  },
  ...
 ]
}

Tham số truy vấn tùy chọn

Bạn có thể sử dụng các tham số truy vấn chuẩn khi truy xuất danh sách giá sách công khai của người dùng.

Truy xuất giá sách công khai cụ thể

Bạn có thể truy xuất một giá sách công khai cụ thể bằng cách gửi yêu cầu HTTP GET đến URI có định dạng như sau:

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

Thay thế các tham số đường dẫn userIdgiá bằng các mã nhận dạng chỉ định người dùng và giá sách bạn muốn truy xuất. Hãy xem mục Mã Google Sách để biết thêm thông tin.

Yêu cầu

Dưới đây là ví dụ:

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

Vì người dùng không phải xác thực để truy xuất thông tin liên quan đến giá sách công khai, nên bạn không cần cung cấp tiêu đề HTTP Authorization với yêu cầu GET.

Phản hồi

Nếu yêu cầu thành công, máy chủ sẽ phản hồi bằng mã trạng thái HTTP 200 OK và tài nguyên giá sách:

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"
}

Tham số truy vấn tùy chọn

Bạn có thể sử dụng các tham số truy vấn chuẩn khi truy xuất một giá sách công khai cụ thể.

Đang truy xuất danh sách các tập trên giá sách công khai

Bạn có thể truy xuất danh sách các phương tiện nhớ trên giá sách công khai của người dùng bằng cách gửi yêu cầu HTTP GET với URI có định dạng sau:

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

Yêu cầu

Dưới đây là ví dụ:

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

Thay thế các tham số đường dẫn userIdgiá bằng các mã nhận dạng chỉ định người dùng và giá sách bạn muốn truy xuất. Hãy xem mục Mã Google Sách để biết thêm thông tin.

Vì người dùng không phải xác thực để truy xuất thông tin liên quan đến giá sách công khai, nên bạn không cần cung cấp tiêu đề HTTP Authorization với yêu cầu GET.

Phản hồi

Nếu yêu cầu thành công, máy chủ sẽ phản hồi bằng mã trạng thái HTTP 200 OK và danh sách giá sách của người dùng:

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
}

Tham số truy vấn tùy chọn

Ngoài các tham số truy vấn chuẩn, bạn có thể sử dụng tham số truy vấn sau đây khi truy xuất danh sách các tập trên giá sách công khai.

Phân trang

Bạn có thể phân trang danh sách tập bằng cách chỉ định hai giá trị trong tham số cho yêu cầu:

  • startIndex – Vị trí trong bộ sưu tập để bắt đầu. Chỉ mục của mục đầu tiên là 0.
  • maxResults – Số lượng kết quả tối đa cần trả về. Giá trị mặc định là 10 và giá trị tối đa cho phép là 40.

Làm việc với các giá sách trong "Thư viện của tôi"

Tất cả "Thư viện của tôi" yêu cầu áp dụng cho dữ liệu của người dùng đã được xác thực.

Đang truy xuất danh sách giá sách

Bạn có thể truy xuất danh sách tất cả giá sách của người dùng đã xác thực bằng cách gửi yêu cầu HTTP GET đến URI có định dạng sau:

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

Yêu cầu

Dưới đây là ví dụ:

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

Lưu ý: Người dùng phải được xác thực để truy xuất danh sách "Thư viện của tôi" giá sách. Vì vậy, bạn phải cung cấp tiêu đề HTTP Authorization với yêu cầu GET.

Phản hồi

Nếu yêu cầu thành công, máy chủ sẽ phản hồi bằng mã trạng thái HTTP 200 OK và danh sách tất cả giá sách của người dùng hiện tại đã xác thực:

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"
  }
 ]
}

Tham số truy vấn tùy chọn

Bạn có thể sử dụng các tham số truy vấn chuẩn khi truy xuất danh sách giá sách của người dùng đã xác thực.

Đang truy xuất danh sách các tập trên giá sách của tôi

Bạn có thể truy xuất danh sách các phương tiện nhớ trên giá sách của người dùng đã xác thực bằng cách gửi yêu cầu HTTP GET đến URI có định dạng sau:

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

Thay thế thông số đường dẫn giá bằng mã giá sách. Hãy xem mục Mã Google Sách để biết thêm thông tin về mã giá sách.

Yêu cầu

Dưới đây là ví dụ:

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

Lưu ý: Người dùng phải được xác thực để truy xuất danh sách "Thư viện của tôi" tập. Vì vậy, bạn phải cung cấp tiêu đề HTTP Authorization kèm theo yêu cầu GET.

Phản hồi

Nếu yêu cầu thành công, máy chủ sẽ phản hồi bằng mã trạng thái HTTP 200 OK và danh sách tập sách sách:

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
}

Tham số truy vấn tùy chọn

Ngoài các tham số truy vấn chuẩn, bạn có thể sử dụng tham số truy vấn sau khi truy xuất danh sách các tập trên một trong những giá sách của người dùng đã xác thực.

Phân trang

Bạn có thể phân trang danh sách tập bằng cách chỉ định hai giá trị trong tham số cho yêu cầu:

  • startIndex – Vị trí trong bộ sưu tập để bắt đầu. Chỉ mục của mục đầu tiên là 0.
  • maxResults – Số lượng kết quả tối đa cần trả về. Giá trị mặc định là 10.

Đang thêm một ổ đĩa vào giá sách của tôi

Để thêm một ổ đĩa vào giá sách của người dùng đã xác thực, hãy gửi yêu cầu HTTP POST qua URI có định dạng sau:

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

Thay thế thông số đường dẫn giá bằng mã giá sách. Hãy xem mục Mã Google Sách để biết thêm thông tin về mã giá sách.

Yêu cầu có một tham số truy vấn bắt buộc:

  • volumeId – Mã của tập. Hãy xem mục Mã Google Sách để biết thêm thông tin về mã nhận dạng đĩa.

Yêu cầu

Dưới đây là ví dụ về cách thêm "Hoa cho Algernon" vào &&t=;Yêu thích" giá sách:

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

Lưu ý: Người dùng phải được xác thực để chỉnh sửa giá sách, vì vậy, bạn phải cung cấp tiêu đề HTTP Authorization kèm theo yêu cầu POST. Tuy nhiên, bạn không cần phải sử dụng dữ liệu này thông qua POST này.

Phản hồi

Nếu yêu cầu thành công, máy chủ sẽ phản hồi bằng mã trạng thái HTTP 204 No Content.

Tham số truy vấn tùy chọn

Bạn có thể sử dụng các tham số truy vấn chuẩn khi thêm một ổ đĩa vào một trong các giá sách đã được xác thực của người dùng.

Tôi đang xoá một ổ đĩa khỏi giá sách

Để xoá một phương tiện ghi khỏi giá sách của người dùng đã xác thực, hãy gửi một HTTP POST đến URI có định dạng sau:

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

Thay thế thông số đường dẫn giá bằng mã giá sách. Hãy xem mục Mã Google Sách để biết thêm thông tin về mã giá sách.

Yêu cầu có một tham số truy vấn bắt buộc:

  • volumeId – Mã của tập. Hãy xem mục Mã Google Sách để biết thêm thông tin về mã nhận dạng đĩa.

Yêu cầu

Sau đây là ví dụ về việc xoá "Flowers for Algernon" khỏi the "Favorite" bookshelf:

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

Lưu ý: Người dùng phải được xác thực để chỉnh sửa giá sách, vì vậy, bạn phải cung cấp tiêu đề HTTP Authorization kèm theo yêu cầu POST. Tuy nhiên, bạn không cần phải sử dụng dữ liệu này thông qua POST này.

Phản hồi

Nếu yêu cầu thành công, máy chủ sẽ phản hồi bằng mã trạng thái 204 No Content.

Tham số truy vấn tùy chọn

Bạn có thể sử dụng các tham số truy vấn chuẩn khi xóa một ổ đĩa khỏi một trong những giá sách của người dùng đã xác thực.

Đang xóa tất cả các tập khỏi giá sách của tôi

Để xoá tất cả các phương tiện nhớ khỏi giá sách của người dùng đã xác thực, hãy gửi POST HTTP đến URI có định dạng sau:

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

Thay thế thông số đường dẫn giá bằng mã giá sách. Hãy xem mục Mã Google Sách để biết thêm thông tin về mã giá sách.

Yêu cầu

Sau đây là ví dụ về cách xóa "Mục yêu thích" giá sách:

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
  

Lưu ý: Người dùng phải được xác thực để chỉnh sửa giá sách, vì vậy, bạn phải cung cấp tiêu đề HTTP Authorization kèm theo yêu cầu POST. Tuy nhiên, bạn không cần phải sử dụng dữ liệu này thông qua POST này.

Phản hồi

Nếu yêu cầu thành công, máy chủ sẽ phản hồi bằng mã trạng thái 204 No Content.

Tham số truy vấn tùy chọn

Bạn có thể sử dụng các tham số truy vấn chuẩn khi xóa tất cả các ổ đĩa khỏi một trong những giá sách của người dùng đã xác thực.

Tham chiếu tham số truy vấn

Các tham số truy vấn mà bạn có thể sử dụng với API Sách được tóm tắt trong phần này.Tất cả các giá trị thông số cần được mã hóa URL.

Tham số truy vấn chuẩn

Bạn có thể ghi lại các tham số truy vấn áp dụng cho mọi thao tác API Sách tại Thông số hệ thống.

Tham số truy vấn dành riêng cho API

Bảng tóm tắt các tham số yêu cầu chỉ áp dụng cho một số thao tác cụ thể trong API sách.

Thông số Ý nghĩa Ghi chú Khả năng áp dụng
download Giới hạn số lượng theo tình trạng có sẵn để tải xuống.
  • Hiện tại, giá trị duy nhất được hỗ trợ là epub.
  • Bạn có thể cần phải mua quyền truy cập tệp tải xuống.
filter Lọc kết quả tìm kiếm theo loại số lượng và khả năng cung cấp.
  • Các bộ lọc được hỗ trợ là:
    • filter=partial – Hạn chế kết quả ở những nơi có thể xem trước ít nhất một phần văn bản.
    • filter=full – Hạn chế kết quả ở những nơi có thể xem toàn bộ văn bản.
    • filter=free-ebooks - Hạn chế kết quả đối với sách điện tử miễn phí trên Google.
    • filter=paid-ebooks - Hạn chế kết quả đối với sách điện tử trên Google bằng giá bán.
    • filter=ebooks - Hạn chế kết quả đối với sách điện tử trên Google, có tính phí hoặc miễn phí.Ví dụ về nội dung không phải sách điện tử sẽ là nội dung dành cho nhà xuất bản ở chế độ xem trước có giới hạn và không phải để bán hoặc tạp chí.

 

langRestrict Hạn chế số lượng được trả về cho những đĩa có gắn thẻ bằng ngôn ngữ đã chỉ định.
  • Hạn chế kết quả tìm kiếm trong kết quả tìm kiếm bằng những ngôn ngữ cụ thể bằng cách chỉ định langRestrict trong mã ISO-639-1 gồm hai chữ cái, chẳng hạn như "en" hoặc "fr"
maxResults Số lượng phần tử tối đa cần trả về theo yêu cầu này.
  • Đối với bất kỳ yêu cầu nào cho tất cả các mục trong một bộ sưu tập, bạn có thể phân trang kết quả bằng cách chỉ định startIndexmaxResults trong các thông số cho yêu cầu đó.
  • Mặc định: maxResults=10
  • Giá trị tối đa được phép: maxResults=40.
orderBy

Thứ tự của kết quả tìm kiếm theo số lượng.

  • Theo mặc định, yêu cầu tìm kiếm sẽ trả về kết quả maxResults, trong đó maxResults là thông số dùng trong quá trình phân trang, sắp xếp theo thứ tự phù hợp nhất trước.
  • Bạn có thể thay đổi thứ tự bằng cách đặt tham số orderBy thành một trong các giá trị sau:
    • orderBy=relevance – Trả về kết quả tìm kiếm theo thứ tự phù hợp nhất đến ít nhất (đây là mặc định).
    • orderBy=newest – Trả về kết quả tìm kiếm theo thứ tự của ngày xuất bản gần nhất cho ngày cũ nhất.
printType Chỉ áp dụng cho sách hoặc tạp chí.
  • Các giá trị được hỗ trợ là:
    • printType=all – Trả về tất cả các loại nội dung tập (không bị hạn chế). Đây là tuỳ chọn mặc định.
    • printType=books – Chỉ trả lại sách.
    • printType=magazines – Chỉ trả về tạp chí.
projection Hạn chế thông tin về số lượng được trả về một nhóm nhỏ các trường.
  • Các phép chiếu được hỗ trợ là:
    • projection=full – Bao gồm tất cả siêu dữ liệu về âm lượng (mặc định).
    • projection=lite – Chỉ bao gồm chủ đề về âm lượng và siêu dữ liệu truy cập.
q Chuỗi truy vấn toàn văn bản.
  • Khi tạo cụm từ tìm kiếm, hãy liệt kê các cụm từ tìm kiếm được phân tách bằng dấu # và #39;, dưới dạng q=term1+term2_term3. (Ngoài ra, bạn có thể phân tách chúng bằng dấu cách, nhưng giống như tất cả giá trị tham số truy vấn khác, dấu cách phải được mã hóa URL.) API trả về tất cả mục khớp với tất cả cụm từ tìm kiếm (như sử dụng AND giữa các cụm từ). Giống như nội dung tìm kiếm trên web của Google, API tìm kiếm các từ đầy đủ (và các từ liên quan có cùng nguồn gốc), không phải các chuỗi con.
  • Để tìm kiếm đúng cụm từ đó, hãy đặt cụm từ đó trong dấu ngoặc kép: q="exact phrase".
  • Để loại trừ các mục nhập khớp với một cụm từ nhất định, hãy sử dụng biểu mẫu q=-term.
  • Cụm từ tìm kiếm không phân biệt chữ hoa chữ thường.
  • Ví dụ: để tìm kiếm tất cả các mục có chứa cụm từ chính xác "Elizabeth Bennet" và từ "Darcy" nhưng không chứa từ "Austen", hãy sử dụng giá trị tham số truy vấn sau:
    q="Elizabeth+Bennet"+Darcy-Austen
  • Có những từ khoá đặc biệt (phân biệt chữ hoa chữ thường) mà bạn có thể chỉ định trong cụm từ tìm kiếm để tìm kiếm trong một số trường cụ thể, chẳng hạn như:
    • intitle: Trả về kết quả mà văn bản theo sau từ khóa này được tìm thấy trong tiêu đề.
    • inauthor: Trả về kết quả khi tìm thấy văn bản sau từ khoá này trong tác giả.
    • inpublisher: Trả về kết quả mà nhà xuất bản tìm thấy sau văn bản này.
    • subject: Trả về kết quả mà văn bản theo sau từ khóa này được liệt kê trong danh sách danh mục của tập.
    • isbn: Trả về kết quả mà văn bản sau từ khóa này là số ISBN.
    • lccn: Trả về kết quả mà văn bản sau từ khóa này là Số kiểm soát của Thư viện Quốc hội.
    • oclc: Trả về kết quả trong đó văn bản sau từ khóa này là số của Trung tâm thư viện máy tính trực tuyến.
startIndex Vị trí trong tập hợp để bắt đầu danh sách kết quả.
  • Đối với mọi yêu cầu cho tất cả các mục trong một bộ sưu tập, bạn có thể phân trang kết quả bằng cách chỉ định startIndexmaxResults trong các thông số cho yêu cầu đó.
  • Chỉ mục của mục đầu tiên là 0.
volumeId Xác định một khối lượng được liên kết với yêu cầu.
  • Chỉ định âm lượng để thêm hoặc xóa khỏi giá sách.