ساختار کلی سرویس VOD ابر آروان و مراحل انجام کار در آن در شکل زیر آمده است.
برای استفاده از سرویس VOD ابر آروان دو روش وجود دارد:
- استفاده از پنل کاربری ابر آروان برای کاربران عادی
- استفاده از API برای برنامه‌نویسان و توسعه‌دهندگان
معماری APIهای سرویس ویدیو ابر آروان REST است که شامل چند گروه به‌شکل زیر است:
- کانال (Channel)
- فایل‌های موقت (File)
- پروفایل (Profile)
- گزارش‌ها (Analytics)
- زیرنویس (Subtitle)
- دامنه (Domain)
- ویدیو (Video)
- واترمارک (Watermark)
طبق شکلی که در ابتدای مطلب دیدیم، برای استفاده از API هر قسمت باید یک پیش‌نیاز رعایت شده باشد، برای نمونه نخستین مرحله ساخت دامنه است که در نخستین ورود به پنل ساخته می‌شود و پس از آن امکان استفاده از APIهای Analytics – Channel وجود دارد.
- برای استفاده از APIهای Watermark – Profile – File – Video در ابتدا باید یک کانال ساخته باشید.
- برای استفاده از APIهای Subtitle در ابتدا باید یک ویدیو ساخته باشید.
شیوه‌ی استفاده از تمامی APIها واضح است و فقط APIهای مربوط به File توضیح داده می‌شوند.
API Key
نخستین مرحله برای استفاده از API، احراز هویت به سامانه است. برای این کار لازم است API Key خود را به‌منظور هویت‌سنجی در قسمت «Authorize» وارد کنید. چنان‌چه اطلاعی از API Key خود ندارید، می‌توانید به صفحه‌ی چگونه API Key یا کلید دسترسی برنامه‌نویسی بسازید؟ بروید.
پس از ایجاد API Key و برای تست API ویدیو ابر آروان، می‌توانید از ابزارهای Postman یا Insomnia استفاده کنید. به این منظور و بعد از دریافت یکی از این دو ابزار، ابتدا باید فایل postman-collection را در یکی از این دو برنامه‌ی نصب شده Import و سپس API Key دریافتی از پنل کاربری ابر آروان را در قسمت Edit Collection، بخش Variables وارد کنید.
برای در دسترس قرار گرفتن سرویس میزبانی ویدیو، نخست باید Subdomain انتخابی با استفاده از درخواست Post ایجاد شود. برای این‌کار از دستور زیر استفاده کنید.
POST /domain Parameters Subdomain required
نکته‌ی مهم آن است که این درخواست، فقط یک بار قابل اجرا است و امکان تغییر دامنه‌ی انتخابی وجود ندارد.
فایل (File)
سرویس VOD آروان برای آپلود فایل از پروتکل Tus استفاده می‌کند که قابلیت‌هایی مانند Resume را برای آپلود فایل‌ها فراهم می‌کند. راحت‌ترین روش استفاده از این پروتکل و پیشنهاد آروان استفاده از کتابخانه‌های آماده Tus است که برای زبان‌های مختلف و به‌شکل اوپن سورس ارایه می‌شود.
اما اگر قصد استفاده از کتابخانه‌های آماده را ندارید و می‌خواهید این قسمت را خودتان انجام دهید (آروان این کار را پیشنهاد نمی‌کند و مسوولیتی در قبال درست بودن پیاده‌سازی با این شیوه نخواهد داشت)، در این حالت باید تسلط کامل بر پروتکل Tus داشته باشید. در این‌جا برای نمونه توضیح کوتاه و مختصری از شیوه‌ی آپلود یک فایل داده می‌شود.
- Post
برای آغاز آپلود باید متد Post را صدا بزنید و سه مورد را در Header آن ارسال کنید.
-
- tus-resumable: ورژن tus که اکنون می‌توانید از نسخه‌ی 1.0.0 استفاده کنید.
- upload-length: سایز فایل ارسالی برمبنای Byte.
- upload-metadata: این قسمت شامل ترکیبی از filename وfiletype است که برای شیوه‌ی تولید آن می‌توانید به این لینک بروید. برای نمونه metadata ویدیویی به نام test.mp4 به‌شکل زیر است:
Base64(test.mp4) ⇒ dGVzdC5tcDQ=
Base64(video/mp4) ⇒ dmlkZW8vbXA0
metadata ⇒ filename dGVzdC5tcDQ=,filetype dmlkZW8vbXA0
با موفقیت‌آمیز بودن این مرحله، کد ۲۰۱ برگردانده می‌شود و Location فایل ایجاد شده در Response Header برگردانده می‌شود که برای مراحل بعدی استفاده می شود و فایل به این آدرس ارسال می شود.
- Patch
در این مرحله قسمتی از فایل که مورد نظرتان هست را در Payload و دو مورد زیر را در Header قرار می‌دهید و به آدرسی (Location) که در مرحله قبل بدست آوردید ارسال می کنید.
-
- tus-resumable: ورژن tus که اکنون می‌توانید از نسخه‌ی 1.0.0 استفاده کنید.
- upload-offset: در نخستین ریکویست مقدار آن صفر است اما در ریکویست‌های بعدی میزان Byte ارسال شده به سرور تا این لحظه است.
با موفقیت‌آمیز بودن این ریکویست کد ۲۰۴ و مقدار Upload-Offset که در واقع طول Payload ارسالی به سرور برمبنای بایت است در Response Header برگردانده می‌شود که برای ریکویست‌های بعدی لازم است.
هر زمان که مقدار Upload-Offset که در Response Header برگردانده می‌شود با مقدار upload-length برابر شد، می‌توانیم متوجه شویم که تمام فایل به سرور ارسال شده است.
راحت‌ترین راه (نه بهترین) استفاده از این قسمت ارسال فایل به‌شکل یک‌جاست، یعنی در نخستین ریکویست ارسالی تمامی فایل را در Payload قرار داده و ارسال کنیم، در فایل‌هایی با سایز بالا ممکن است به‌دلیل موقعیت‌هایی مانند قطع و وصل شدن اینترنت، ناپایدار بودن اینترنت و مواردی از این دست، فایل به‌درستی ارسال نشود و نیاز به انجام دوباره‌ی این مرحله باشد.
نمونه درخواست‌های API
مشاهده دامنه
برای مشاهده‌ی دامنه‌ی اختصاص یافته، کافی است از متد زیر استفاده کنید.
GET /domain
مدیریت کانال‌ها
برای آپلود فایل‌های صوتی و تصویری در سرورهای میزبانی ویدیوی ابر آروان، نخست نیاز است که دست کم یک کانال ایجاد شود. کلیه‌ی فایل‌هایی که در پلتفرم ویدیوی ابر آروان مورد استفاده قرار می‌گیرند، مانند فایل‌های ویدیو، فایل‌های صوتی، واترمارک و پروفایل، درون یک کانال قرار می‌گیرند.
ساخت کانال
با استفاده از دستور زیر می‌توانید از طریق API ابر آروان یک کانال ایجاد کنید.
POST /channels Parameters Title (string) required Description (string) Secure_link_enabled (boolean) Secure_link_enabled (string) required if “secure_link_enabled” is true
مشاهده تمام کانال‌ها
از طریق API سرویس میزبانی ویدیو ابر آروان، می‌توانید لیست کانال‌های موجود روی حساب کاربری خود را مشاهده کنید. به این منظور، می‌توانید از متد زیر استفاده کنید.
GET /channels
آپدیت کانال
برای آپدیت یک کانال مانند ساخت آن، باید قسمت Body فرستاده شود و هم‌چنین باید در URL، مقدار Channel ID نیز عنوان شود.
PATCH /channels/{channel_id}
مشاهده یک کانال خاص
برای مشاهده‌ی اطلاعات مربوط به یک کانال خاص، می‌توان از این Route استفاده کرد.
GET /channels/{channel_id}
حذف کانال
متد زیر به شما امکان حذف کامل یک کانال را می‌دهد.
DELETE /channels/{channel_id}
باید توجه داشت که بعد از حذف یک کانال، تمامی فایل‌های قرار گرفته روی آن، شامل تمام فایل‌های صوتی، تصویری، واترمارک‌ها و پروفایل‌های ساخته شده حذف می‌شوند.
آپلود فایل
اصلی‌ترین مفهوم که پیش از آغاز فایل باید از آن مطلع باشید، پروتکل TUS است. این پروتکل متن‌باز به شما امکان آپلود به‌شکل Resumable را می‌دهد. پیش از شروع ارسال فایل به سرور، نخست باید بر اساس حجم فایل که از قسمت مشاهده‌ی اطلاعات فایل در دسترس است، یک فضای خالی ایجاد شود. فرض کنید یک فایل mp4 با نام video.mp4 با حجم 6.8 MB (یا 6777592 بایت) وجود دارد، ابتدا از قسمت Properties حجم فایل کپی می‌شود.
POST /channels/{channel_id}/files
Headers
tus-resumable: 1.0.0
upload_length: 6777592
upload-metadata: filename dmlkZW8ubXA0,filetype dmlkZW8vbXA0
سپس ID فضای ایجاد شده از قسمت Response Header کپی و با استفاده از PATH Request، فایل به سمت سرور ارسال می‌شود (ID فایل و کانال در URL قرار می‌گیرند).
POST /channels/{channel_id}/videos
Parameters
Title (string) required
Description (string)
Video_url (should be a valid URL. Otherwise, this will be corrupted)
File_id (should be string and it will be required whenever video_url is not available) required
Convert_mode (could be auto or manual or profile)
Profile_id (required if convert mode has set to profile)
Parallel_convert (boolean) required
Thumbnail_time (numeric) required
Convert_info (must be an array and this will be required if convert mode has set to manual)
[
{
“audio_bitrate”: 0,
“video_bitrate”: 0,
“resolution”: “string”,
}
]
Watermark_id
Watermark_area (should be one of: center, fix_top_left, fix_top_right, fix_top_center, fix_bottom_left, fix_bottom_right, fix_bottom_center, animate_left_to_right, animate_top_to_bottom)
اگر فایل صوتی یا تصویری با URL در دسترس است، بدون در نظر گرفتن مراحل قبل، می‌توان URL فایل را به‌شکل مستقیم در video_url / audio_url وارد کرد. هم‌چنین، اگر مقادیر Bitrate و Resolution ثابت است، بهتر است از پروفایل استفاده شود تا هنگام تبدیل فایل، تنها به Profile_id نیاز باشد.
برای قرار دادن یک تصویر روی ویدیو، نخست باید Watermark ایجاد و ID آن هنگام ارسال فایل وارد شود. برای تبدیل همزمان فایل‌ها، باید مقدار parallel_convert را true ارسال کرد. در حالت معمول تمامی فایل‌ها Queue می‌شوند، در صف تبدیل قرار می‌گیرند و تک‌تک تبدیل می‌شوند. با انتخاب parallel_convert تا تعداد ۳ فایل را می‌توان به‌شکل همزمان تبدیل کرد و باید توجه داشت که بابت تبدیل همزمان هر فایل هزینه‌ای برای کاربر لحاظ خواهد شد.
وضعیت تبدیل
بعد از ارسال فایل برای تبدیل، برای در دسترس قرار گرفتن فایل باید گام‌هایی پیموده شوند. نخست، برای مشخص شدن وضعیت فایل باید از GET Request استفاده کرد. مقدار Status در Response نمایان‌گر وضعیت فعلی است.
GET/videos/{video_id}
تمامی ویدیوهای یک کانال را می‌توان با Route زیر مشاهده کرد.
GET/channels/{channel_id}/videos
هم‌چنین، عنوان و توضیحات را می‌توان با Route زیر آپدیت کرد.
PATCH/videos/{video_id}
Parameters
Title (string) required
Description (string)
زیرنویس‌ها
برای یک ویدیو می‌توان چندین زیرنویس آپلود کرد. اضافه کردن زیرنویس باید با درخواست POST انجام شود. در حال حاضر تنها فرمت‌های SRT و VTT برای فایل زیرنویس معتبر هستند.
POST /videos/{video_id}/subtitles
Parameters
subtitle (file) required
lang (string) required
مشاهده تمام زیرنویس‌های یک ویدیو
GET/videos/{video_id}/subtitles
مشاهده زیرنویس یک ویدیوی خاص
GET/subtitles/{subtitles_id}
حذف زیرنویس
DELETE/subtitles/{subtitle_id}
اضافه کردن واترمارک
تصاویر مختلفی می‌توانند در هر کانال به‌شکل جداگانه ذخیره شوند که در زمان تبدیل فایل ویدیویی، به‌عنوان واترمارک روی آن‌ها قرار بگیرند. برای انتخاب واترمارک، کافی است ID تصویر موردنظر را انتخاب کرد.
POST /channels/{channel_id}/watermarks
Parameters
title (string) required
description (string)
watermark (file) required
به‌روزرسانی واترمارک
به کمک ID هر واترمارک، می‌توان آن را به‌راحتی به‌روزرسانی کرد.
POST / watermarks /{ watermark _id}
Parameters
title (string) required
description (string)
مشاهده همه واترمارک‌های یک کانال
GET/channels/{channel_id}/watermarks
مشاهده یک واترمارک
GET/watermarks/{watermark_id}
حذف زیرنویس
DELETE/watermarks/{watermark_id}
مدیریت پروفایل‌ها
برای آن‌که در هربار تبدیل ویدیو یا فایل صوتی نیاز به وارد کردن تنظیمات تبدیل فایل به‌شکل دستی نباشد، می‌توان یک پروفایل ساخت تا با انتخاب آن، تبدیل فایل با توجه به تنظیمات پروفایل انجام شود. هر کانال می‌تواند چندین پروفایل داشته باشد.
POST /channels/{channel_id}/profiles
Parameters
Title (string) required
Description (string)
convert_mode ("auto", “manual”) required
thumbnail_time (number)
watermark_id (string)
Watermark_area (should be one of: center, fix_top_left, fix_top_right, fix_top_center, fix_bottom_left, fix_bottom_right, fix_bottom_center, animate_left_to_right, animate_top_to_bottom)
Convert_info (must be an array and this will be required if convert mode has set to manual)
[
{
“audio_bitrate”: 0,
“video_bitrate”: 0,
“resolution”: “string”,
}
]
آپدیت پروفایل
PATCH /profiles/{profile_id}
Parameters
Title (string) required
Description (string)
convert_mode ("auto", “manual”) required
thumbnail_time (number)
watermark_id (string)
Watermark_area (should be one of: center, fix_top_left, fix_top_right, fix_top_center, fix_bottom_left, fix_bottom_right, fix_bottom_center, animate_left_to_right, animate_top_to_bottom)
Convert_info (must be an array and this will be required if convert mode has set to manual)
[
{
“audio_bitrate”: 0,
“video_bitrate”: 0,
“resolution”: “string”,
}
]
مشاهده تمام پروفایل‌های یک کانال
GET/channels/{channel_id}/profiles
مشاهده یک پروفایل
GET/profiles/{profile_id}
حذف پروفایل
DELETE/profiles/{profile_id}