Bắt đầu

Tài liệu này trình bày chi tiết kiến thức cơ bản mà bạn cần có để sử dụng Google Books API.

Giới thiệu
Trước khi bạn bắt đầu
Thông tin cơ bản về Books API
Kiểu gọi
1. REST
Định dạng dữ liệu
1. JSON

Giới thiệu

Tài liệu này dành cho những nhà phát triển muốn viết các ứng dụng có thể tương tác với API Google Sách. Google Sách có mục tiêu số hoá sách trên toàn thế giới. Bạn có thể sử dụng Google Books API để tìm kiếm nội dung, sắp xếp thư viện cá nhân của người dùng đã xác thực và sửa đổi thư viện đó.

Trước khi bắt đầu

Tạo Tài khoản Google

Bạn cần có một Tài khoản Google cho mục đích kiểm thử. Nếu đã có tài khoản kiểm thử, thì bạn đã hoàn tất việc thiết lập. Bạn có thể truy cập vào giao diện người dùng Google Sách để thiết lập, chỉnh sửa hoặc xem dữ liệu kiểm thử.

Làm quen với Sách

Nếu chưa quen với các khái niệm về Google Sách, bạn nên đọc tài liệu này và thử nghiệm với giao diện người dùng trước khi bắt đầu viết mã. Tài liệu này giả định rằng bạn đã quen thuộc với các khái niệm lập trình web và định dạng dữ liệu web.

Tìm hiểu về cách uỷ quyền cho các yêu cầu và xác định ứng dụng của bạn

Khi ứng dụng của bạn yêu cầu dữ liệu riêng tư, yêu cầu này phải được một người dùng đã xác thực có quyền truy cập vào dữ liệu đó cấp phép.

Cụ thể, tất cả các thao tác trong phần "Thư viện của tôi" trong Google Books API đều được coi là riêng tư và yêu cầu xác thực cũng như uỷ quyền. Ngoài ra, chỉ người dùng sở hữu dữ liệu đó mới có thể thực hiện mọi thao tác sửa đổi dữ liệu trên Google Sách.

Khi ứng dụng của bạn yêu cầu dữ liệu công khai, yêu cầu này không cần được cấp phép, nhưng cần phải đi kèm với một giá trị nhận dạng, chẳng hạn như khoá API.

Để biết thông tin về cách uỷ quyền cho các yêu cầu và sử dụng khoá API, hãy xem phần Uỷ quyền cho các yêu cầu và xác định ứng dụng của bạn trong tài liệu Sử dụng API.

Thông tin cơ bản về Books API

Các khái niệm về sách

Google Sách được xây dựng dựa trên 4 khái niệm cơ bản:

Tập: Tập đại diện cho dữ liệu mà Google Sách lưu trữ về một cuốn sách hoặc tạp chí. Đây là tài nguyên chính trong Books API. Tất cả các tài nguyên khác trong API này đều chứa hoặc chú thích một tập.
Giá sách: Giá sách là một bộ sưu tập các tập. Google Sách cung cấp một bộ kệ sách được xác định trước cho mỗi người dùng, trong đó có một số kệ sách do người dùng quản lý hoàn toàn, một số kệ sách được tự động điền dựa trên hoạt động của người dùng và một số kệ sách là hỗn hợp. Người dùng có thể tạo, sửa đổi hoặc xoá các giá sách khác. Các giá sách này luôn được điền sách theo cách thủ công. Người dùng có thể đặt giá sách ở chế độ riêng tư hoặc công khai.
Lưu ý: Hiện tại, bạn chỉ có thể tạo và xoá giá sách cũng như sửa đổi chế độ cài đặt quyền riêng tư trên giá sách thông qua trang web Google Sách.
Bài đánh giá: Bài đánh giá về một tập là sự kết hợp giữa điểm xếp hạng theo sao và/hoặc văn bản. Mỗi người dùng chỉ có thể gửi một bài đánh giá cho mỗi tập. Bài đánh giá cũng có thể đến từ các nguồn bên ngoài và được ghi nhận một cách thích hợp.
Vị trí đọc: Vị trí đọc cho biết vị trí đọc lần cuối của người dùng trong một tập. Mỗi người dùng chỉ có thể có một vị trí đọc cho mỗi tập. Nếu người dùng chưa mở tập đó trước đây, thì vị trí đọc sẽ không tồn tại. Vị trí đọc có thể lưu trữ thông tin chi tiết về vị trí xuống đến độ phân giải của một từ. Thông tin này luôn là thông tin riêng tư của người dùng.

