Tài liệu này giải thích cách bắt đầu sử dụng Blogger API.
Trước khi bắt đầu
Tạo Tài khoản Google
Đảm bảo bạn đã thiết lập Tài khoản Google. Bạn nên sử dụng một Tài khoản Google riêng cho mục đích phát triển và kiểm thử để tránh bị mất dữ liệu do nhầm lẫn. Nếu đã có tài khoản kiểm thử, thì bạn có thể bỏ qua bước này. Bạn có thể truy cập vào giao diện người dùng Blogger để thiết lập, chỉnh sửa hoặc xem dữ liệu kiểm thử.
Làm quen với Blogger
Nếu bạn chưa quen với các khái niệm về Blogger, hãy đọ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 Blogger, 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 đó uỷ quyền.
Khi ứng dụng của bạn yêu cầu dữ liệu công khai, yêu cầu đó không cần được uỷ quyền, 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ề Blogger API
Các khái niệm về Blogger
Blogger được xây dựng dựa trên 5 khái niệm cơ bản:
- Blog: Khái niệm cơ bản của API. Một blog có các bài đăng và trang. Đây là vùng chứa cho siêu thông tin của blog, chẳng hạn như tên và nội dung mô tả của blog.
- Bài đăng: Bài đăng trên blog là mục có thể xuất bản mà tác giả blog đã tạo. Thông tin này phải kịp thời, phản ánh những gì mà tác giả muốn xuất bản cho mọi người ngay bây giờ. Chúng tôi hiểu rằng theo thời gian, nội dung của bài đăng trên blog sẽ cũ đi và trở nên ít phù hợp hơn.
- Bình luận: Bình luận là nơi những người không phải là tác giả của bài đăng trên blog phản ứng với nội dung mà tác giả đã viết. Mọi thứ từ gạch đến bó hoa.
- Trang: Trang là nơi chứa nội dung tĩnh, chẳng hạn như thông tin tiểu sử hoặc cách liên hệ với người dùng. Đây thường là thông tin không có thời hạn và không thay đổi thường xuyên.
- Người dùng: Người dùng là người tương tác với Blogger, cho dù họ là Tác giả, Quản trị viên hay chỉ là Độc giả. Đối với blog công khai, người đọc có thể là người dùng ẩn danh, nhưng trên blog riêng tư, Blogger phải xác định được người đọc.
Mô hình dữ liệu Blogger 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. Blogger JSON API hoạt động trên 5 loại tài nguyên:
- Tài nguyên Blog: Biểu thị một blog.
- Tài nguyên bài đăng: Biểu thị một bài đăng; mỗi tài nguyên bài đăng là một phần tử con của tài nguyên blog.
- Tài nguyên Comments: Biểu thị một bình luận về một bài đăng cụ thể; mỗi tài nguyên comments là một phần tử con của tài nguyên posts.
- Tài nguyên Trang: Biểu thị một trang tĩnh; mỗi tài nguyên trang là một phần tử con của tài nguyên blog.
- Tài nguyên Người dùng: Biểu thị một người dùng không ẩn danh. Thuộc tính này dùng để xác định Tác giả của một trang, bài đăng hoặc bình luận.
Mô hình dữ liệu Blogger API dựa trên các nhóm tài nguyên, được gọi là tập hợp:
- Bộ sưu tập blog
- Một <span="apicollection">tập hợp blog bao gồm tất cả các blog mà người dùng có quyền truy cập. Bạn có thể liệt kê các blog theo người dùng hoặc truy xuất một blog duy nhất theo mã nhận dạng.</span="apicollection">
- Bộ sưu tập bài đăng
- Tập hợp bài đăng bao gồm tất cả tài nguyên bài đăng trong một tài nguyên blog cụ thể.
- Thu thập bình luận
- Tập hợp bình luận bao gồm tất cả tài nguyên bình luận trong một tài nguyên bài đăng cụ thể.
- Tập hợp trang
- Tập hợp trang bao gồm tất cả tài nguyên trang trong một tài nguyên blog cụ thể.
- Tập hợp người dùng
- Tập hợp người dùng bao gồm tất cả tài nguyên người dùng trên Blogger, do đó không thể liệt kê. Người dùng có thể truy xuất tài nguyên người dùng của riêng họ (nhưng không phải của người khác) theo mã nhận dạng hoặc bằng cách sử dụng giá trị nhận dạng
self.
Các thao tác của Blogger API
Bạn có thể gọi một số phương thức khác nhau trên các bộ sưu tập và tài nguyên trong Blogger 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ê tất cả tài nguyên trong một bộ sưu tập. | GET trên một URI bộ sưu tập. |
| get | Nhận một tài nguyên cụ thể. | GET trên URI tài nguyên. |
| getByUrl | Nhận một tài nguyên bằng cách tra cứu theo URL. | GET có URL được truyền vào dưới dạng tham số. |
| getByPath | Lấy một tài nguyên bằng cách tra cứu theo đường dẫn của tài nguyên đó. | GET với Đường dẫn được truyền vào dưới dạng tham số. |
| listByUser | Liệt kê các tài nguyên thuộc sở hữu của một Người dùng. | GET trên một bộ sưu tập thuộc sở hữu của người dùng. |
| search | Tìm kiếm tài nguyên dựa trên một tham số truy vấn. | GET trên URL tìm kiếm, với truy vấn được truyền vào dưới dạng một tham số. |
| chèn | Tạo tài nguyên trong một bộ sưu tập. | POST trên một URI bộ sưu tập. |
| xóa | Xoá một tài nguyên. | DELETE trên URI tài nguyên. |
| patch | Cập nhật một tài nguyên bằng cách sử dụng ngữ nghĩa của bản vá. | PATCH trên URI tài nguyên. |
| update | Cập nhật tài nguyên. | PUT trên URI tài nguyên. |
Bảng dưới đây cho biết từng loại tài nguyên hỗ trợ những phương thức nào. Tất cả các thao tác list và get trên blog riêng tư đều yêu cầu xác thực.
Loại tài nguyên |
Các phương thức được hỗ trợ |
|||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| list | get | getByUrl | getByPath | listByUser | search | insert | xoá | patch | update | |
| Blog | không | có | có | không | có | không | không | không | không | không |
| Bài đăng | có | có | không | có | không | có | có | có | có | có |
| Nhận xét | có | có | không | không | không | không | không | không | không | không |
| Trang | có | có | không | không | không | không | không | không | không | không |
| Số người dùng | không | có | không | không | không | không | không | không | không | không |
Kiểu gọi
Có một số cách để gọi API:
- Sử dụng REST trực tiếp hoặc từ JavaScript (không cần mã phía máy chủ)
- Sử dụng thư viện ứng dụng.
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 Blogger API
Các thao tác được hỗ trợ của Blogger 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 Blogger API.
Các định dạng cụ thể cho URI API của Blogger là:
https://www.googleapis.com/blogger/v3/users/userId https://www.googleapis.com/blogger/v3/users/self https://www.googleapis.com/blogger/v3/users/userId/blogs https://www.googleapis.com/blogger/v3/users/self/blogs https://www.googleapis.com/blogger/v3/blogs/blogId https://www.googleapis.com/blogger/v3/blogs/byurl https://www.googleapis.com/blogger/v3/blogs/blogId/posts https://www.googleapis.com/blogger/v3/blogs/blogId/posts/bypath https://www.googleapis.com/blogger/v3/blogs/blogId/posts/search https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId/comments https://www.googleapis.com/blogger/v3/blogs/blogId/posts/postId/comments/commentId https://www.googleapis.com/blogger/v3/blogs/blogId/pages https://www.googleapis.com/blogger/v3/blogs/blogId/pages/pageId
Bạn sẽ tìm được nội dung giải thích đầy đủ về các URI được dùng và kết quả của từng thao tác được hỗ trợ trong API trong tài liệu Tài liệu tham khảo về Blogger API.
Ví dụ
Liệt kê những blog mà người dùng đã xác thực có quyền truy cập:
GET https://www.googleapis.com/blogger/v3/users/self/blogs?key=YOUR-API-KEY
Nhận các bài đăng trên blog code.blogger.com có mã nhận dạng blog là 3213900:
GET https://www.googleapis.com/blogger/v3/blogs/3213900?key=YOUR-API-KEY
REST từ JavaScript
Bạn có thể gọi Blogger API từ JavaScript bằng cách sử dụng tham số truy vấn callback và cung cấp một hàm gọi lại.
Khi trình duyệt tải tập lệnh, hàm gọi lại sẽ được thực thi và phản hồi sẽ được cung cấp cho hàm gọi lại. Phương pháp này cho phép bạn viết các ứng dụng đa dạng hiển thị dữ liệu Blogger mà không cần mã phía máy chủ.
Ví dụ sau đây truy xuất một bài đăng từ blog code.blogger.com sau khi bạn thay thế YOUR-API-KEY bằng khoá API của mình.
<html>
<head>
<title>Blogger API Example</title>
</head>
<body>
<div id="content"></div>
<script>
function handleResponse(response) {
document.getElementById("content").innerHTML += "<h1>" + response.title + "</h1>" + response.content;
}
</script>
<script
src="https://www.googleapis.com/blogger/v3/blogs/3213900/posts/8398240586497962757?callback=handleResponse&key=YOUR-API-KEY"></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.