Sử dụng API hiệu quả: bộ nhớ đệm, webhook và giới hạn tốc độ

Premium

Tối ưu các lệnh gọi API Omniscol: dùng ETag để tránh tải lại dữ liệu không đổi, lưu phản hồi vào bộ nhớ đệm, nhận thông báo thay đổi nhờ webhook và tuân thủ giới hạn tốc độ theo địa chỉ IP và theo khóa API.

Một tích hợp truy vấn Omniscol mỗi phút để kiểm tra dữ liệu có thay đổi hay không thường nhận được phản hồi giống hệt lần gọi trước. Nó tiêu tốn hạn mức một cách vô ích và gây tải cho máy chủ mà không thu được thông tin mới.

Trang này giới thiệu các cơ chế giúp tránh những lệnh gọi thừa đó, cùng các giới hạn tốc độ áp dụng cho API.

Tránh tải lại dữ liệu không đổi

Hầu hết các phản hồi đọc của API đều có tiêu đề ETag, dùng để nhận diện một phiên bản của phản hồi. Hãy lưu giá trị này cùng với dữ liệu nhận được và gửi lại trong tiêu đề If-None-Match ở lần gọi tiếp theo:

curl -i -G "https://ten-truong-cua-ban.omniscol.com/api/schedules/lessons/20261102-20261108" \
     -H "Authorization: Bearer $TOKEN" \
     -H 'If-None-Match: W/"os1.…"'

Nếu dữ liệu không đổi, Omniscol trả về 304 Not Modified và không có nội dung phản hồi. Khi đó bạn có thể dùng lại dữ liệu đã lưu trong bộ nhớ đệm. Nếu ngược lại, bạn nhận được phản hồi 200 OK đầy đủ, kèm một ETag mới.

ETag là một giá trị không diễn giải được (opaque): hãy lưu và gửi lại đúng nguyên văn, kể cả dấu ngoặc kép và tiền tố W/, không cố tự tạo hay giải mã nó. ETag gắn với yêu cầu đã tạo ra nó và với quyền truy cập được dùng: đừng dùng lại cho một URL khác hoặc với một mã thông báo khác.

Tiêu đề Cache-Control: private, no-cache cho biết phản hồi có thể được lưu trong bộ nhớ đệm riêng, nhưng phải được xác thực lại với Omniscol trước khi dùng lại. Đó chính là vai trò của If-None-Match.

Một số phản hồi không có ETag, đặc biệt khi chúng phụ thuộc vào ngày hiện tại và có thể thay đổi mà dữ liệu của tài khoản không bị chỉnh sửa. Những phản hồi này phải được tải lại ở mỗi lần gọi.

Sau khi Omniscol triển khai phiên bản mới, các ETag được làm mới, dù dữ liệu không đổi. Lần gọi đầu tiên khi đó nhận phản hồi 200, rồi các lần gọi sau lại có thể hưởng lợi từ phản hồi 304.

304 cũng giảm khối lượng xử lý phía máy chủ. Trong phần lớn trường hợp, khi không có dữ liệu nào của tài khoản thay đổi kể từ lần gọi trước, Omniscol có thể trả lời mà không cần đọc lại dữ liệu liên quan, và 304 này khi đó không bị tính vào hạn mức gắn với khóa API của bạn. Ngược lại, một 304 có đọc lại dữ liệu vẫn được tính như một phản hồi thông thường.

Vì vậy, việc xác thực lại thường xuyên có chi phí thấp khi dữ liệu không đổi. Tuy nhiên, nó vẫn chịu giới hạn chung theo địa chỉ IP.

Lưu phản hồi vào bộ nhớ đệm

Nếu nhiều người dùng hoặc nhiều màn hình trong ứng dụng của bạn cùng xem một dữ liệu, không cần truy vấn Omniscol cho từng người hay từng màn hình.

Hãy lưu các phản hồi và ETag của chúng trong một bộ nhớ đệm ứng dụng do bạn kiểm soát, chẳng hạn Redis, Memcached hoặc một bảng cơ sở dữ liệu. Ứng dụng của bạn khi đó có thể phục vụ dữ liệu từ bộ nhớ đệm này, và bộ nhớ đệm đảm nhiệm việc xác thực lại với Omniscol bằng If-None-Match, theo chu kỳ đều đặn hoặc khi một webhook báo có thay đổi.

