Skip to content

docs.md

Latest commit

 

History

History
889 lines (755 loc) · 24.5 KB

docs.md

File metadata and controls

889 lines (755 loc) · 24.5 KB

راهنمای استفاده از وب‌سرویس اسکای‌روم

آشنایی با وب‌سرویس اسکای‌روم

معرفی

وب‌سرویس اسکای‌روم با هدف یک‍پارچه‌سازی و بکارگیری سرویس‌های اسکای‌روم در سایر سامانه‌ها و برنامه‌های نرم‌افزاری طراحی و پیاده‌سازی شده است. با بهره‌گیری از وب‌سرویس اسکای‌روم می‌توانید سرویس‌ها، اتاق‌های مجازی، کاربران و سایر امکانات فراهم شده را از درون سامانه یا اپلیکیشن خود و با فراخوانی دستورات وب‌سرویس (API) مدیریت نمایید.

مشخصات فنی

وب‌سرویس اسکای‌روم بر پایه REST طراحی و پیاده‌سازی گردیده و در آن تلاش شده است تا ضمن الگوبرداری از استانداردهای رایج دنیا، سادگی در اولویت نخست باشد. از اینرو در وب‌سرویس اسکای‌روم تمامی درخواست‌ها (request) به شکل POST ارسال می‌گردند.

  • فرمت داده‌های ارسالی (Content-Type) می‌تواند یکی از انواع JSON یا URL-Encoded باشد.
  • پاسخ همواره JSON خواهد بود.
  • به منظور تفکیک خطاهای شبکه و سرور از خطاهای برنامه، تمامی پاسخ‌ها از سوی وب‌سرویس (چه موفق چه ناموفق) با کد وضعیت 200 برگردانده می‌شود.
    (200 = HTTP Status Code)

نکات مهم برای توسعه‌دهندگان

  • بهتر است اتاق‌ها و کاربران یک‌بار ایجاد و به دفعات استفاده شوند. پس از ایجاد هر اتاق یا کاربر، شناسه آن را در دیتابیس ذخیره کرده و در نشست‌های بعدی استفاده کنید. ساخت اتاق و کاربر برای هر بار برگزاری کلاس و حذف آن‌ها در پایان کلاس (خصوصاً زمانی که تعداد کلاس‌ها زیاد باشد) توصیه نمی‌شود؛ چون علاوه بر ایجاد سربار، ممکن است باعث عبور از محدودیت‌های سرویس‌دهنده و دریافت خطا شود.
  • اگر تعداد کلاس‌های همزمان زیادی دارید (مثل مدارس و دانشگاه‌ها)، ایجاد لینک ورود با تابع createLoginUrl هزینه زیادی خواهد داشت و ممکن است با محدودیت نرخ ارسال درخواست در دقیقه مواجه شوید. توصیه می‌شود لینک‌های ورود را از پیش ایجاد و در دیتابیس نگهداری کنید تا با هر بار ورود و خروج کاربر نیاز به ساخت دوباره آن نباشد. با پارامتر ttl می‌توانید زمان منقضی شدن لینک‌ها را مدیریت نمایید.
  • در بروزرسانی‌های اخیر روی توابع getRoom و getUser، امکان جستجوی اتاق/کاربر با نام فراهم شده است؛ بنابراین برای پیدا کردن یک کاربر یا اتاق نیازی به دریافت کل لیست نیست. این بهبود می‌تواند در راندمان و کاهش خطاها بسیار مؤثر باشد.
  • نرخ ارسال درخواست‌ها در حال حاضر محدود به ۵۰۰ درخواست در دقیقه است. درخواست‌های بیشتر با خطای 503 روبرو می‌شوند.
  • به علت اجتناب‌ناپذیر بودن اختلالات شبکه، علاوه بر مدیریت خطاهای وب‌سرویس، خطاهای زیرساختی مثل ریسالو نشدن دامنه، تایم‌آوت و خطای SSL را نیز مدیریت کرده و لاگ کنید.

