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:
- 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.
- 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.)
- 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 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:
- Mở trang Thông tin xác thực trong Bảng điều khiển API.
-
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ườngidcủ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.
idcủ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.
Loại in
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 userId và giá 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 userId và giá 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. |
|
|
filter |
Lọc kết quả tìm kiếm theo loại số lượng và khả năng cung cấp. |
|
|
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. |
|
|
maxResults |
Số lượng phần tử tối đa cần trả về theo yêu cầu này. |
|
|
orderBy |
Thứ tự của kết quả tìm kiếm theo số lượng. |
|
|
printType |
Chỉ áp dụng cho sách hoặc 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. |
|
|
q |
Chuỗi truy vấn toàn văn bản. |
|
|
startIndex |
Vị trí trong tập hợp để bắt đầu danh sách kết quả. |
|
|
volumeId |
Xác định một khối lượng được liên kết với yêu cầu. |
|