Khóa bộ nhớ đệm phải tính đến URL đầy đủ, mã thông báo xác thực được dùng và, khi bạn dùng đến, nội dung của yêu cầu GET cùng các tiêu đề làm thay đổi phản hồi, chẳng hạn Accept-Language. Hai mã thông báo có quyền khác nhau có thể truy cập các dữ liệu khác nhau: phản hồi nhận được bằng một trong hai mã không bao giờ được phục vụ cho người dùng mà quyền không cho phép truy cập dữ liệu đó.

Hãy lưu cả nội dung của mỗi phản hồi cùng với ETag của nó. Nếu thiếu dữ liệu tương ứng, phản hồi 304 không cho phép dựng lại kết quả mong muốn.

Bộ nhớ đệm ứng dụng này khác với bộ nhớ đệm HTTP dùng chung: chỉ thị Cache-Control: private cấm bộ nhớ đệm dùng chung lưu các phản hồi.

Nhận thông báo thay vì truy vấn định kỳ

Thay vì kiểm tra định kỳ xem dữ liệu có thay đổi hay không, bạn có thể yêu cầu Omniscol thông báo cho ứng dụng của bạn khi có thay đổi xảy ra.

Cơ chế này dựa trên các webhook, được cấu hình trong màn hình tùy chỉnh API (xem Tùy chỉnh API). Một webhook có thể theo dõi một điểm truy cập cụ thể hoặc một sự kiện gộp nhiều thay đổi, chẳng hạn việc sửa đổi thời khóa biểu.

Vô hiệu hóa bộ nhớ đệm khi nhận webhook

Cách dùng đơn giản nhất là coi webhook như một tín hiệu vô hiệu hóa.

Khi có thông báo đến, ứng dụng của bạn đánh dấu các dữ liệu liên quan là đã hết hạn và xác thực lại chúng với Omniscol. Không cần diễn giải nội dung của thay đổi: webhook chỉ cho biết cần kiểm tra lại.

Cách hoạt động này kết hợp tự nhiên với bộ nhớ đệm đã mô tả ở trên.

Đồng bộ các tiết học theo phần chênh lệch

Nếu bạn duy trì một bản sao đồng bộ của các tiết học, tùy chọn Kèm dữ liệu của sự kiện sửa đổi thời khóa biểu cho phép nhận một phần chênh lệch gồm các tiết học được thêm, sửa và xóa.

Ứng dụng của bạn khi đó chỉ cần áp dụng những thay đổi này, không phải tải lại toàn bộ thời khóa biểu.

Đảm bảo nhận được thông báo

Omniscol chỉ thực hiện một lần gửi cho mỗi webhook. Nó chờ tối đa bốn giây, không thử lại nếu thất bại và ghi lỗi vào nhật ký của mình.

Do đó máy chủ của bạn phải xác nhận nhanh bằng phản hồi 200 OK hoặc 202 Accepted, rồi xử lý cần thiết một cách bất đồng bộ.

Hãy giữ thêm một lần xác thực lại định kỳ làm cơ chế bù. Nếu máy chủ của bạn không khả dụng lúc webhook được gửi, lần kiểm tra này sẽ phát hiện các thay đổi bị bỏ lỡ. Nhờ các phản hồi 304, chi phí của nó vẫn thấp khi dữ liệu đã cập nhật.

Bảo mật webhook

Để xác minh một thông báo thật sự đến từ Omniscol, hãy cấu hình một tiêu đề HTTP tùy chỉnh chứa một bí mật chỉ ứng dụng của bạn và Omniscol biết. Máy chủ của bạn phải từ chối các lệnh gọi không mang giá trị mong đợi.

Hai tiêu đề bổ sung cung cấp thông tin về ngữ cảnh của thông báo:

  • X-School xác định tài khoản Omniscol liên quan;
  • X-OS-auth chứa mã thông báo xác thực của người dùng đã thực hiện thay đổi.

Mã thông báo truyền trong X-OS-auth là thông tin bảo mật. Đừng ghi nó vào nhật ký của bạn, đừng chuyển cho các dịch vụ khác và hạn chế nghiêm ngặt quyền truy cập vào nó.

Chỉ yêu cầu dữ liệu cần thiết

Phản hồi chứa ít dữ liệu hơn thường được tạo, truyền và lưu vào bộ nhớ đệm nhanh hơn.

