Tìm kiếm, lượt xem và «Đọc nhiều»

Tìm kiếm

GET /v2/public/cms/{siteSlug}/entries?locale=vi&q=bon%20mang&page=1&limit=12

Tìm trong tiêu đề, tóm tắt và thân bài (phần chữ, không tính tên thẻ HTML) của bản dịch ở đúng locale.
Không phân biệt dấu và hoa thường: bon mang tìm ra «Bổn mạng».
Khớp một chuỗi con liền mạch, không tách từ: mang bon không tìm ra «Bổn mạng». Các ký tự % và _ được hiểu đúng nghĩa đen.
Chỉ tìm bài viết đã xuất bản, không tìm trang tĩnh. Bài của loại nội dung «không liệt kê» không có trong kết quả.
Kết quả xếp mới nhất trước; bỏ qua bài nổi bật (featured luôn false).
q dài 2–100 ký tự sau khi cắt khoảng trắng hai đầu; ngoài khoảng đó nhận 400 với message: "CMS_SEARCH_QUERY_INVALID".
Không kết hợp q với category, tag hay sort (400 CMS_FILTER_CONFLICT).

Hãy chuẩn hóa từ khóa trước khi gọi, để không tốn một yêu cầu bị từ chối và để mọi người đọc cùng từ khóa dùng chung một bản trong bộ đệm:

function searchTerm(raw: string): string | null {
  const term = raw.trim()
  return term.length >= 2 && term.length <= 100 ? term : null
}

Kết quả tìm kiếm được giữ trong bộ đệm tối đa 60 giây và không được làm mới ngay khi nhân sự sửa bài.

Lượt xem

POST /v2/public/cms/{siteSlug}/entries/{entrySlug}/view

Gửi một lần mỗi khi người đọc mở một bài viết hoặc trang. Lượt xem dùng cho thống kê của nhân sự và cho khối «Đọc nhiều».

Cách gọi đúng, từ trình duyệt của người đọc:

function sendView(entrySlug: string): void {
  if (typeof window === 'undefined') return // never during server rendering or a static build
  try {
    fetch(`${API}/entries/${encodeURIComponent(entrySlug)}/view`, {
      method: 'POST',
      keepalive: true,
      credentials: 'omit',
    }).catch(() => undefined)
  } catch {
    // ignore: a lost view must never break the page
  }
}

Quy tắc:

Không thân yêu cầu, không header (kể cả Content-Type). Như vậy đây là một «simple request» của CORS, trình duyệt không phải gửi thêm yêu cầu OPTIONS.
Luôn nhận 204, không có nội dung, kể cả khi lượt đó không được đếm. Đừng đọc phản hồi và đừng báo lỗi cho người đọc.
Chỉ gửi từ trình duyệt. Gửi từ máy chủ hay lúc dựng trang tĩnh sẽ làm mọi lượt xem trông như cùng một người đọc, nên hầu như không được đếm.
Không gửi thêm gì về người đọc: API không nhận và không cần thông tin cá nhân.

Máy chủ không đếm khi:

cùng một người đọc đã được đếm cho entry đó trong 30 phút gần nhất (nhận diện bằng một mã băm một chiều của địa chỉ IP và User-Agent; mã này chỉ dùng để chống đếm trùng, không được ghi lại hay lưu vào cơ sở dữ liệu);
User-Agent trông như máy (chứa bot, crawl, spider, preview hoặc slurp);
entry không tồn tại, chưa xuất bản, hoặc slug sai dạng.

Lượt xem hiện ra cho nhân sự và trong «Đọc nhiều» sau khoảng 30 giây. Slug cũ (đã đổi) vẫn được đếm cho entry hiện tại.

Giới hạn tần suất của đường dẫn này chặt hơn các đường đọc: xem Giới hạn.

«Đọc nhiều»

GET /v2/public/cms/{siteSlug}/entries?locale=vi&sort=popular&page=1&limit=6

Các bài viết có nhiều lượt xem nhất trong 30 ngày gần nhất (tính theo ngày UTC); bằng nhau thì bài mới hơn đứng trước.
Chỉ gồm bài đã được xem ít nhất một lần trong khoảng đó, nên danh sách có thể ngắn hơn limit, kể cả rỗng với một trang web mới. Hãy ẩn khối này khi data rỗng.
Chỉ page=1, và limit là 3, 6 hoặc 12; khác đi nhận 400 với message: "CMS_POPULAR_QUERY_INVALID".
Không kết hợp với category, tag hay q.
meta.total bằng số mục thực trả về.
Bài của loại nội dung «không liệt kê» không có trong danh sách.

Tìm kiếm​

Lượt xem​

«Đọc nhiều»​

Tìm kiếm

Lượt xem

«Đọc nhiều»