راهنمای اتصال ArtanLMS به ArtanClass

ArtanClass سرویس کلاس مجازی ماست. ArtanLMS سامانهٔ آموزشی شماست. اتصال فقط دو API دارد: ثبت کلاس با اعضا و دریافت لینک ورود شخصی.

۱. اتصال را آماده کنید

در پنل مدیر ArtanClass، بخش «اتصال به LMS»، یک کلید بسازید و نشانی اصلی LMS را ثبت کنید. این نشانی مقصد بازگشت افراد از کلاس است.

کلید را فقط در تنظیمات سرور LMS نگه دارید. نشانی توسعهٔ محلی https://meet.localhost است؛ روی سرور از دامنهٔ واقعی ArtanClass استفاده کنید.

ARTANCLASS_BASE_URL=https://meet.localhost
ARTANCLASS_API_KEY=art_lms_YOUR_SERVER_KEY

هر درخواست با این دو هدر ارسال شود:

Authorization: Bearer art_lms_YOUR_SERVER_KEY
Content-Type: application/json

۲. کلاس را همراه معلم و دانش‌آموزان ثبت کنید

هنگام ثبت کلاس در LMS یا تغییر اعضای آن، سرور LMS این درخواست را بفرستد:

POST /api/v1/lms/classes

{
  "external_class_id": "math-701",
  "name": "ریاضی هفتم ۷۰۱",
  "teacher": {
    "external_user_id": "teacher-42",
    "name": "سمیه احمدی",
    "national_id": "0012345679"
  },
  "students": [
    {
      "external_user_id": "student-101",
      "name": "علی رضایی",
      "national_id": "0023456787"
    },
    {
      "external_user_id": "student-102",
      "name": "مریم محمدی",
      "national_id": "0034567895"
    }
  ]
}

پاسخ موفق فقط لینک دائمی کلاس است؛ این لینک را در رکورد همان کلاس در LMS ذخیره کنید. کلاس جدید پاسخ 201 و کلاس موجود پاسخ 200 دارد.

{"class_url":"https://meet.localhost/c/ریاضی-هفتم-۷۰۱"}

• external_class_id شناسهٔ ثابت کلاس در LMS است؛ ۱ تا ۱۲۸ نویسهٔ انگلیسی، عدد، زیرخط یا خط تیره. برای جلسهٔ بعد همان شناسه را استفاده کنید.

• name نام نمایشی کلاس، تا ۲۵۵ نویسه است. لینک کلاس جدید از همین نام ساخته می‌شود؛ در صورت تشابه، پسوند یکتا می‌گیرد. لینک برگشتی را ذخیره کنید و خودتان نسازید.

• teacher یک معلم و students فهرست کامل دانش‌آموزان است؛ آرایهٔ خالی [] هم مجاز است. حداکثر ۹۹۹ دانش‌آموز پذیرفته می‌شود.

• برای هر شخص فقط external_user_id، name و national_id را بفرستید. شناسهٔ شخص رشتهٔ ثابت و یکتا در همان اتصال است، تا ۱۲۸ نویسه. کد ملی رشتهٔ ده‌رقمی معتبر است؛ صفر اول را حفظ کنید.

• ظرفیت خودکار برابر یک معلم + تعداد دانش‌آموزان است؛ ظرفیت این نمونه ۳ نفر می‌شود.

• حساب تازه با رمز اولیهٔ برابر کد ملی ساخته می‌شود. نام و رمز حساب موجود خودکار عوض نمی‌شود. نقش یا هویت ناسازگار باید توسط مدیر اصلاح شود.

• همان کلاس با همان شناسه به‌روز می‌شود؛ کلاس جدیدی ایجاد نمی‌شود. برای تغییر اعضا فهرست کامل را بفرستید. شمارهٔ نسخه لازم نیست؛ ترتیب درخواست‌های تغییر را در سرور LMS حفظ کنید تا فهرست قدیمی دیرتر ارسال نشود.

• تغییر نام، معلم یا اعضا هنگام جلسهٔ فعال با 409 class_running متوقف می‌شود. پس از پایان جلسه دوباره ارسال کنید. ارسال همان اطلاعات بدون تغییر مجاز است.

• تنظیمات وبکم و استریم از پنل ArtanClass مدیریت می‌شود و از این API دریافت نمی‌شود. نامک دستی موجود حفظ می‌شود.

• ثبت کلاس به‌تنهایی جلسهٔ زنده یا مصرف پردازشی کلاس ایجاد نمی‌کند. کلاس دائمی است تا مدیر آن را بایگانی کند؛ پایان جلسه کلاس را حذف نمی‌کند.

۳. دکمهٔ ورود به کلاس را متصل کنید