Với các tiết học, hãy giới hạn khoảng thời gian yêu cầu và lọc kết quả theo các đối tượng bạn quan tâm (xem API tiết học).

Với các tìm kiếm, điểm truy cập search/query cung cấp bộ lọc, chọn trường và phân trang (xem Truy vấn nâng cao).

Để cập nhật nhiều phần tử cùng loại (lớp, phòng học, môn học, v.v.), hãy ưu tiên các điểm truy cập cho phép gửi trọn một tập hợp trong một yêu cầu duy nhất, khi chúng có trong tài liệu OpenAPI, thay vì gửi nhiều lệnh gọi đơn lẻ.

Tuân thủ giới hạn tốc độ

Hai giới hạn tốc độ áp dụng cho các lệnh gọi API. Khi chạm một giới hạn, Omniscol trả về 429 Too Many Requests, kèm tiêu đề Retry-After cho biết số giây cần chờ trước khi gửi lại yêu cầu.

Giới hạn theo địa chỉ IP

Giới hạn chung là 300 yêu cầu trong mỗi khoảng 10 giây, tính chung mọi điểm truy cập của API, kể cả MCP và các bảng thông tin.

Ngưỡng này thường đủ cho một tích hợp được thiết kế đúng cách. Tuy nhiên, vòng lặp gọi không có độ trễ hoặc quá nhiều yêu cầu song song có thể làm chạm ngưỡng này.

Giới hạn theo khóa API

Các mã thông báo cùng thuộc một khóa API dùng chung hai hạn mức:

  • 60 yêu cầu mỗi phút;
  • 5 000 yêu cầu mỗi ngày.

Các phản hồi có thể mang các tiêu đề sau, giúp theo dõi mức tiêu thụ:

  • RateLimit-Policy cho biết các hạn mức áp dụng, chẳng hạn 60;w=60, 5000;w=86400;
  • RateLimit-Limit cho biết hạn mức ứng với giới hạn sắp đạt nhất;
  • RateLimit-Remaining cho biết số yêu cầu còn lại của hạn mức đó;
  • RateLimit-Reset cho biết số giây còn lại trước khi hạn mức được làm mới.

Các tiêu đề này đặc biệt không xuất hiện trong các phản hồi 304 nhận được mà không đọc lại dữ liệu: việc không thấy chúng không có nghĩa là hạn mức đã cạn.

Khi hạn mức đã cạn, phản hồi 429 còn cho biết thời gian chờ trong nội dung của nó, qua trường retry_after.

Các phản hồi 304 nhận được mà không đọc lại dữ liệu không bị tính vào các hạn mức này, nhưng vẫn chịu giới hạn chung theo địa chỉ IP.

Nếu các giới hạn này cản trở một cách dùng API chính đáng, hãy liên hệ với chúng tôi thay vì tạo thêm nhiều khóa.

Xử lý lỗi và thử lại

Sau phản hồi 429

Hãy tuân theo thời gian chờ do Retry-After chỉ định trước khi gửi lại yêu cầu. Thử lại ngay lập tức là vô ích và có thể kéo dài tình trạng, nhất là khi nhiều tiến trình của ứng dụng cùng thử lại một lúc.

Sau lỗi máy chủ hoặc quá thời gian chờ

Sau lỗi 5xx hoặc khi quá thời gian chờ, một yêu cầu đọc có thể được gửi lại với khoảng cách tăng dần giữa các lần thử: chẳng hạn một giây, rồi hai, rồi bốn, cho đến một số lần thử tối đa.

Với yêu cầu ghi, tình huống khác: thay đổi có thể đã được ghi nhận dù phản hồi chưa bao giờ đến được với bạn. Hãy kiểm tra trạng thái thực của dữ liệu trước khi thực hiện lại thao tác, để tránh các thay đổi bị trùng lặp.

Sau phản hồi 401

Phản hồi 401 Unauthorized thường không thể giải quyết bằng cách thử lại với cùng mã thông báo. Nó có thể cho biết mã thông báo đã hết hạn, khóa API của nó đã bị xóa hoặc đã hết hạn, hoặc điểm truy cập được yêu cầu không nằm trong số những điểm mà khóa cho phép.

Hãy kiểm tra mã thông báo và các quyền liên quan trước khi gọi lại (xem API Omniscol).

Xem thêm