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

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

معرفی

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

مشخصات فنی

وب‌سرویس اسکای‌روم بر پایه REST طراحی و پیاده‌سازی گردیده و در آن تلاش شده است تا ضمن الگوبرداری از استانداردهای رایج دنیا، سادگی در اولویت نخست باشد. از اینرو در وب‌سرویس اسکای‌روم تمامی درخواست(request)ها به شکل POST ارسال می گردند. فرمت داده‌های ارسالی (content-type) می‌تواند یکی از انواع JSON یا URL-Encoded باشد اما پاسخ همواره JSON خواهد بود. همچنین به منظور تفکیک خطاهای شبکه و سرور از خطاهای برنامه، تمامی پاسخ‌ها از سوی وب‌سرویس، چه موفق چه ناموفق، با کد وضعیت 200 برگردانده می شود (200 = HTTP Status Code).

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

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

ساختار آدرس(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"
    ]
  }
}

مدیریت خطاها

همانطور که پیشتر اشاره شد، تمامی پاسخ‌های دریافتی از سمت وب‌سرویس اعم از موفق یا ناموفق با کد وضعیت 200 ارسال می‌گردد. در نتیجه چنانچه مقدار این کد (با استفاده از خواندن HTTP Header) عددی غیر از 200 باشد نشان دهنده بروز خطای شبکه یا سرور بوده و لازم است تا به گونه‌ای مدیریت شود. اما در مورد خطاهای برنامه‌ای، پاسخ همواره به شکل زیر خواهد بود:

HTTP/1.1 200 OK
{
  "ok": false,
  "error_code": 14,
  "error_message": "درخواست شما با خطا روبرو شد."
}

بدین ترتیب چنانچه عملیات ناموفق باشد دو مقدار error_code و error_message برگردانده می‌شود که به ترتیب بیانگر کد خطا و توضیح خطا می‌باشند.

کد خطاهای عمومی به قرار زیر است:

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


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

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

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

شما در اسکای‌روم سرویس خود را بر اساس مولفه‌هایی همچون تعداد کاربر همزمان، تعداد ویدیوی همزمان در هر اتاق، حجم نفرساعت مصرفی و همچنین بازه زمانی بهره‌برداری از سرویس خریداری می‌کنید. برای ساخت اتاق‌های مجازی، وجود حداقل یک سرویس فعال الزامی است. چناچه بیش از یک سرویس فعال داشته باشید می‌بایست به هنگام ایجاد اتاق، شناسه سرویس مربوطه را نیز مشخص نمایید در غیر این صورت نیازی به ارسال شناسه سرویس نیست و به طور پیش‌فرض، اتاق‌ها بر روی سرویس فعال شما ساخته می‌شوند. ضمن اینکه می‌توانید با استفاده از تابع 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
}

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

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

مشخصات کاربر

ویژگی نوع مقدار
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
}

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

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

درخواست:
{
  "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 خالی باشد این پارامتر بی‌تاثیر خواهد بود. مقدار پیش‌فرض برای concurrent عدد 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 اپراتور