Tùy chỉnh API: ghi đè điểm truy cập và hook

Tìm ở đâu

Mô-đun Quản trị, màn hình Nhập và xuất dữ liệu, mục Tùy chỉnh API, nút API.

Màn hình này chỉ dành cho tài khoản Premium và được bảo vệ bằng xác thực tăng cường: Omniscol hỏi lại mật khẩu của quản trị viên trước khi mở cửa sổ. Vì mọi thao tác trên màn hình này đều động đến hợp đồng kỹ thuật của phần tích hợp bên bạn, việc thiết lập được thực hiện phối hợp với Omniscol.

Cấu hình chung

Tại đây bạn khai báo các tiêu đề HTTP (theo dạng key1:value1;key2:value2) được áp dụng cho mọi hook. Đây là chỗ tự nhiên để mang một mã thông báo xác thực sang máy chủ của chính bạn (ví dụ một Authorization: Bearer … mà máy chủ của bạn chờ nhận). Ngược lại, với một lần ghi đè, phần xác thực nằm trong các tiêu đề riêng của từng điểm truy cập (xem bên dưới).

Ghi đè một điểm truy cập

Một lần ghi đè định nghĩa lại một điểm truy cập của API Omniscol để ứng dụng web gọi một URL khác thay cho nó. Có ba cách dùng, từ mạnh nhất đến đơn giản nhất.

Cấp dữ liệu trực tiếp từ hệ thống thông tin của bạn

Đây là cách dùng mạnh nhất. Bạn chuyển hướng một điểm truy cập đọc dữ liệu sang một URL bên ngoài — thường là một ETL làm cầu nối với hệ thống thông tin nội bộ của trường bạn. Ứng dụng web khi đó lấy dữ liệu trực tiếp trong hệ thống ấy, thay vì lấy bản sao cục bộ mà Omniscol đang giữ.

Cụ thể: khi URL chuyển hướng là một địa chỉ bên ngoài tuyệt đối, ứng dụng web gọi thẳng địa chỉ đó, không đi vòng qua máy chủ của Omniscol, và dùng nguyên phản hồi nhận được — đúng như thể phản hồi ấy đến từ Omniscol. Ràng buộc duy nhất là hệ thống của bạn phải trả lời đúng định dạng mà Omniscol chờ đợi cho điểm truy cập đó (cùng một cấu trúc JSON): không hề có bước chuyển mã trung gian. Với điểm truy cập này, bản sao cục bộ của Omniscol không còn được truy vấn nữa; dữ liệu hiển thị là dữ liệu sống của hệ thống bên bạn.

Ví dụ: danh mục môn học của trường được cấp trực tiếp theo yêu cầu từ hệ thống thông tin của bạn, sao cho mọi cập nhật ở phía nhà trường đều thấy được ngay trong Omniscol, không cần nhập lại dữ liệu.

Ở đây, phần xác thực tới hệ thống của bạn nằm trong các tiêu đề riêng của điểm truy cập (ví dụ một Authorization: Bearer …), nhập ngay trên dòng của lần ghi đè. Phương thức HTTP cũng có thể được ấn định theo từng điểm truy cập.

Đấu nối lại một điểm truy cập của chính ứng dụng vào một nguồn dữ liệu sống bên ngoài là khả năng vừa mạnh vừa đòi hỏi: hãy làm cùng bộ phận công nghệ thông tin của bạn, và cùng với Omniscol.

Chèn máy chủ của bạn hoặc một proxy

Bạn cũng có thể cho các lệnh gọi đi qua máy chủ của chính bạn hoặc một proxy — chẳng hạn để cho phép chia sẻ tài nguyên giữa các nguồn gốc khác nhau (CORS), hoặc để chèn một lớp xử lý tự xây giữa ứng dụng web và Omniscol.

Tắt một điểm truy cập

Bạn tắt một điểm truy cập bằng cách không cho nó URL chuyển hướng nào (phương thức null).

Hãy cân nhắc tác động lên giao diện. Omniscol là một ứng dụng web một trang (SPA) mà các thành phần giao diện đều do những điểm truy cập đang có điều khiển: nút, tab và menu chỉ hiện ra nếu điểm truy cập mà chúng dựa vào còn tồn tại. Vì vậy, tắt một điểm truy cập sẽ tự động làm biến mất, ở lần hiển thị kế tiếp, những thành phần giao diện phụ thuộc vào nó — và nếu bạn tắt toàn bộ điểm truy cập của một mô-đun thì cả mô-đun sẽ biến khỏi thanh điều hướng. Những thành phần đó bị gỡ bỏ chứ không chỉ bị ẩn đi, và tất cả diễn ra mà không phải động đến mã nguồn: chỉ cần sửa cấu hình rồi tải lại ứng dụng.