Mô hình dữ liệu Books API

Tài nguyên là một thực thể dữ liệu riêng lẻ có giá trị nhận dạng riêng biệt. Books API hoạt động trên 2 loại tài nguyên, dựa trên các khái niệm được mô tả ở trên:

Tài nguyên âm lượng: Biểu thị một âm lượng.
Tài nguyên giá sách: Đại diện cho một giá sách duy nhất của một người dùng cụ thể.

Mô hình dữ liệu Books API dựa trên các nhóm tài nguyên, được gọi là bộ sưu tập:

Bộ sưu tập số lượng lớn: Bộ sưu tập tập là một bộ sưu tập gồm mọi tài nguyên tập do Google Sách quản lý. Do đó, bạn không thể liệt kê tất cả các tài nguyên về tập, nhưng bạn có thể liệt kê tất cả các tập phù hợp với một bộ cụm từ tìm kiếm.
Bộ sưu tập trên giá sách: Bộ sưu tập giá sách bao gồm tất cả tài nguyên giá sách do Google Sách quản lý. Bạn phải luôn tham chiếu đến giá sách trong bối cảnh thư viện của một người dùng cụ thể. Giá sách có thể chứa từ 0 cuốn sách trở lên.

Các thao tác của Books API

Bạn có thể gọi 5 phương thức khác nhau trên các bộ sưu tập và tài nguyên trong Books API, như mô tả trong bảng sau.

Hoạt động	Mô tả	Mối liên kết HTTP REST
list	Liệt kê một nhóm nhỏ tài nguyên được chỉ định trong một bộ sưu tập.	`GET` trên một URI bộ sưu tập.
chèn	Chèn một tài nguyên mới vào một bộ sưu tập (tạo một tài nguyên mới).	`POST` trên một URI tập hợp, trong đó bạn truyền dữ liệu cho một tài nguyên mới.
get	Nhận một tài nguyên cụ thể.	`GET` trên URI tài nguyên.
update	Cập nhật một tài nguyên cụ thể.	`PUT` trên URI tài nguyên, trong đó bạn truyền dữ liệu cho tài nguyên đã cập nhật.
xóa	Xoá một tài nguyên cụ thể.	`DELETE` trên URI tài nguyên, trong đó bạn truyền dữ liệu cho tài nguyên cần xoá.

Các thao tác được hỗ trợ cho nhiều loại tài nguyên được tóm tắt trong bảng dưới đây. Các thao tác áp dụng cho dữ liệu riêng tư của người dùng được gọi là thao tác "Thư viện của tôi" và tất cả các thao tác này đều yêu cầu xác thực.

Loại tài nguyên	Các thao tác được hỗ trợ
	list	insert	get	update	xoá
Tập	có*		có
Giá sách	có*	có, ĐÃ XÁC THỰC	có*	có, ĐÃ XÁC THỰC	có, ĐÃ XÁC THỰC
Vị trí đọc		có, ĐÃ XÁC THỰC	có, ĐÃ XÁC THỰC	có, ĐÃ XÁC THỰC	có, ĐÃ XÁC THỰC

*Cả phiên bản AUTHENTICATED và phiên bản chưa xác thực của các thao tác này đều có sẵn, trong đó các yêu cầu đã xác thực hoạt động trên dữ liệu riêng tư "Thư viện của tôi" của người dùng và các yêu cầu chưa xác thực chỉ hoạt động trên dữ liệu công khai.

Kiểu gọi

Có một số cách để gọi API:

Sử dụng trực tiếp REST
Sử dụng REST từ JavaScript (không cần mã phía máy chủ)

REST

REST là một kiểu kiến trúc phần mềm mang đến cho bạn phương pháp thuận tiện và nhất quán trong việc yêu cầu và sửa đổi dữ liệu.

Cụm từ REST là viết tắt của "Chuyển đổi trạng thái trình bày". Đối với bối cảnh là các API của Google, cụm từ này đề cập đến việc sử dụng các động từ HTTP để truy xuất và sửa đổi các dạng trình bày của dữ liệu do Google lưu trữ.

Trong hệ thống RESTful, tài nguyên được lưu trữ trong kho lưu trữ dữ liệu; khi ứng dụng gửi yêu cầu để máy chủ thực hiện một thao tác cụ thể (chẳng hạn như tạo, truy xuất, cập nhật hoặc xoá tài nguyên), sau đó máy chủ thực hiện thao tác đó và gửi phản hồi, thường ở dạng trình bày đối với tài nguyên đã chỉ định.