آدرس وب‌سرویس

ساختار آدرس (URL) وب‌سرویس:

https://www.skyroom.online/skyroom/api/{your-api-key}

در اینجا {your-api-key} یک رشته به طول ۵۰ حرف و کلید اختصاصی شما برای استفاده از وب‌سرویس است و در تمامی درخواست‌ها جزء ثابت آدرس خواهد بود.

ارسال درخواست

شکل کلی درخواست:

POST https://www.skyroom.online/skyroom/api/apikey-71-819540-0f178abb0c712c4cfd5ae13e4c54687a
{
  "action": "actionName",
  "params": {
    "param_1": "value1",
    "param_2": "value2",
    "param_3": "value3"
  }
}
  • action: تابعی که قصد فراخوانی آن را داریم.
  • params: پارامترهای تابع.

توجه: نام تابع و پارامترهای ارسالی به کوچکی و بزرگی حروف حساس هستند.

دریافت پاسخ

فرم کلی پاسخ‌ها:

{
  "ok": true,
  "result": "action-result"
}
  • ok: مقدار true یا false (موفق/ناموفق)
  • result: نتیجه عملیات در صورت موفق بودن (می‌تواند number، string، [] یا {} باشد)

نمونه‌ها:

{ "ok": true, "result": 12 }
{ "ok": true, "result": "https://www.skyroom.online/ch/web-conference" }
{
  "ok": true,
  "result": ["item1", "item2", "item3"]
}
{
  "ok": true,
  "result": {
    "key1": 32,
    "key2": "value2",
    "key3": ["item1", "item2", "item3"]
  }
}

مدیریت خطاها

تمامی پاسخ‌ها (موفق/ناموفق) با کد وضعیت HTTP برابر 200 برمی‌گردند. بنابراین:

  • اگر HTTP Status Code چیزی غیر از 200 باشد: خطای شبکه/سرور رخ داده و باید مدیریت شود.
  • اگر خطای برنامه‌ای رخ دهد، بدنه پاسخ این شکل را دارد:
HTTP/1.1 200 OK
{
  "ok": false,
  "error_code": 14,
  "error_message": "درخواست شما با خطا روبرو شد."
}

کد خطاهای عمومی

کد خطا توضیح
10 وب‌سرویس غیرفعال است.
11 کلید وب‌سرویس نامعتبر است.
12 درخواست شما غیرمجاز است.
13 درخواست شما معتبر نیست.
14 درخواست شما با خطا روبرو شد.
15 داده‌ مورد نظر پیدا نشد.

امکانات مدیریتی

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

  1. مدیریت سرویس‌ها
  2. مدیریت اتاق‌ها
  3. مدیریت کاربران

۱) مدیریت سرویس‌ها

شما در اسکای‌روم سرویس خود را بر اساس مولفه‌هایی مانند تعداد کاربر همزمان، تعداد ویدیوی همزمان در هر اتاق، حجم نفرساعت مصرفی و بازه زمانی بهره‌برداری خریداری می‌کنید. برای ساخت اتاق‌های مجازی، وجود حداقل یک سرویس فعال الزامی است.

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

مشخصات سرویس

ویژگی نوع مقدار
id number شناسه سرویس
title string عنوان سرویس (حداکثر ۱۲۸ حرف)
status number وضعیت سرویس (0: غیرفعال - 1: فعال)
user_limit number سقف تعداد کاربر آنلاین
video_limit number سقف تعداد ویدیوی همزمان (در هر اتاق)
time_limit number محدودیت نفرثانیه
time_usage number نفرثانیه مصرف شده
start_time Unix time زمان شروع سرویس
stop_time Unix time زمان پایان سرویس
create_time Unix time زمان ایجاد سرویس
update_time Unix time زمان آخرین بروزرسانی

توابع سرویس

نام تابع شرح مقدار بازگشتی نوع مقدار بازگشتی
getServices دریافت لیست سرویس‌های موجود لیست سرویس‌ها []

