راهنمای استفاده از API پلتفرم ویدیو ابر آروان

ساختار کلی سرویس 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}