Tài liệu này giải thích cách bắt đầu sử dụng API Blogger.
Trước khi bắt đầu
Tạo tài khoản Google
Đảm bảo rằng 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ử, nhằm tự bảo vệ mình khỏi tình trạng mất dữ liệu ngoài ý muốn. Nếu đã có tài khoản kiểm thử thì bạn đã hoàn tất; bạn có thể truy cập 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ử của bạn.
Làm quen với Blogger
Nếu bạn chưa hiểu rõ các khái niệm của 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ác yêu cầu cấp phép và cách 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 đó 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 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 kèm theo một giá trị nhận dạng, chẳng hạn như một 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 Cho phép yêu cầu và xác định ứng dụng của bạn trong tài liệu Sử dụng API.
Nền API Blogger
Các khái niệm về Blogger
Blogger được xây dựng dựa trên năm khái niệm cơ bản:
- Blog: Khái niệm gốc của API. Mỗi blog có các bài đăng và trang. Đây là vùng chứa siêu thông tin của blog như tên blog và phần Nội dung mô tả.
- 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 nhằm kịp thời, phản ánh những nội dung mà tác giả muốn xuất bản ra thế giới lúc này. Chúng ta hiểu rằng khi thời gian trôi qua, nội dung trên blog sẽ cũ lại và ít liên quan 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 thể hiện cảm xúc về những gì tác giả đó viết. Mọi thứ từ gạch cho đến bó hoa.
- Trang: Trang là nơi dành cho nội dung tĩnh, chẳng hạn như thông tin tiểu sử hoặc cách thức liên hệ với người dùng. Đây thường là thông tin vượt thời gian và không thường xuyên thay đổi.
- Người dùng: Người dùng là người tương tác với Blogger, có thể là họ đóng vai trò là Tác giả, Quản trị viên hoặc chỉ là Người đọc. Đối với blog công khai, người đọc có thể ẩn danh, nhưng trên blog riêng tư, người đọc phải được Blogger xác định.
Mô hình dữ liệu API Blogger
Tài nguyên là một thực thể dữ liệu riêng lẻ có giá trị nhận dạng duy nhất. API JSON của Blogger 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: Đại diện cho một bài đăng; mỗi tài nguyên bài đăng là một phần tử con của một tài nguyên blog.
- Tài nguyên nhận xét: Biểu thị một nhận xét về một bài đăng cụ thể; mỗi tài nguyên nhận xét là một phần tử con của tài nguyên bài đăng.
- Tài nguyên trang: Đại diện cho một trang tĩnh; mỗi tài nguyên trang là một phần tử con của một 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 nhận xét.
Mô hình dữ liệu API Blogger 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 blog
- Một <span="apicollection">bộ sưu tậ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ê blog theo người dùng hoặc truy xuất một blog theo mã nhận dạng.</span="apicollection">
- Bộ sưu tập bài đăng
- Bộ sưu tậ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
- Một bộ sưu tậ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
- Một bộ sưu tập trang bao gồm mọi 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 nên không thể được 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ọ (chứ 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.
Hoạt động của API Blogger
Bạn có thể gọi một số phương thức đối với các bộ sưu tập và tài nguyên trong API Blogger, như mô tả trong bảng sau.
| Hoạt động | Nội dung mô tả | 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 URI của bộ sưu tập. |
| nhận | Lấy một tài nguyên cụ thể. | GET trên URI tài nguyên. |
| getByUrl | Lấy tài nguyên, tra cứu theo URL. | GET với URL được truyền vào dưới dạng tham số. |
| getByPath | Lấy tài nguyên bằng cách tra cứu tài nguyên đó theo đường dẫ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 do Người dùng sở hữu. | GET trên một bộ sưu tập do người dùng sở hữu. |
| search | Tìm kiếm tài nguyên, dựa trên tham số truy vấn. | GET trên URL tìm kiếm, trong đó cụm từ tìm kiếm được truyền vào dưới dạng tham số. |
| chèn | Tạo tài nguyên trong bộ sưu tập. | POST trên URI của bộ sưu tập. |
| xóa | Xoá tài nguyên. | DELETE trên URI tài nguyên. |
| bản vá | Cập nhậ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. |
| cập nhật | Cập nhật tài nguyên. | PUT trên URI tài nguyên. |
Bảng dưới đây cho biết các phương thức được từng loại tài nguyên hỗ trợ. Tất cả các thao tác list (danh sách) và get (nhận) 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ợ |
|||||||||
|---|---|---|---|---|---|---|---|---|---|---|
| danh sách | nhận | getByUrl | getByPath | listByUser | tìm kiếm | chèn | xoá | bản vá | cập nhật | |
| Blog | no | có | có | no | có | no | no | no | no | no |
| Bài đăng | có | có | no | có | no | có | có | có | có | có |
| Bình luận | có | có | no | no | no | no | no | no | no | no |
| Trang | có | có | no | no | no | no | no | no | no | no |
| Số người dùng | no | có | no | no | no | no | no | no | no | no |
Kiểu gọi
Có một số cách để gọi API:
- Sử dụng REST trực tiếp hoặc qua JavaScript (không cần mã phía máy chủ)
- Dùng thư viện ứng dụng.
Kiến trúc chuyển trạng thái đại diện (REST)
REST là một kiểu kiến trúc phần mềm mang lại cách tiếp cận thuận tiện và nhất quán để yêu cầu và sửa đổi dữ liệu.
Thuật ngữ REST là viết tắt của "Đại diện chuyển trạng thái". Trong ngữ cảnh của API Google, nó đề cập đến việc sử dụng các động từ HTTP để truy xuất và sửa đổi bản trình bày dữ liệu do Google lưu trữ.
Trong hệ thống RESTful, các tài nguyên được lưu trữ trong kho dữ liệu; máy khách gửi yêu cầu 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), còn máy chủ thực hiện thao tác và gửi phản hồi, thường ở dạng biểu diễn tài nguyên đã chỉ định.
Trong API RESTful của Google, ứng dụng chỉ định một hành động bằng cách sử dụng động từ HTTP như POST, GET, PUT hoặc DELETE. Phương thức này chỉ định tài nguyên bằng một URI duy nhất trên toàn hệ thống có dạng sau:
https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters
Vì mọi tài nguyên API đều có URI riêng biệt có thể truy cập HTTP, nên REST cho phép lưu 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 phối của web.
Bạn có thể thấy đị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ì các định nghĩa này bao gồm nội dung kỹ thuật cho GET, POST, PUT và DELETE.
REST trong API Blogger
Các thao tác được hỗ trợ của Blogger sẽ liên kết trực tiếp đến các động từ HTTP REST, như mô tả trong Thao tác của API Blogger.
Đị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
Nội dung giải thích đầy đủ về các URI được sử dụng và kết quả cho từng thao tác được hỗ trợ trong API được tóm tắt trong tài liệu Tài liệu tham khảo về API của Blogger.
Ví dụ
Liệt kê các 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
Xem các bài đăng trên blog code.blogger.com có mã blog là 3213900:
GET https://www.googleapis.com/blogger/v3/blogs/3213900?key=YOUR-API-KEY
Kiến trúc chuyển trạng thái đại diện (REST) từ JavaScript
Bạn có thể gọi API Blogger qua JavaScript bằng cách dùng tham số truy vấn callback và cung cấp một hàm callback.
Khi trình duyệt tải tập lệnh, hàm callback được thực thi và phản hồi sẽ được cung cấp cho hàm callback. Phương pháp này cho phép bạn viết các ứng dụng đa dạng thức 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.
<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, không phụ thuộc vào ngôn ngữ, cung cấp bản trình bày văn bản đơn giản của các cấu trúc dữ liệu tùy ý. Để biết thêm thông tin, hãy xem json.org.