دریافت لیست سرویس‌های موجود

درخواست:

{
  "action": "getServices"
}

پاسخ (نمونه):

[
  {
    "id": 1,
    "title": "سرویس وب کنفرانس",
    "status": 1,
    "user_limit": 10,
    "video_limit": 8,
    "time_limit": null,
    "time_usage": 2213762,
    "start_time": 1582851460,
    "stop_time": 1580259460,
    "create_time": 1582851460,
    "update_time": 1580259460
  },
  {
    "id": 2,
    "title": "سرویس آموزش آنلاین",
    "status": 0,
    "user_limit": 100,
    "video_limit": 3,
    "time_limit": null,
    "time_usage": 21124,
    "start_time": 1580259460,
    "stop_time": 1582851460,
    "create_time": 1479021195,
    "update_time": 1582851460
  }
]

۲) مدیریت اتاق‌ها

با استفاده از اتاق‌های مجازی می‌توان رویدادهای مختلف را به صورت همزمان و کاملاً مجزا برگزار نمود. هر اتاق دارای یک نام واحد است که آدرس (URL) اتاق نیز با همان نام ساخته می‌شود؛ بنابراین بهتر است نام را به صورت لاتین وارد کنید.

می‌توان محدودیت‌هایی مثل سقف کاربر آنلاین، میزان نفرساعت مصرفی و جلوگیری از ورود کاربران پیش از ورود اپراتور را اعمال کرد.

مشخصات اتاق

ویژگی نوع مقدار
id number شناسه اتاق
service_id number شناسه سرویس
name string نام اتاق به لاتین (حداکثر ۱۲۸ حرف)
title string عنوان اتاق (حداکثر ۱۲۸ حرف)
description string شرح اتاق (حداکثر ۵۱۲ حرف)
status number وضعیت اتاق
guest_login bool ورود به صورت میهمان
guest_limit number محدودیت تعداد میهمان (0 = نامحدود)
op_login_first bool ابتدا اپراتور وارد شود
max_users number سقف تعداد کاربر آنلاین
session_duration number محدودیت طول نشست
time_limit number محدودیت نفرثانیه
time_usage number نفرثانیه مصرف شده
time_total number مجموع نفرثانیه مصرف شده
create_time Unix time زمان ایجاد
update_time Unix time آخرین بروزرسانی

توابع اتاق

نام تابع شرح مقدار بازگشتی نوع مقدار بازگشتی
getRooms دریافت لیست اتاق‌های موجود لیست اتاق‌ها []
countRooms دریافت تعداد اتاق‌های موجود تعداد اتاق‌ها number
getRoom دریافت مشخصات یک اتاق مشخصات اتاق {}
getRoomUrl دریافت آدرس یک اتاق آدرس اتاق string
createRoom ایجاد اتاق جدید شناسه اتاق ایجاد شده number
updateRoom بروزرسانی اتاق 1 number
deleteRoom حذف اتاق 1 number
getRoomUsers دریافت لیست کاربران دارای دسترسی به اتاق لیست کاربران []
addRoomUsers افزودن دسترسی کاربران به اتاق تعداد کاربران افزوده شده number
removeRoomUsers حذف دسترسی کاربران از اتاق تعداد کاربران حذف شده number
updateRoomUser تغییر دسترسی کاربر به اتاق 1 number

دریافت لیست اتاق‌های موجود

درخواست:

{
  "action": "getRooms"
}

پاسخ:

{
  "ok": true,
  "result": [
    {
      "id": 1,
      "service_id": 8230,
      "name": "meeting",
      "title": "اتاق جلسات",
      "status": 1
    },
    {
      "id": 2,
      "service_id": 8230,
      "name": "learning-php",
      "title": "کلاس آموزش PHP",
      "status": 0
    }
  ]
}

دریافت تعداد اتاق‌های موجود

درخواست:

{
  "action": "countRooms"
}

پاسخ:

