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 nội dung đó dễ tìm thấy hơn 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 nội dung được cá nhân hoá liên quan đến nội dung đó.
Nếu chưa nắm 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.
Uỷ quyền cho các yêu cầu và xác định ứ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 API Sách đều cần xác định ứng dụng của bạn với Google. Có hai 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 cấp quyền cho yêu cầu) và/hoặc sử dụng khoá API của ứng dụng. Sau đây là cách xác định tuỳ chọn nào nên dùng:
- Nếu yêu cầu cần được uỷ quyền (chẳng hạn như yêu cầu về dữ liệu riêng tư của một cá nhân), thì ứng dụng phải cung cấp mã thông báo OAuth 2.0 cùng với 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ỳ lựa 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 đến API Sách về dữ liệu người dùng không công khai phải được 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 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 truy cập 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.
Lấy và sử dụng khoá API
Yêu cầu gửi đến API Sách để lấy dữ liệu công khai phải đi kèm với một giá trị nhận dạng, có thể là khoá API hoặc mã thông báo truy cập.
Cách lấy khoá API:
- Mở trang Thông tin xác thực trong API Console.
-
API này hỗ trợ hai loại thông tin xác thực.
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 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 mã xác thực ứng dụng khách để 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: Một yêu cầu không cung cấp mã thông báo OAuth 2.0 phải gửi một khoá API. Khoá này xác định dự án của bạn và cung cấp quyền truy cập API, hạn mức và báo cáo.
API này hỗ trợ một số loại 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 xác thực > Khoá API. Bạn có thể hạn chế khoá trước khi sử dụng khoá đó trong phiên bản 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ó 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ả URL yêu cầu.
Khoá API an toàn để nhúng vào URL; không cần mã hoá.
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ã tập – 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 phương tiện là
_LettPDhwR0C. Bạn có thể sử dụng API để lấy mã nhận dạng phương tiện bằng cách đưa ra yêu cầu trả về tài nguyên Phương tiện; bạn có thể tìm thấy mã nhận dạng phương tiện trong trườngidcủa tài nguyên đó. - Mã giá sách – Giá trị dạng 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ố kệ được xác định trước cho mọi người dùng có các mã nhận dạng sau:
- Danh sách yêu thích: 0
- Số lượt mua: 1
- Để đọ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 sẽ 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 chỉ định 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ã nhận dạng đó từ selfLink trong tài nguyên Bookshelf đượ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 của riêng họ 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 của người dùng khác thông qua API hoặc trang web Sách; người dùng khác 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 API Sách cũng chính là mã nhận dạng được sử dụng trên trang web Google Sách.
- Mã nhận dạng phương tiện
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à 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 kệ sách cụ thể trên trang web, bạn có thể tìm thấy mã nhận dạng kệ sách trong tham số URL
as_coll. Dưới đâ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 người dùng
Khi xem thư việ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. Dưới đây là ví dụ:https://books.google.com/books?uid=11122233344455566778&source=gbs_lp_bookshelf_list
Thiết lập thông tin vị trí của người dùng
Google Sách tuân thủ bản quyền, hợp đồng và các quy định 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 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 đó 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.
Làm việc với các phương tiện
Tìm kiếm
Bạn có thể tìm kiếm theo phương tiện bằng cách gửi yêu cầu GET HTTP đến URI sau:
https://www.googleapis.com/books/v1/volumes?q=search+terms
Yêu cầu này có một tham số bắt buộc:
q– Tìm kiếm các tập chứa chuỗi văn bản này. Có một số từ khoá đặc biệt mà bạn có thể chỉ định 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ả có văn bản theo sau từ khoá này trong tiêu đề.inauthor:Trả về kết quả trong đó văn bản theo từ khoá này được tìm thấy trong tác giả.inpublisher:Trả về kết quả trong đó văn bản theo từ khoá này được tìm thấy trong nhà xuất bản.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ài liệu.isbn:Trả về kết quả trong đó văn bản theo sau từ khoá này là số ISBN.lccn:Trả về kết quả trong đó văn bản theo sau từ khoá này là Mã 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 theo sau từ khoá này là số Trung tâm thư viện máy tính trực tuyến (OCLC).
Yêu cầu
Dưới đây là ví dụ về cách tìm kiếm cuốn sách "Flowers for 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 cần 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 Dung 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ề dung 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 không bắt buộc
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 đây 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 tham số download để hạn chế kết quả trả về ở những phương tiện có định dạng tải xuống là epub bằng cách đặt thành giá trị epub.
Ví dụ sau đây tìm kiế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 thông số filter để hạn chế thêm kết quả 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ả mà ít nhất một phần văn bản có thể xem trước.full– Chỉ trả về kết quả có thể xem được toàn bộ văn bản.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ử trên Google có giá.ebooks– Chỉ trả về kết quả là 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ử: nội dung của nhà xuất bản có bản xem trước có giới hạn và không bán, hoặc tạp chí.
Ví dụ sau đây chỉ cho phép kết quả tìm kiếm là 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 các phương tiện 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 để bắt đầu. Chỉ mục của mục đầu tiên là 0.maxResults– Số 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 bản in
Bạn có thể sử dụng tham số printType để giới hạn kết quả trả về ở một loại ấn phẩm hoặc ấn bản cụ thể bằng cách đặt tham số này thành một trong các giá trị sau:
all– Không hạn chế theo loại bản 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 ở 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 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 Volume (Dung lượng) được xác định trước để trả về:
full– Trả về tất cả các trường Volume (Dung lượng).lite– Chỉ trả về một số trường nhất định. Xem nội dung mô tả trường được đánh dấu bằng dấu hoa thị đôi trong Tài liệu tham khảo về tập lệnh để tìm hiểu xem có những trường nào.
Ví dụ sau đây trả về kết quả tìm kiếm có thông tin về lượng tìm kiếm bị giới hạn:
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 theo khối lượng sẽ trả về kết quả maxResults, trong đó maxResults là tham số dùng trong tính năng 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ự mới nhất đến ít mới nhất được phát hành.
Ví dụ sau đây liệt kê 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 phương tiện cụ thể
Bạn có thể truy xuất thông tin cho một phương tiện bộ nhớ cụ thể bằng cách gửi yêu cầu GET HTTP đến URI tài nguyên Phương tiện bộ nhớ:
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 phương tiện cần truy xuất. Hãy xem phần Mã Google Sách để biết thêm thông tin về mã tập.
Yêu cầu
Sau đây là ví dụ về một yêu cầu GET nhận được một phương tiện:
GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?key=yourAPIKey
Lưu ý: Việc truy xuất thông tin về phương tiện không yêu cầu xác thực, vì vậy, bạn không cần 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 xác thực, thì Dung 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 Dung 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 trọng trong việc xác định những tính năng có sẵn cho sách điện tử. epub là sách điện tử ở định dạng văn bản tự ngắt dòng, mục 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.
Trang này sẽ có đường liên kết tải xuống nếu có bản minh hoạ cho cuốn sách hoặc nếu người dùng có thể đọc cuốn sách do đã mua hoặc do cuốn sách đó thuộc miền công khai ở vị trí của người dùng. pdf cho Google Sách cho biết phiên bản trang đã quét của sách điện tử có các thông tin chi tiết tương tự, chẳng hạn như liệu có phiên bản này hay không và đường liên kết tải xuống. Google đề xuất tệp epub cho máy đọc sách điện tử và điện thoại thông minh, vì các trang đã quét có thể khó đọc trên các thiết bị này.
Nếu không có phần accessInfo, thì bạn sẽ không thể tải cuốn sách đó xuống dưới dạng sách điện tử của 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 phương tiện cụ thể.
Dự đoá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 Volume (Dung lượng) được xác định trước để trả về:
full– Trả về tất cả các trường Volume (Dung lượng).lite– Chỉ trả về một số trường nhất định. Xem nội dung mô tả trường được đánh dấu bằng dấu hoa thị đôi trong Tài liệu tham khảo về tập lệnh để tìm hiểu xem có những trường nào.
Ví dụ sau đây trả về thông tin giới hạn về dung lượng cho một phương tiện:
GET https://www.googleapis.com/books/v1/volumes/zyTCAlFPjgYC?projection=lite&key=yourAPIKey
Làm việc với kệ sách
Truy xuất danh sách kệ sách công khai của người dùng
Bạn có thể truy xuất danh sách kệ sách công khai của người dùng bằng cách gửi yêu cầu GET HTTP đến URI theo định dạng sau:
https://www.googleapis.com/books/v1/users/userId/bookshelves
Thay thế tham số đường dẫn userId bằng mã nhận dạng của người dùng mà bạn muốn truy xuất kệ sách. Hãy xem phần Mã 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 về các kệ sách công khai, nên bạn không cầ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 kệ 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 các tham số truy vấn chuẩn khi truy xuất danh sách kệ sách công khai của người dùng.
Truy xuất một kệ sách công khai cụ thể
Bạn có thể truy xuất một kệ 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ế các tham số đường dẫn userId và shelf bằng các mã nhận dạng chỉ định người dùng và 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.
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 về các kệ sách công khai, nên bạn không cầ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à 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 các tham số truy vấn chuẩn khi truy xuất một kệ sách công khai cụ thể.
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 cuốn sách trên kệ sách công khai của người dùng bằng cách gửi yêu cầu HTTP GET đến một 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 userId và shelf bằng các mã nhận dạng chỉ định người dùng và 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ì người dùng không cần phải được xác thực để truy xuất thông tin về các kệ sách công khai, nên bạn không cầ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 kệ 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 các tham số truy vấn tiêu 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 cuốn sách trên giá sách công khai.
Phân trang
Bạn có thể phân trang danh sách các phương tiện 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 để bắt đầu. Chỉ mục của mục đầu tiên là 0.maxResults– Số 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 kệ sách trong phần "Thư viện của tôi"
Tất cả các yêu cầu về "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 kệ sách của tôi
Bạn có thể truy xuất danh sách tất cả các kệ sách của người dùng đã xác thực bằng cách gửi yêu cầu GET HTTP đến URI theo đị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 các kệ sách "Thư viện của tôi". 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ả kệ 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 các tham số truy vấn chuẩn khi truy xuất danh sách kệ sách của người dùng đã xác thực.
Truy xuất danh sách các cuốn sách trên kệ sách của tôi
Bạn có thể truy xuất danh sách các cuốn sách 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 GET HTTP đến URI theo định dạng sau:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/volumes
Thay thế tham số đường dẫn shelf bằng mã của giá sách. Hãy xem phần Mã Google Sách để biết thêm thông tin về mã kệ 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 cuốn sách trong "Thư viện của tôi". 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 các cuốn sách trên kệ 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 các tham số truy vấn tiêu 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 kệ 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 các phương tiện 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 để bắt đầu. Chỉ mục của mục đầu tiên là 0.maxResults– Số kết quả tối đa cần trả về. Giá trị mặc định là 10.
Thêm một cuốn sách vào kệ sách của tôi
Để thêm một cuốn sách vào giá sách của người dùng đã xác thực, hãy gửi yêu cầu POST HTTP đến URI theo định dạng sau:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/addVolume
Thay thế tham số đường dẫn shelf bằng mã nhận dạng của giá sách. Hãy xem phần Mã Google Sách để biết thêm thông tin về mã kệ sách.
Yêu cầu có một tham số truy vấn bắt buộc:
volumeId– Mã của phương tiện. Hãy xem phần 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ề cách thêm cuốn sách "Flowers for Algernon" vào giá sách "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 một kệ sách, vì vậy, bạn phải cung cấp tiêu đề HTTP Authorization cùng với yêu cầu POST. Tuy nhiên, bạn không cần dữ liệu nào 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 các thông số truy vấn chuẩn khi thêm một cuốn sách vào một trong các kệ sách của người dùng đã xác thực.
Xoá một cuốn sách khỏi kệ sách
Để xoá một cuốn sách khỏi giá sách của người dùng đã xác thực, hãy gửi một POST HTTP đến URI theo định dạng sau:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/removeVolume
Thay thế tham số đường dẫn shelf bằng mã của giá sách. Hãy xem phần Mã Google Sách để biết thêm thông tin về mã kệ sách.
Yêu cầu có một tham số truy vấn bắt buộc:
volumeId– Mã của phương tiện. Hãy xem phần 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ề cách xoá cuốn "Flowers for Algernon" khỏi giá sách "Favorites" (Sách 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 một kệ sách, vì vậy, bạn phải cung cấp tiêu đề HTTP Authorization cùng với yêu cầu POST. Tuy nhiên, bạn không cần dữ liệu nào 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 các tham số truy vấn chuẩn khi xoá một cuốn sách khỏi một trong các kệ sách của người dùng đã xác thực.
Xoá tất cả các cuốn sách khỏi kệ sách của tôi
Để xoá tất cả các cuốn sách khỏi giá sách của người dùng đã xác thực, hãy gửi một POST HTTP đến URI theo định dạng sau:
https://www.googleapis.com/books/v1/mylibrary/bookshelves/shelf/clearVolumes
Thay thế tham số đường dẫn shelf bằng mã của giá sách. Hãy xem phần Mã Google Sách để biết thêm thông tin về mã kệ sách.
Yêu cầu
Sau đây là ví dụ về cách xoá giá sách "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 một kệ sách, vì vậy, bạn phải cung cấp tiêu đề HTTP Authorization cùng với yêu cầu POST. Tuy nhiên, bạn không cần dữ liệu nào 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 các thông số truy vấn chuẩn khi xoá tất cả các cuốn sách khỏi một trong những kệ 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
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ả giá trị tham số đều phải được mã hoá URL.
Tham số truy vấn tiêu chuẩn
Các tham số truy vấn áp dụng cho tất cả thao tác API của Sách được ghi lại tại Tham số hệ thống.
Tham số truy vấn dành riêng cho API
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 được tóm tắt trong bảng sau.
| Thông số | Ý nghĩa | Ghi chú | Khả năng áp dụng |
|---|---|---|---|
download |
Hạn chế theo số lượng theo tình trạng có thể tải xuống. |
|
|
filter |
Lọc kết quả tìm kiếm theo loại sách và tình trạng còn hàng. |
|
|
langRestrict |
Hạn chế 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ề bằng yêu cầu này. |
|
|
orderBy |
Thứ tự của kết quả tìm kiếm theo lượng tìm kiếm. |
|
|
printType |
Chỉ cho phép sách hoặc tạp chí. |
|
|
projection |
Hạn chế thông tin về dung lượng được trả về cho một tập hợp con các trường. |
|
|
q |
Chuỗi truy vấn toàn văn. |
|
|
startIndex |
Vị trí trong tập hợp để bắt đầu danh sách kết quả. |
|
|
volumeId |
Xác định một phương tiện liên kết với yêu cầu. |
|