Bảng liệt kê, theo từng điểm truy cập: khóa của nó (mã nội bộ của thao tác), URL gốc, phương thức HTTP, URL mới để chuyển hướng và các tiêu đề riêng. Một ô tìm kiếm giúp bạn tìm lại điểm truy cập cần ghi đè.

Hook (các lệnh gọi đi)

Một hook yêu cầu Omniscol gửi một yêu cầu HTTP tới URL của bạn sau khi một thao tác đã thành công. Đây là cơ chế để giữ cho một hệ thống bên ngoài luôn nắm tình hình theo thời gian thực — một bảng thông tin, một không gian làm việc số, một hệ thống nhân sự, một cơ chế đồng bộ tự xây…

Một hook gắn được theo hai cách:

• vào một điểm truy cập cụ thể (khóa của thao tác);
• vào một sự kiện gộp, bao trọn cả một họ thao tác cùng lúc. Có ba sự kiện gộp:
  • thay đổi thời khóa biểu — một thay đổi chạm tới thời khóa biểu đang có hiệu lực, kể cả các tác động kéo theo: lưu một thời khóa biểu, tạo, dời hoặc xóa tiết học, kích hoạt một thời khóa biểu, vắng mặt của giáo viên hay của lớp ngay khi có một ngày bị ảnh hưởng, và những lần gỡ bỏ mang tính cấu trúc (một phòng học, một môn học…) trên một thời khóa biểu đã công bố (đang hoạt động) — gỡ một môn học sẽ xóa các tiết học dùng đến nó, tự thân đó đã là một thay đổi. Những chỉnh sửa chỉ nằm trong một bản nháp chưa hoạt động thì không làm sự kiện này phát đi;
  • thay đổi giáo viên (thêm, cập nhật hoặc xóa);
  • thay đổi môn học (các môn học tùy chỉnh).

Với mỗi hook, bạn khai báo URL gọi lại, phương thức HTTP, ô đánh dấu “kèm dữ liệu” (có đính kèm phần thân của yêu cầu gốc hay không?) và các tiêu đề riêng.

Máy chủ của bạn nhận được gì

Lệnh gọi được gửi dưới dạng application/json và mang theo, ngoài các tiêu đề của bạn:

• phần thân của yêu cầu gốc nếu tùy chọn “kèm dữ liệu” đang bật;
• một khối siêu dữ liệu của Omniscol: URL được gọi, mã của điểm truy cập, phương thức, các tham số, mã thông báo xác thực của người dùng, mã định danh của trường và chính cấu hình của hook;
• các tiêu đề phục vụ truy vết: X-OS-original-query, X-OS-original-endpoint, X-OS-auth và X-School.

Với sự kiện thay đổi thời khóa biểu, khi tùy chọn “kèm dữ liệu” đang bật, lệnh gọi còn kèm thêm một bảng chênh lệch tiết học (tiết học được thêm, được sửa, bị xóa) — rất tiện để chỉ lan truyền đúng phần đã thay đổi.

Cách hoạt động

Các hook được phát đi ở chế độ nền, sau khi thao tác của người dùng đã hoàn tất: chúng không làm chậm giao diện và không chặn giao diện nếu máy chủ của bạn gặp sự cố. Một lệnh gọi đi không tới đích sẽ được ghi vào nhật ký, mà không làm gián đoạn công việc trong Omniscol. Mỗi lệnh gọi có thời gian chờ ngắn (vài giây): máy chủ của bạn phải báo nhận thật nhanh rồi xử lý phần còn lại ở phía mình.

Những điều nên biết

• API của Omniscol chỉ mở ra một tập con các thao tác; một lần ghi đè hay một hook chỉ áp dụng cho những điểm truy cập thật sự được mở. Xem API Omniscol để biết danh sách và cách xác thực.
• Với một phần tích hợp cùng phần mềm đóng gói (ERP, hệ thống nhân sự, không gian làm việc số), cơ chế đồng bộ chuyên dụng thường phù hợp hơn — xem Đồng bộ hóa với các hệ thống bên ngoài. Bên trong, chính hệ thống hook này được dùng lại.
• Để một tác nhân AI tra cứu dữ liệu của bạn mà không cần lập trình, xem MCP — kết nối một tác nhân AI bên ngoài.