{
  "ok": true,
  "result": 2
}

دریافت مشخصات یک اتاق با استفاده از شناسه

درخواست:

{
  "action": "getRoom",
  "params": {
    "room_id": 1
  }
}

دریافت مشخصات یک اتاق با استفاده از نام

درخواست:

{
  "action": "getRoom",
  "params": {
    "name": "meeting"
  }
}

پاسخ:

{
  "ok": true,
  "result": {
    "id": 1,
    "service_id": 8230,
    "name": "meeting",
    "title": "اتاق جلسات",
    "description": null,
    "status": 1,
    "guest_login": false,
    "guest_limit": 0,
    "op_login_first": true,
    "max_users": 8,
    "session_duration": null,
    "time_limit": null,
    "time_usage": 184486,
    "time_total": 3144460,
    "create_time": 1479021434,
    "update_time": 1501559112
  }
}

دریافت آدرس یک اتاق

درخواست:

{
  "action": "getRoomUrl",
  "params": {
    "room_id": 1,
    "language": "fa"
  }
}

پاسخ:

{
  "ok": true,
  "result": "https://www.skyroom.online/ch/faramooz/meeting"
}

ایجاد اتاق جدید

درخواست:

{
  "action": "createRoom",
  "params": {
    "name": "math-exercise",
    "title": "کلاس حل تمرین ریاضی",
    "guest_login": false,
    "op_login_first": true,
    "max_users": 10
  }
}

پاسخ:

{
  "ok": true,
  "result": 3
}

بروزرسانی اتاق

درخواست:

{
  "action": "updateRoom",
  "params": {
    "room_id": 3,
    "max_users": 20
  }
}

پاسخ:

{
  "ok": true,
  "result": 1
}

حذف اتاق

درخواست:

{
  "action": "deleteRoom",
  "params": {
    "room_id": 3
  }
}

پاسخ:

{
  "ok": true,
  "result": 1
}

دریافت لیست کاربران دارای دسترسی به یک اتاق

درخواست:

{
  "action": "getRoomUsers",
  "params": {
    "room_id": 2
  }
}

پاسخ:

{
  "ok": true,
  "result": [
    {
      "user_id": 6344,
      "username": "operator",
      "nickname": "اپراتور",
      "access": 3
    },
    {
      "user_id": 6345,
      "username": "presenter",
      "nickname": "ارایه کننده",
      "access": 2
    },
    {
      "user_id": 6347,
      "username": "user-150",
      "nickname": "کاربر عادی",
      "access": 1
    }
  ]
}

انواع دسترسی‌ها: «کاربر عادی»، «ارایه کننده»، «اپراتور» و «مدیر». جدول انواع دسترسی در انتهای همین صفحه آمده است.

افزودن دسترسی کاربران به یک اتاق

درخواست:

{
  "action": "addRoomUsers",
  "params": {
    "room_id": 1,
    "users": [
      { "user_id": 6344 },
      { "user_id": 6345, "access": 2 }
    ]
  }
}

پاسخ:

{
  "ok": true,
  "result": 2
}

حذف دسترسی کاربران از یک اتاق

درخواست:

{
  "action": "removeRoomUsers",
  "params": {
    "room_id": 1,
    "users": [6344, 6345]
  }
}

پاسخ:

{
  "ok": true,
  "result": 2
}

تغییر دسترسی کاربر به یک اتاق

درخواست:

{
  "action": "updateRoomUser",
  "params": {
    "room_id": 1,
    "user_id": 6344,
    "access": 3
  }
}

پاسخ:

{
  "ok": true,
  "result": 1
}

۳) مدیریت کاربران

برای ورود به اتاق‌های مجازی و شرکت در رویدادها نیاز به ساخت حساب کاربری است. برای ساخت حساب کاربری، وارد کردن نام کاربری، گذرواژه و نام نمایشی الزامی است.

  • با هر حساب کاربری تنها یک بار می‌توان وارد اتاق شد.
  • اگر قرار است چند نفر به صورت همزمان از یک حساب استفاده کنند، باید یک حساب عمومی (Public) ایجاد کنید.
  • پس از ساخت حساب کاربری باید دسترسی کاربر به اتاق/اتاق‌ها اعطا شود.

