استفاده از API پلتفرم میزبانی ویدیو ابر آروان
برای کار با پلتفرم میزبانی ویدیو ابر آروان، می‌توانید از دو روش استفاده از پنل کاربری ابر آروان یا استفاده از API ابر آروان بهره ببرید. در حالی که روش اول برای کاربران نهایی مناسب‌تر است، امکانات و دسترسی‌های API میزبانی ویدیو ابر آروان ابزاری قدرتمند را برای توسعه‌دهندگان فراهم می‌کند.
در این راهنمای فنی، به معرفی API پلتفرم ویدیو ابر آروان و شیوه‌ی کار با آن می‌پردازیم. هم‌چنین، می‌توانید اطلاعات بیش‌تر درباره‌ی این ابزار را در بخش مستندات API پلتفرم میزبانی ویدیو ابر آروان مشاهده کنید.
آغاز کار با API
برای آغاز کار با API ابر آروان، داشتن کلید API یا API Key الزامی است. این کار به‌سادگی و از طریق پنل کاربری ابر آروان امکان‌پذیر است. برای اطلاع از شیوه‌ی ساخت API Key، می‌توانید از راهنمای ایجاد کلید API استفاده کنید.
پس از ایجاد API Key و برای تست API ویدیو ابر آروان، می‌توانید از ابزارهای Postman یا Insomnia استفاده کنید. به این منظور و بعد از دریافت یکی از این دو ابزار، ابتدا باید فایل postman-collection را در یکی از این دو برنامه‌ی نصب شده Import و سپس API Key دریافتی از پنل کاربری ابر آروان را در قسمت Edit Collection، بخش Variables وارد کنید.
برای در دسترس قرار گرفتن سرویس میزبانی ویدیو، نخست باید Subdomain انتخابی با استفاده از درخواست Post ایجاد شود. برای این‌کار از دستور زیر استفاده کنید.
POST /domain
Parameters
Subdomain required
نکته‌ی مهم آن است که این درخواست، فقط یک بار قابل اجرا است و امکان تغییر دامنه‌ی انتخابی وجود ندارد.
مشاهده دامنه
برای مشاهده‌ی دامنه‌ی اختصاص یافته، کافی است از متد زیر استفاده کنید.
GET /domain
مدیریت کانال‌ها
برای آپلود فایل‌های صوتی و تصویری در سرورهای میزبانی ویدیوی ابر آروان، نخست نیاز است که دست کم یک کانال ایجاد شود. کلیه‌ی فایل‌هایی که در پلتفرم ویدیوی ابر آروان مورد استفاده قرار می‌گیرند، مانند فایل‌های ویدیو، فایل‌های صوتی، واترمارک و پروفایل، درون یک کانال قرار می‌گیرند.
ساخت کانال
با استفاده از دستور زیر می‌توانید از طریق API ابر آروان یک کانال ایجاد کنید.
POST /channels
Parameters
Title (string) required
Description (string) required
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 را می‌دهد. برای اطلاع دقیق‌تر درباره‌ی این پروتکل و آشنایی با شیوه‌ی کار با آن، راهنمای بارگذاری Resumable فایل‌ها با پروتکل TUS را مطالعه کنید.
پیش از شروع ارسال فایل به سرور، نخست باید بر اساس حجم فایل که از قسمت مشاهده‌ی اطلاعات فایل در دسترس است، یک فضای خالی ایجاد شود. فرض کنید یک فایل 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) required
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) required
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}