وقتی شخص در LMS روی «ورود به کلاس» می‌زند، ابتدا سرور LMS ورود و عضویت او را بررسی کند. شناسهٔ کلاس و کاربر را از پایگاه داده و نشست معتبر خودتان بردارید.

POST /api/v1/lms/classes/math-701/launch

{"external_user_id":"teacher-42"}

پاسخ موفق 200 فقط لینک ورود شخصی است:

{"entry_url":"https://meet.localhost/sso/launch#ticket=EXAMPLE&browser_nonce=EXAMPLE"}

مرورگر همان شخص را با پاسخ 303 Redirect به مقدار کامل entry_url بفرستید. شخص نامش را تأیید می‌کند و وارد می‌شود؛ رمز دوباره لازم نیست. معلم جلسه را خودکار شروع می‌کند. دانش‌آموز زودتر رسیده، صفحهٔ انتظار معلم را می‌بیند.

برای دانش‌آموز دقیقاً همین درخواست را با شناسهٔ خودش، مثلاً student-101 بفرستید. نقش از عضویت ثبت‌شده تعیین می‌شود؛ نقش، مشخصات فرد و شناسهٔ نشست را دوباره نفرستید.

لینک شخصی فقط یک بار و تا ۱۲۰ ثانیه معتبر است. آن را در دیتابیس یا لاگ ذخیره نکنید و بین افراد به اشتراک نگذارید. بخش بعد از # را حذف نکنید. برای کلیک بعدی یا لینک منقضی، درخواست جدید بفرستید.

ArtanClass نشست مرورگر را مدیریت می‌کند. ورود از دستگاه دیگر طبق محدودیت یک نشست انجام می‌شود؛ استثنای چندنشستی را مدیر برای هر کاربر فعال می‌کند. ظرفیت کلاس در لحظهٔ پیوستن هم بررسی می‌شود.

class_url لینک ثابت کلاس است و صفحهٔ ورود نام کاربری یا کد ملی و رمز را باز می‌کند. entry_url لینک شخصی ورود از LMS است؛ این دو کاربرد متفاوت دارند.

نمونه‌کدها

کنار این راهنما فایل‌های artanclass.go، artanclass.mjs و requests.sh قرار دارند. نمونهٔ بدنه و پاسخ‌ها در فایل‌های JSON و قرارداد فنی در lms-api.openapi.json است.

// Node.js — داخل سرور LMS و پس از بررسی عضویت
const { class_url } = await client.createClass(classData);
const { entry_url } = await client.getEntryLink(classId, authenticatedUser.externalId);

// Go — داخل سرور LMS و پس از بررسی عضویت
classroom, err := client.CreateClass(ctx, classData)
entry, err := client.EntryLink(ctx, classID, authenticatedUser.ExternalID)
// پیش از استفاده از نتیجه، err هر درخواست را بررسی کنید.

فضای تست مستندات

در سایت مستندات، صفحهٔ «فضای تست API» را باز کنید، کلید اتصال را وارد کنید و ابتدا ساخت کلاس و سپس دریافت لینک شخص را ارسال کنید. این صفحه درخواست واقعی می‌فرستد و اطلاعات واقعی می‌سازد یا همگام می‌کند. داده‌های نمونه ساختگی آموزشی هستند؛ از کلاس نمونهٔ جدا استفاده کنید.

کلید فقط تا زمان باز بودن صفحه در حافظه می‌ماند و ذخیره نمی‌شود. قابلیت ارسال در نصب محلی فعال است؛ نسخهٔ عمومی مستندات می‌تواند فقط خواندنی باشد. دکمهٔ ارسال جای پیاده‌سازی سرور LMS را نمی‌گیرد.

خطاها را چطور مدیریت کنید؟

{"code":"invalid_payload","errors":["اطلاعات درخواست را اصلاح کنید."]}

درخواست JSON حداکثر ۲ مگابایت است. برای هر کلید، ساخت/همگام‌سازی ۱۲۰ درخواست و گرفتن لینک ۱۲۰۰ درخواست در دقیقه مجاز است. همهٔ تغییرات یک درخواست ثبت کلاس در یک تراکنش انجام می‌شوند.

چک‌لیست تحویل به برنامه‌نویس LMS

• کلید اتصال فقط روی سرور نگه داشته شود؛ درخواست مستقیم از جاوااسکریپت عمومی LMS ارسال نشود.

• شناسهٔ کلاس و افراد در LMS ثابت بماند و عضویت قبل از گرفتن لینک بررسی شود.

• لینک ثابت کلاس ذخیره شود؛ لینک شخصی فقط هنگام ورود صادر و فوراً استفاده شود.

• در خروجی مسیر ورود LMS، Cache-Control: no-store و Referrer-Policy: no-referrer تنظیم شود.

• روی سرور آنلاین از HTTPS معتبر استفاده شود. اعتبارسنجی TLS را برای نمونه‌ها خاموش نکنید.