مشخصات کاربر

ویژگی نوع مقدار
id number شناسه کاربر
username string نام کاربری به لاتین (حداکثر ۳۲ حرف)
nickname string نام نمایشی (حداکثر ۱۲۸ حرف)
password string گذرواژه (حداکثر ۲۴ حرف)
email string ایمیل (حداکثر ۱۲۸ حرف)
fname string نام (حداکثر ۱۲۸ حرف)
lname string نام خانوادگی (حداکثر ۱۲۸ حرف)
gender number جنسیت
status number وضعیت کاربر
is_public bool کاربر عمومی
concurrent number محدودیت استفاده همزمان (0 = نامحدود)
time_limit number محدودیت زمانی (ثانیه)
time_usage number زمان مصرف شده (ثانیه)
time_total number مجموع زمان مصرف شده (ثانیه)
expiry_date Unix time تاریخ انقضا
create_time Unix time زمان ایجاد
update_time Unix time آخرین بروزرسانی

توابع کاربر

نام تابع شرح مقدار بازگشتی نوع مقدار بازگشتی
getUsers دریافت لیست کاربران موجود لیست کاربران []
countUsers دریافت تعداد کاربران موجود تعداد کاربران number
getUser دریافت مشخصات یک کاربر مشخصات کاربر {}
createUser ایجاد کاربر جدید شناسه کاربر ایجاد شده number
updateUser بروزرسانی کاربر 1 number
deleteUser حذف کاربر 1 number
deleteUsers حذف چند کاربر 1 number
getUserRooms دریافت لیست اتاق‌های کاربر لیست اتاق‌ها []
addUserRooms افزودن به اتاق‌های کاربر 1 number
removeUserRooms حذف از اتاق‌های کاربر 1 number
createLoginUrl دریافت آدرس ورود مستقیم به اتاق بدون نیاز به لاگین و ساخت کاربر آدرس (URL) string

دریافت لیست کاربران موجود

درخواست:

{
  "action": "getUsers"
}

پاسخ:

{
  "ok": true,
  "result": [
    { "id": 1, "username": "parham", "nickname": "پرهام", "status": 1 },
    { "id": 2, "username": "sara", "nickname": "سارا", "status": 1 }
  ]
}

دریافت مشخصات یک کاربر با استفاده از شناسه

درخواست:

{
  "action": "getUser",
  "params": {
    "user_id": 1
  }
}

دریافت مشخصات یک کاربر با استفاده از نام کاربری

درخواست:

{
  "action": "getUser",
  "params": {
    "username": "parham"
  }
}

پاسخ:

{
  "ok": true,
  "result": {
    "id": 1,
    "username": "parham",
    "nickname": "پرهام",
    "email": "example@gmail.com",
    "fname": "پرهام",
    "lname": "عابدینی",
    "gender": 1,
    "status": 1,
    "is_public": false,
    "concurrent": 0,
    "time_limit": null,
    "time_usage": 426466,
    "time_total": 8464516,
    "expiry_date": null,
    "create_time": 1489021434,
    "update_time": 1489021434
  }
}

ایجاد کاربر جدید

درخواست:

{
  "action": "createUser",
  "params": {
    "username": "test-user",
    "password": "12345",
    "nickname": "کاربر عمومی",
    "status": 1,
    "is_public": true
  }
}

پاسخ:

{
  "ok": true,
  "result": 3
}

بروزرسانی کاربر

درخواست:

{
  "action": "updateUser",
  "params": {
    "user_id": 3,
    "password": "tu2017!"
  }
}

پاسخ:

{
  "ok": true,
  "result": 1
}

حذف کاربر

درخواست:

