Tổng quan OneRoster
Kết nối phần mềm quản lý đào tạo (SIS) của trường với cổng thực tập theo chuẩn OneRoster 1.2.
Mỗi cổng thực tập của một trường mở một API theo chuẩn quốc tế 1EdTech OneRoster 1.2, để phần mềm quản lý đào tạo (SIS) hay hệ thống khác của trường đọc danh sách sinh viên, đợt thực tập và kết quả thực tập. Phần mềm nào đã hỗ trợ OneRoster đều kết nối được mà không cần viết riêng.
Đặc điểm chính
- Chuẩn: OneRoster 1.2, phần Rostering (danh sách) và Gradebook (kết quả), giao thức REST, chỉ đọc.
- Xác thực: OAuth 2.0, luồng Client Credentials, đúng như OneRoster 1.2 yêu cầu. Xem Xác thực.
- Địa chỉ: mỗi trường dùng chính địa chỉ cổng của trường, ví dụ
https://<trường>.<tên-miền-nền-tảng>. Thông tin xác thực của trường nào chỉ dùng được ở trường đó và chỉ thấy dữ liệu của trường đó. - Định dạng: JSON, mã hoá UTF-8. Thời điểm theo ISO 8601 (UTC); ngày (
startDate,endDate,scoreDate) theo giờ Việt Nam.
Bắt đầu nhanh
Tạo kết nối
Cán bộ nhà trường vào Kết nối hệ thống → Tạo kết nối, đặt tên, chọn quyền, rồi gửi mã ứng dụng (client_id) và khoá bí mật (client_secret) cho đơn vị phụ trách hệ thống. Khoá bí mật chỉ hiện một lần.
Lấy mã truy cập
curl -u "CLIENT_ID:CLIENT_SECRET" \
-d "grant_type=client_credentials" \
https://<trường>.<tên-miền-nền-tảng>/oauth/token{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "bearer",
"expires_in": 3600,
"scope": "https://purl.imsglobal.org/spec/or/v1p2/scope/roster.readonly https://purl.imsglobal.org/spec/or/v1p2/scope/gradebook.readonly"
}Gọi API
curl -H "Authorization: Bearer ACCESS_TOKEN" \
"https://<trường>.<tên-miền-nền-tảng>/ims/oneroster/rostering/v1p2/students?limit=100"Hai nhóm API
| Nhóm | Địa chỉ gốc | Nội dung |
|---|---|---|
| Danh sách (Rostering) | /ims/oneroster/rostering/v1p2 | Trường, đợt thực tập, học phần, lớp, sinh viên, cán bộ trường, ghi danh |
| Kết quả (Gradebook) | /ims/oneroster/gradebook/v1p2 | Kết quả thực tập của từng sinh viên trong từng đợt |
Chi tiết từng nhóm: Dữ liệu danh sách và Kết quả thực tập. Mã mẫu chạy được: Ví dụ đồng bộ.
Gửi dữ liệu vào cổng
API OneRoster chỉ đọc. Để hệ thống của trường gửi sinh viên, đợt thực tập, ghi danh vào cổng, có hai cách:
| Cách | Dùng khi |
|---|---|
| Gói CSV OneRoster | Phần mềm của trường xuất được gói CSV OneRoster |
| API của cổng (v1) | Hệ thống không theo OneRoster; cần API JSON đơn giản để đọc và gửi |
Đặc tả máy đọc được
Mỗi cổng có tệp OpenAPI 3 tại /ims/oneroster/openapi.json, nhập được vào Postman hoặc dùng để sinh mã. Bản đặc tả đầy đủ của chuẩn có tại trang 1EdTech.