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 các ứng dụng có thể tương tác với Books API (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. Books API (API Sách) là một cách để tìm kiếm và truy cập vào nội dung đó, cũng như để tạo và xem hoạt động cá nhân hoá xung quanh nội dung đó.
Nếu chưa hiểu rõ các khái niệm của Google Sách, bạn nên đọc phần Bắt đầu trước khi bắt đầu viết mã.
Uỷ quyền cho yêu cầu và nhận dạng ứng dụng của bạn
Mọi yêu cầu mà ứng dụng của bạn gửi tới Books API cần xác định ứ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 cho phép yêu cầu) và/hoặc sử dụng khoá API của ứng dụng. Dưới đây là cách xác định nên sử dụng tuỳ chọn nào trong số đó:
- Nếu yêu cầu cần được uỷ quyền (chẳng hạn như yêu cầu dữ liệu cá nhân của một cá nhân) thì ứng dụng phải cung cấp mã OAuth 2.0 cùng với yêu cầu đó. Ứng dụng cũng có thể cung cấp khoá API (không bắt buộc).
- Nếu yêu cầu đó không đòi hỏi việc uỷ quyền (chẳng hạn như yêu cầu đối với dữ liệu công khai) thì ứng dụng phải cung cấp khoá API hoặc mã OAuth 2.0, hoặc cả hai – tuỳ theo phương á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
Các yêu cầu gửi dữ liệu không công khai của người dùng tới API Books phải do 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:
- 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ư mã ứng dụng khách và mật khẩu ứng dụng khách.
- Kích hoạt Books API (API Sách) trong Google API Console. (Nếu API không được liệt kê trong API Console, thì hãy bỏ qua bước này.)
- 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ể.
- 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.
- 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.
- 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.
- 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 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ư mã ứng dụng khách và mật khẩu ứng dụng khách).
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.
Nhận và sử dụng khoá API
Các yêu cầu gửi dữ liệu công khai đến Books API phải đi kèm với giá trị nhận dạng, có thể là khoá API hoặc mã truy cập.
Cách lấy khoá API:
- Mở trang Thông tin đăng nhập trong Bảng điều khiển API.
-
API này hỗ trợ hai loại thông tin xác thực.
Tạo bất cứ thông tin đăng nhập nào phù hợp với dự án của bạn:
-
OAuth 2.0: Bất cứ khi nào ứng dụng của bạn 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 khách và có thể là mật khẩu ứng dụng khách để lấy mã thông báo. Bạn có thể tạo thông tin đăng nhập OAuth 2.0 cho các ứ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 giúp xác định dự án của bạn và cung cấp quyền truy cập, hạn mức và báo cáo API.
API này hỗ trợ một số loại quy định hạn chế đối với khoá API. Nếu khoá API mà 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 đăng nhập > Khoá API. Bạn có thể hạn chế khoá đó trước khi sử dụng trong phiên bản phát hành công khai bằng cách nhấp vào Restrict key (Hạn chế khoá) rồi chọn một trong các Hạn chế (Hạn chế).
-
Để giữ an toàn cho 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ó khoá API, ứng dụng của bạn có thể thêm tham số truy vấn key=yourAPIKey vào tất cả các URL yêu cầu.
Khoá API an toàn để nhúng trong URL và không cần sử dụng phương thức mã hoá nào.
Mã Google Sách
Bạn cần chỉ định trường mã nhận dạng bằng một số lệnh gọi phương thức API. Có 3 loại mã nhận dạng được sử dụng trong Google Sách:
- Mã tập sách – Các chuỗi duy nhất được cấp cho mỗi tập mà Google Sách biết. Ví dụ về mã nhận dạng ổ đĩa là
_LettPDhwR0C. Bạn có thể dùng API để lấy mã ổ đĩa bằng cách đưa ra yêu cầu trả về tài nguyên ổ đĩa. Bạn có thể tìm thấy mã ổ đĩa trong trườngidcủa ổ đĩa đó. - Mã nhận dạng giá sách – Giá trị dạng số được cung cấp cho 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 với các mã sau:
- Mục yêu thích: 0
- Đã mua: 1
- Cần đọc: 2
- Đang đọc: 3
- Đã đọc: 4
- Đã đánh giá: 5
- Mới 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.
id. - Mã nhận dạng người dùng – Các giá trị số duy nhất được gán cho mỗi người dùng. Các giá trị này không nhất thiết phải giống với giá trị mã 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ừ bản thân Liên kết trong tài nguyên Giá sách được truy xuất bằng một yêu cầu đã xác thực. Người dùng cũng có thể lấy mã nhận dạng người dùng riêng trên trang web Sách. Một người dùng không thể lấy mã nhận dạng người dùng cho một người dùng khác thông qua API hoặc trang web Sách; người dùng còn lại sẽ phải chia sẻ thông tin đó một cách rõ ràng, chẳng hạn như qua email.
Mã nhận dạng trên trang web Google Sách
Mã nhận dạng mà bạn sử dụng với Books API (API Sách) cũng chính là mã nhận dạng bạn dùng trên trang web Google Sách.
- Mã tập
Khi xem một tập cụ thể trên trang web, bạn có thể tìm thấy mã tập đó trong tham số URL
id. Dưới đây là một 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ể thấy mã giá sách trong tham số URL
as_coll. Dưới đây là một 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 người dùng
Khi xem thư viện của mình 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. Dưới đây là một 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 hạn chế pháp lý khác 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 vào nội dung sách ở một số quốc gia. Ví dụ: một số cuốn sách chỉ "có thể xem trước" ở Hoa Kỳ; chúng tôi sẽ bỏ qua các đường liên kết xem trước như vậy đối với 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.
Xử lý số lượng
Thực hiện tìm kiếm
Bạn có thể tìm kiếm tập 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 kiếm các tập có chứa chuỗi văn bản này. Bạn có thể chỉ định một số từ khoá đặc biệt trong cụm từ tìm kiếm để tìm kiếm trong các trường cụ thể, chẳng hạn như:intitle:Trả về kết quả mà có văn bản theo sau từ khoá này trong tiêu đề.inauthor:Trả về kết quả có văn bản theo sau từ khoá này thuộc về tác giả.inpublisher:Trả về kết quả khi tìm thấy văn bản theo sau từ khoá này trong nhà xuất bản.subject:Trả về kết quả mà 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 đứng sau từ khoá này là số ISBN.lccn:Trả về các 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 Hoa Kỳ.oclc:Trả về kết quả mà văn bản theo 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
Dưới đây là ví dụ về cách tìm kiếm "Hoa cho Algernon" của Daniel Keyes:
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 với yêu cầu GET. Tuy nhiên, nếu lệnh gọi được thực hiện bằng phương thức 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ả về ổ đĩa:
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 không bắt buộc
Ngoài tham số truy vấn chuẩn, bạn có thể sử dụng các tham số truy vấn sau đây khi thực hiện tìm kiếm tập sách.
Định dạng tải xuống
Bạn sử dụng tham số download để giới hạn kết quả được trả về cho các tập có
định dạng tải xuống hiện có là epub bằng cách đặt thành giá trị
epub.
Ví dụ sau đây về việc tìm những cuốn sách có thể tải xuống ở định dạ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 tham số filter để hạn chế hơn nữa kết quả trả về bằng cách đặt tham số này thành một trong các giá trị sau:
partial– Trả về kết quả trong đó ít nhất các phần của văn bản có thể xem trước.full– Chỉ trả về kết quả khi tất cả văn bản đều có thể xem được.free-ebooks– Chỉ trả về những kết quả là sách điện tử miễn phí trên Google.paid-ebooks– Chỉ trả về những kết quả là các sách điện tử trên Google kèm theo mức giá.ebooks– Chỉ trả về những kết quả là Sách điện tử trên Google, có tính phí hoặc miễn phí. Ví dụ về những nội dung không phải Sách điện tử là nội dung của nhà xuất bản được cung cấp ở dạng bản xem trước có giới hạn và không để bán, hoặc tạp chí.
Ví dụ sau đây giới hạn kết quả tìm kiếm ở những 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 các tham số cho yêu cầu:
startIndex– Vị trí trong tập hợp mà tại đó 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 được phép là 40.
Loại ảnh in
Bạn có thể dùng tham số printType để hạn chế kết quả được trả về ở một loại bản in hoặc ấn phẩm cụ thể bằng cách đặt tham số đó 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 đây giới hạn kết quả tìm kiếm đối với tạp chí:
GET https://www.googleapis.com/books/v1/volumes?q=time&printType=magazines&key=yourAPIKey
Dự kiến
Bạn có thể sử dụng tham 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 cần trả về:
full– Trả về tất cả trường Tập.lite– Chỉ trả về một số trường nhất định. Hãy xem nội dung mô tả các trường được đánh dấu bằng dấu hoa thị kép trong phần Tài liệu tham khảo về thể tích để 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 kèm theo 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 số lượng lớn sẽ trả về kết quả maxResults, trong đó maxResults là thông số được dùng để phân trang (ở trên), được sắp xếp theo mức độ liên quan với 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à mặc định).newest– Trả về kết quả theo thứ tự xuất bản gần đây nhất đến ít nhất xuất bản gần đây nhất.
Ví dụ sau đây liệt kê các kết quả theo ngày xuất bản, từ mới nhất đến cũ nhất:
GET https://www.googleapis.com/books/v1/volumes?q=flowers&orderBy=newest&key=yourAPIKey
Truy xuất một âm lượng cụ thể
Bạn có thể truy xuất thông tin về 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 Âm lượng:
https://www.googleapis.com/books/v1/volumes/volumeId
Thay thế tham số đường dẫn volumeId bằng mã nhận dạng của ổ đĩa cần truy xuất. Hãy xem phần Mã nhận dạng sách trên 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 được một ổ đĩa duy nhất:
GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?key=yourAPIKey
Lưu ý: Việc truy xuất thông tin về ổ đĩa 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 với 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, thì Tập 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 Tập đượ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 truy cập
Phần accessInfo được đặc biệt quan tâm đến việc xác định những tính năng nào có sẵn cho sách điện tử. epub là sách điện tử có định dạng văn bản tự xuống dòng, phần epub sẽ có thuộc tính isAvailable cho biết liệu có loại sách điện tử này hay không.
Ứng dụng sẽ có đường liên kết tải xuống nếu có sách mẫu hoặc người dùng
có thể đọc sách do đã mua hoặc do sách thuộc phạm vi công cộng
tại vị trí của người dùng. pdf dành cho Google Sách cho biết phiên bản trang được quét của sách điện tử có các thông tin chi tiết tương tự như sách có sẵn hay không và đường liên kết tải xuống. Bạn nên dùng các tệp epub cho thiết bị đọ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 những thiết bị này.
Nếu không có phần accessInfo thì cuốn sách đó sẽ không được cung cấp dưới dạng sách điện tử trên Google.
Tham số truy vấn không bắt buộc
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 một ổ đĩa cụ thể.
Dự kiến
Bạn có thể sử dụng tham 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 cần trả về:
full– Trả về tất cả trường Tập.lite– Chỉ trả về một số trường nhất định. Hãy xem nội dung mô tả các trường được đánh dấu bằng dấu hoa thị kép trong phần Tài liệu tham khảo về thể tích để tìm hiểu xem những trường nào được đưa vào.
Ví dụ sau đây trả về thông tin về ổ đĩa bị giới hạn cho một ổ đĩa:
GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?projection=lite&key=yourAPIKey
Xử lý giá sách
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 ID của người dùng có giá sách bạn muốn truy xuất. Hãy xem phần Mã nhận dạng trên Google Sách để biết thêm thông tin về mã nhận dạng người dù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 cần phải được 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 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 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 không bắt buộc
Bạn có thể sử dụng 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 mộ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 theo định dạng sau:
https://www.googleapis.com/books/v1/users/userId/bookshelves/shelf
Thay thế thông số đường dẫn userId và kệ bằng 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 phần Mã nhận dạng trên 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 cần phải được 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 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à 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 không bắt buộc
Bạn có thể sử dụng tham số truy vấn chuẩn khi truy xuất một giá sách công khai cụ thể.
Truy xuất danh sách các tập trên giá sách công cộng
Bạn có thể truy xuất danh sách các tập trên giá sách công khai của người dùng bằng cách gửi HTTP GET yêu cầu 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ế thông số đường dẫn userId và kệ bằng 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 phần Mã nhận dạng trên Google Sách để biết thêm thông tin.
Vì người dùng không cần phải được 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 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 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 không bắt buộc
Ngoài 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 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 các tham số cho yêu cầu:
startIndex– Vị trí trong tập hợp mà tại đó 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 được 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ả yêu cầu "Thư viện của tôi" đều áp dụng cho dữ liệu của người dùng đã xác thực.
Truy xuất danh sách giá sách của tôi
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 giá sách "Thư viện của tôi". Vì vậy, bạn phải cung cấp tiêu đề HTTP Authorization cùng 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 đã xác thực hiện tại:
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 không bắt buộc
Bạn có thể sử dụng 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 có trên giá sách của tôi
Bạn có thể truy xuất danh sách các tập 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ế tham số đường dẫn shelf (giá sách) bằng mã nhận dạng của giá sách. Hãy xem phần Mã nhận dạng giá sách trên 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 các ổ đĩa "Thư viện của tôi". Vì vậy, bạn phải cung cấp tiêu đề HTTP Authorization cùng 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 số lượng giá 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 không bắt buộc
Ngoài 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 một trong các 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 các tham số cho yêu cầu:
startIndex– Vị trí trong tập hợp mà tại đó 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.
Thêm một tập vào giá sách của tôi
Để thêm một tập 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 đến URI có định dạng sau:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/addVolume
Thay thế tham số đường dẫn shelf (giá sách) bằng mã nhận dạng của giá sách. Hãy xem phần Mã nhận dạng giá sách trên 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 duy nhất:
volumeId– Mã nhận dạng của ổ đĩa. Hãy xem phần Mã nhận dạng sách trên 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ề cách thêm "Hoa cho Algernon" vào giá sách "Yêu thí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 để sửa đổi giá sách. Vì vậy, bạn phải cung cấp tiêu đề HTTP Authorization với yêu cầu POST. Tuy nhiên, bạn không cần cung cấp dữ liệu với 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 không bắt buộc
Bạn có thể sử dụng tham số truy vấn chuẩn khi thêm tập vào một trong các giá sách của người dùng đã xác thực.
Xóa một tập khỏi giá sách của tôi
Để xoá một tập khỏi giá sách của người dùng đã xác thực, hãy gửi HTTP POST đến URI có định dạng sau:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/removeVolume
Thay thế tham số đường dẫn shelf (giá sách) bằng mã nhận dạng của giá sách. Hãy xem phần Mã nhận dạng giá sách trên 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 duy nhất:
volumeId– Mã nhận dạng của ổ đĩa. Hãy xem phần Mã nhận dạng của Google Sách để biết thêm thông tin về mã tập sách.
Yêu cầu
Dưới đây là ví dụ về cách xoá "Hoa cho Algernon" khỏi giá sách "Mục yêu thích":
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 để sửa đổi giá sách. Vì vậy, bạn phải cung cấp tiêu đề HTTP Authorization với yêu cầu POST. Tuy nhiên, bạn không cần cung cấp dữ liệu với 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 không bắt buộc
Bạn có thể sử dụng tham số truy vấn chuẩn khi xoá một tập khỏi một trong các giá sách của người dùng đã xác thực.
Xoá tất cả các tập khỏi giá sách của tôi
Để xoá tất cả các tập khỏi giá sách của người dùng đã xác thực, hãy gửi HTTP POST đến URI có định dạng sau:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/clearVolumes
Thay thế tham số đường dẫn shelf (giá sách) bằng mã nhận dạng của giá sách. Hãy xem phần Mã nhận dạng giá sách trên 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ụ về cách xoá giá sách "Yêu thí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 để sửa đổi giá sách. Vì vậy, bạn phải cung cấp tiêu đề HTTP Authorization với yêu cầu POST. Tuy nhiên, bạn không cần cung cấp dữ liệu với 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 không bắt buộc
Bạn có thể sử dụng tham số truy vấn chuẩn khi xoá tất cả các tập khỏi một trong các giá sách của người dùng đã xác thực.
Tài liệu tham khảo về tham số truy vấn
Phần này tóm tắt các tham số truy vấn mà bạn có thể sử dụng với Books API (API Sách).Tất cả giá trị thông số cần phải được mã hoá URL.
Tham số truy vấn chuẩn
Tham số truy vấn áp dụng cho tất cả hoạt động của API Books được ghi lại tại phần Tham số hệ thống.
Tham số truy vấn theo API cụ thể
Các tham số yêu cầu chỉ áp dụng cho các thao tác cụ thể trong Books API được tóm tắt trong bảng sau.
| Thông số | Ý nghĩa | Ghi chú | Khả năng áp dụng |
|---|---|---|---|
download |
Giới hạn số lượng theo khả năng tải xuống. |
|
|
filter |
Lọc kết quả tìm kiếm theo loại tập và phạm vi cung cấp. |
|
|
langRestrict |
Giới hạn các tập được trả về ở những tập được gắn thẻ bằng ngôn ngữ đã chỉ định. |
|
|
maxResults |
Số lượng phần tử tối đa cần trả về với yêu cầu này. |
|
|
orderBy |
Thứ tự của kết quả tìm kiếm số lượng. |
|
|
printType |
Hạn chế đối với sách hoặc tạp chí. |
|
|
projection |
Hạn chế thông tin về khối lượng được trả về cho một nhóm nhỏ các trường. |
|
|
q |
Chuỗi truy vấn dạng văn bản đầy đủ. |
|
|
startIndex |
Vị trí trong tập hợp mà từ đó bắt đầu danh sách kết quả. |
|
|
volumeId |
Xác định một khối lượng liên kết với yêu cầu. |
|