{
  "action": "deleteUser",
  "params": {
    "user_id": 3
  }
}

پاسخ:

{
  "ok": true,
  "result": 1
}

حذف چند کاربر

درخواست:

{
  "action": "deleteUsers",
  "params": {
    "users": [3, 4, 5]
  }
}

پاسخ:

{
  "ok": true,
  "result": {
    "success": 2,
    "failure": 1
  }
}

دریافت لیست اتاق‌های یک کاربر

درخواست:

{
  "action": "getUserRooms",
  "params": {
    "user_id": 1
  }
}

پاسخ:

{
  "ok": true,
  "result": [
    { "room_id": 1, "name": "meeting", "title": "اتاق جلسات", "access": 1 },
    { "room_id": 2, "name": "learning-php", "title": "کلاس آموزش PHP", "access": 2 }
  ]
}

افزودن به اتاق‌های یک کاربر

درخواست:

{
  "action": "addUserRooms",
  "params": {
    "user_id": 2,
    "rooms": [
      { "room_id": 1 },
      { "room_id": 2, "access": 2 }
    ]
  }
}

پاسخ:

{
  "ok": true,
  "result": 2
}

حذف از اتاق‌های یک کاربر

درخواست:

{
  "action": "removeUserRooms",
  "params": {
    "user_id": 2,
    "rooms": [1, 2]
  }
}

پاسخ:

{
  "ok": true,
  "result": 2
}

دریافت آدرس ورود مستقیم به اتاق بدون نیاز به لاگین و ساخت کاربر (createLoginUrl)

با این تابع می‌توان برای یک اتاق لینک ورود مستقیم ایجاد کرد تا کاربر بدون نیاز به درج نام کاربری و گذرواژه وارد اتاق شود. در این روش نیازی به ساخت کاربر و اعطای دسترسی نیست و کافی است شناسه اتاق و مشخصات لازم ارسال شود.

درخواست:

{
  "action": "createLoginUrl",
  "params": {
    "room_id": 1,
    "user_id": "sina",
    "nickname": "Sina",
    "access": 3,
    "concurrent": 1,
    "language": "en",
    "ttl": 3600
  }
}
  • room_id: شناسه اتاقی که می‌خواهید برای آن لینک ورود بسازید.
  • user_id (ضروری): عدد یا رشته (بدون فاصله). برای جلوگیری از ورود همزمان چند کاربر با لینک تولید شده.
  • concurrent: تعداد کاربرانی که می‌توانند همزمان با این لینک وارد اتاق شوند. اگر user_id خالی باشد، این پارامتر بی‌تأثیر است. مقدار پیش‌فرض 1.
  • ttl (Time To Live): مدت اعتبار لینک به ثانیه. پس از آن لینک نامعتبر می‌شود. مقدار پیش‌فرض 3600 (یک ساعت).

پاسخ:

{
  "ok": true,
  "result": "https://www.skyroom.online/ch/faramooz/meeting/t/eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJ0eXBlIjoiYXBpX2xvZ2luIiwiZXhwIjoxNjA1MDg2NTY2LCJyb29tX2lkIjoxLCJ1aWQiOiJAYXBpXC9ta2giLCJuaWNrbmFtZSI6Ik1vaHNlbiIsInJvbGUiOjMsImNvbmN1cnJlbnQiOjUsImdlbmRlciI6MH0.hGJyJvnDFSDMEXCt_q1zUru8INLcyH3UGH7kh4D2SAc/l/en"
}

کدهای مفید

وضعیت سرویس (status)

کد شرح
0 غیرفعال
1 فعال

وضعیت اتاق (status)

کد شرح
0 غیرفعال
1 فعال

وضعیت کاربر (status)

کد شرح
0 غیرفعال
1 فعال

جنسیت کاربر (gender)

کد شرح
0 نامعلوم
1 مرد
2 زن

دسترسی به اتاق (access)

کد شرح
1 کاربر عادی
2 ارایه کننده
3 اپراتور