Trong API RESTful của Google, ứng dụng sẽ chỉ định một thao tác bằng cách sử dụng động từ HTTP như POST, GET, PUT hoặc DELETE. Thao tác này sẽ chỉ định tài nguyên theo URI duy nhất toàn hệ thống có dạng như sau:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

Vì tất cả tài nguyên API đều có các URI duy nhất có thể truy cập HTTP, nên REST cho phép lưu trữ dữ liệu vào bộ nhớ đệm và được tối ưu hoá để hoạt động với cơ sở hạ tầng phân tán của trang web.

Bạn sẽ tìm được định nghĩa về phương thức trong tài liệu về các tiêu chuẩn HTTP 1.1 hữu ích; vì trong các định nghĩa này có nội dung đặc tả cho GET, POST, PUT và DELETE.

REST trong Books API

Các thao tác được hỗ trợ của Books có liên hệ trực tiếp đến các động từ HTTP trong REST, như mô tả trong phần Các thao tác của Books API.

Các định dạng cụ thể cho URI Books API là:

https://www.googleapis.com/books/v1/{collectionName}/resourceID?parameters

trong đó resourceID là giá trị nhận dạng cho một tài nguyên tập hoặc giá sách và parameters là mọi tham số cần áp dụng cho truy vấn. Hãy xem Tài liệu tham khảo về tham số truy vấn để biết thông tin chi tiết.

Định dạng của các tiện ích đường dẫn resourceID cho phép bạn xác định tài nguyên mà bạn hiện đang thao tác, ví dụ:

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

Xin lưu ý rằng các thao tác có mylibrary trong URI chỉ áp dụng cho dữ liệu thư viện riêng tư của người dùng hiện đang được xác thực. Bạn có thể xem tóm tắt về toàn bộ URI được dùng cho từng thao tác được hỗ trợ trong API trong tài liệu Tài liệu tham khảo về Books API.

Sau đây là một vài ví dụ về cách hoạt động của tính năng này trong Books API.

Tìm kiếm thông tin về hoạt động chắp vá:

GET https://www.googleapis.com/books/v1/volumes?q=quilting

Nhận thông tin về tập s1gVAAAAYAAJ:

GET https://www.googleapis.com/books/v1/volumes/s1gVAAAAYAAJ

REST từ JavaScript

Bạn có thể gọi Books API bằng REST từ JavaScript (còn gọi là JSON-P), bằng cách sử dụng tham số truy vấn callback và một hàm gọi lại. Điều này cho phép bạn viết các ứng dụng đa dạng hiển thị dữ liệu Sách mà không cần viết mã phía máy chủ.

Lưu ý: Bạn có thể gọi các phương thức đã xác thực bằng cách truyền mã thông báo OAuth 2.0 bằng tham số access_token. Để lấy mã thông báo OAuth 2.0 để sử dụng với JavaScript, hãy làm theo hướng dẫn được mô tả trong phần OAuth 2.0 cho ứng dụng web phía máy khách. Trong thẻ "Quyền truy cập API" của Bảng điều khiển API, hãy nhớ thiết lập một Mã ứng dụng khách cho các ứng dụng web và sử dụng thông tin xác thực OAuth 2.0 đó khi lấy mã thông báo.

Ví dụ sau đây sử dụng phương pháp này để hiển thị kết quả tìm kiếm cho "harry potter":

<html>
  <head>
    <title>Books API Example</title>
  </head>
  <body>
    <div id="content"></div>
    <script>
      function handleResponse(response) {
      for (var i = 0; i < response.items.length; i++) {
        var item = response.items[i];
        // in production code, item.text should have the HTML entities escaped.
        document.getElementById("content").innerHTML += "<br>" + item.volumeInfo.title;
      }
    }
    </script>
    <script src="https://www.googleapis.com/books/v1/volumes?q=harry+potter&callback=handleResponse"></script>
  </body>
</html>

Định dạng dữ liệu

JSON

JSON (Ký hiệu đối tượng JavaScript) là một định dạng dữ liệu phổ biến, độc lập về ngôn ngữ, cung cấp nội dung trình bày văn bản đơn giản của các cấu trúc dữ liệu tuỳ ý. Để biết thêm thông tin, hãy xem json.org.

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