بارگذاری‌های ازسرگرفتنی

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

استفاده از بارگذاری‌های قابل‌ازسرگیری به‌ویژه در هریک از موارد زیر مفید است:

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

این راهنما توالی درخواست‌های HTTP را که یک برنامه برای بارگذاری ویدیوها بااستفاده از فرایند بارگذاری ازسرگرفتنی انجام می‌دهد، توضیح می‌دهد. این راهنما در درجه اول برای توسعه‌دهندگانی است که نمی‌توانند از کتابخانه‌های کارخواه Google API استفاده کنند، برخی‌از این کتابخانه‌ها پشتیبانی بومی برای بارگذاری‌های ازسرگرفتنی ارائه می‌دهند. درواقع، راهنمای YouTube Data API - بارگذاری ویدیو توضیح می‌دهد که چگونه از کتابخانه کارخواه Google APIs برای Python برای بارگذاری ویدیو بااستفاده از فرایند بارگذاری قابل‌ازسرگیری استفاده کنید.

توجه: همچنین می‌توانید بااستفاده از یکی از کتابخانه‌های کارخواه Google API با گزارش‌گیری HTTPS فعال، مجموعه درخواست‌های انجام‌شده برای بارگذاری قابل‌ازسرگیری یا هر عملیات API دیگری را ببینید. برای مثال، برای فعال کردن ردیابی HTTP برای Python، از کتابخانه httplib2 استفاده کنید:

httplib2.debuglevel = 4

مرحله ۱ - شروع جلسه ازسرگرفتنی

برای شروع بارگذاری ویدیو قابل‌ازسرگیری، درخواست POST را به نشانی وب زیر ارسال کنید. در نشانی وب، مقدار پارامتر part را روی مقدار مناسب برای درخواستتان تنظیم کنید. به‌یاد داشته باشید که مقدار پارامتر بخش‌هایی را که حاوی ویژگی‌هایی هستند که تنظیم می‌کنید شناسایی می‌کند و همچنین بخش‌هایی را که می‌خواهید پاسخ میانای برنامه‌سازی کاربردی شامل شود شناسایی می‌کند. مقادیر پارامتر در نشانی وب درخواست باید URL-encoded باشد.

https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&part=PARTS

بدنه درخواست را روی منبع video تنظیم کنید. همچنین، سرصفحه‌های درخواست HTTP زیر را تنظیم کنید:

• Authorization – کد مجوز برای درخواست.
• Content-Length – تعداد بایت‌های ارائه‌شده در بدنه درخواست. توجه داشته باشید که اگر از کدبندی انتقال تکه‌ای استفاده می‌کنید، نیازی به ارائه این سرصفحه ندارید.
• Content-Type – مقدار را روی application/json; charset=UTF-8 تنظیم کنید.
• X-Upload-Content-Length – تعداد بایت‌هایی که در درخواست‌های بعدی بارگذاری خواهد شد. این مقدار را روی اندازه فایلی که بارگذاری می‌کنید تنظیم کنید.
• x-upload-content-type – نوع MIME فایلی که بارگذاری می‌کنید. می‌توانید فایل‌هایی با هر نوع MIME ویدیویی (video/*) یا نوع MIME‏ application/octet-stream بارگذاری کنید.

مثال زیر نشان می‌دهد که چگونه یک جلسه قابل ازسرگیری برای بارگذاری ویدیو آغاز می‌شود. درخواست ویژگی‌ها را در بخش‌های snippet و status منبع video تنظیم (و بازیابی) می‌کند و همچنین ویژگی‌ها را در بخش contentdetails منبع بازیابی می‌کند.

post /upload/youtube/v3/videos?uploadType=resumable&part=parts http/1.1
host: www.googleapis.com
authorization: bearer auth_token
content-length: content_length
content-type: application/json; charset=utf-8
x-upload-content-length: x_upload_content_length
X-Upload-Content-Type: X_UPLOAD_CONTENT_TYPE

video resource

مثال زیر درخواست POST را نشان می‌دهد که همه این مقادیر به‌جز کد اصالت‌سنجی در آن درج شده است. مقدار categoryId در مثال با دسته ویدیو مطابقت دارد. فهرست دسته‌های پشتیبانی‌شده را می‌توان بااستفاده از روش videoCategories.list در API بازیابی کرد.

POST /upload/youtube/v3/videos?uploadType=resumable&part=snippet,status,contentDetails HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer AUTH_TOKEN
Content-Length: 278
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Length: 3000000
X-Upload-Content-Type: video/*

{
  "snippet": {
    "title": "My video title",
    "description": "This is a description of my video",
    "tags": ["cool", "video", "more keywords"],
    "categoryId": 22
  },
  "status": {
    "privacyStatus": "public",
    "embeddable": True,
    "license": "youtube"
  }
}

مرحله ۲ - ذخیره کردن URI جلسه ازسرگرفتنی

اگر درخواستتان موفقیت‌آمیز باشد، سرور میانای برنامه‌سازی کاربردی با رمز وضعیت HTTP 200 (OK) پاسخ خواهد داد و پاسخ شامل سرصفحه HTTP Location خواهد بود که URI را برای جلسه ازسرگرفتنی مشخص می‌کند. این همان URI است که برای بارگذاری فایل ویدیویی خود استفاده خواهید کرد.

مثال زیر یک پاسخ نمونه API به درخواست در مرحله ۱ را نشان می‌دهد:

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/youtube/v3/videos?uploadType=resumable&upload_id=xa298sd_f&part=snippet,status,contentDetails
Content-Length: 0

مرحله ۳ - بارگذاری فایل ویدیو

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

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: CONTENT_LENGTH
Content-Type: CONTENT_TYPE

BINARY_FILE_DATA

درخواست، سرصفحه‌های درخواست اچ‌تی‌تی‌پی زیر را تنظیم می‌کند:

• ‫Authorization – کد مجوز برای درخواست.
• Content-Length – اندازه فایلی که بارگذاری می‌کنید. این مقدار باید با مقدار سرایند درخواست اچ‌تی‌تی‌پی X-Upload-Content-Length در مرحله ۱ یکسان باشد.
• Content-Type – نوع MIME فایلی که بارگذاری می‌کنید. این مقدار باید با مقدار سرایند درخواست اچ‌تی‌تی‌پی X-Upload-Content-Type در مرحله ۱ یکسان باشد.

مرحله ۴ - تکمیل فرایند بارگذاری

درخواست شما به یکی از سناریوهای زیر منجر خواهد شد:

• بارگذاری شما موفقیت‌آمیز بود.

  سرور API با کد پاسخ HTTP 201 (Created) پاسخ می‌دهد. بدنه پاسخ منبع video است که ایجاد کرده‌اید.

• بارگذاری شما موفقیت‌آمیز نبود، اما می‌توانید آن را ازسر بگیرید.

  در هریک از موارد زیر باید بتوانید بارگذاری را ازسر بگیرید:

  • درخواست شما قطع شد زیرا اتصال بین برنامه شما و سرور میانای برنامه‌سازی کاربردی قطع شده است. در این مورد، پاسخ API دریافت نخواهید کرد.

  • پاسخ میانای برنامه‌سازی کاربردی یکی از کدهای پاسخ 5xx زیر را مشخص می‌کند. کد شما باید از استراتژی عقب‌نشینی نمایی هنگام ازسرگیری بارگذاری‌ها پس‌از دریافت هریک از این کدهای پاسخ استفاده کند.

    • 500 – Internal Server Error
    • 502 – Bad Gateway
    • 503 – Service Unavailable
    • 504 – Gateway Timeout

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

• بارگذاری شما برای همیشه ناموفق بود.

  برای بارگذاری ناموفق، پاسخ حاوی یک پاسخ خطا است که به توضیح علت عدم موفقیت کمک می‌کند. برای بارگذاری‌ای که به‌طور دائم ناموفق است، پاسخ میانای برنامه‌سازی کاربردی دارای کد پاسخ 4xx یا کد پاسخ 5xx غیراز موارد فهرست‌شده در بالا خواهد بود.

  اگر درخواستی را با URI جلسه منقضی‌شده ارسال کنید، سرور کد پاسخ HTTP 404 (Not Found) را برمی‌گرداند. در این حالت، باید بارگذاری ازسرگرفتنی جدیدی را شروع کنید، URI جلسه جدیدی دریافت کنید، و بارگذاری را از ابتدا بااستفاده از URI جدید شروع کنید.

مرحله ۴.۱: بررسی وضعیت بارگذاری

برای بررسی وضعیت بارگذاری ازسرگرفتنی قطع‌شده، درخواست PUT خالی به نشانی وب بارگذاری که در مرحله ۲ بازیابی کردید و در مرحله ۳ نیز استفاده کردید ارسال کنید. در درخواستتان، مقدار سرایند Content-Range را روی bytes */CONTENT_LENGTH تنظیم کنید، که در آن CONTENT_LENGTH اندازه فایلی است که بارگذاری می‌کنید.

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: 0
Content-Range: bytes */CONTENT_LENGTH

مرحله ۴.۲: پردازش پاسخ API

اگر بارگذاری قبلاً تکمیل شده باشد، صرف‌نظر از اینکه موفقیت‌آمیز بوده یا ناموفق، API همان پاسخی را برمی‌گرداند که هنگام تکمیل بارگذاری اصلی ارسال کرده بود.

بااین‌حال، اگر بارگذاری قطع شده باشد یا هنوز درحال انجام باشد، پاسخ میانای برنامه‌سازی کاربردی دارای کد پاسخ HTTP 308 (Resume Incomplete) خواهد بود. در پاسخ، سرایند Range مشخص می‌کند که چند بایت از فایل قبلاً باموفقیت بارگذاری شده است.

• مقدار سرایند از 0 نمایه شده است. به‌این‌ترتیب، مقدار سرصفحه 0-999999 نشان می‌دهد که 1,000,000 بایت اول فایل بارگذاری شده است.
• اگر هنوز چیزی بارگذاری نشده باشد، پاسخ میانای برنامه‌سازی کاربردی شامل سرایند Range نخواهد بود.

نمونه پاسخ زیر قالب پاسخ میانای برنامه‌سازی کاربردی را برای بارگذاری ازسرگرفتنی نشان می‌دهد:

308 Resume Incomplete
Content-Length: 0
Range: bytes=0-999999

اگر پاسخ API شامل سرصفحه Retry-After نیز باشد، از مقدار آن سرصفحه برای تعیین زمان تلاش برای ازسرگیری بارگذاری استفاده کنید.

مرحله ۴.۳: ازسرگیری بارگذاری

برای ازسرگیری بارگذاری، درخواست PUT دیگری به نشانی وب بارگذاری ضبط‌شده در مرحله ۲ ارسال کنید. بدنه درخواست را روی کد باینری برای بخشی از فایل ویدیویی که هنوز بارگذاری نشده است تنظیم کنید.

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: REMAINING_CONTENT_LENGTH
Content-Range: bytes FIRST_BYTE-LAST_BYTE/TOTAL_CONTENT_LENGTH

PARTIAL_BINARY_FILE_DATA

باید سرصفحه‌های درخواست اچ‌تی‌تی‌پی زیر را تنظیم کنید:

• ‫Authorization – کد مجوز برای درخواست.

• Content-Length – اندازه محتوایی که هنوز بارگذاری نشده است، برحسب بایت. اگر درحال بارگذاری باقی‌مانده فایل هستید، می‌توانید این مقدار را با کم کردن مقدار FIRST_BYTE از مقدار TOTAL_CONTENT_LENGTH محاسبه کنید. هر دو مقدار در سرصفحه Content-Range استفاده می‌شود.

• Content-Range – بخشی از فایل که درحال بارگذاری آن هستید. مقدار سرایند شامل سه مقدار است:

  • FIRST_BYTE – نمایه عددی مبتنی بر ۰ شماره بایتی که بارگذاری را از آن ازسر می‌گیرید. این مقدار یک عدد بالاتر از عدد دوم در سرصفحه Range است که در مرحله قبل بازیابی شده است. در مثال قبلی، مقدار سرصفحه Range برابر با 0-999999 بود، بنابراین اولین بایت در بارگذاری ازسرگرفته‌شده بعدی 1000000 خواهد بود.

  • LAST_BYTE – نمایه عددی مبتنی بر ۰ آخرین بایت فایل باینری که درحال بارگذاری آن هستید. معمولاً این آخرین بایت در فایل است. بنابراین، برای مثال، اگر اندازه فایل 3000000 بایت باشد، آخرین بایت در فایل شماره 2999999 خواهد بود.

  • TOTAL_CONTENT_LENGTH – اندازه کل فایل ویدیو به بایت. این مقدار همان سرصفحه Content-Length است که در درخواست بارگذاری اصلی مشخص شده است.

  توجه: نمی‌توانید یک بلوک غیرپیوسته از فایل باینری را بارگذاری کنید. اگر سعی کنید یک بلوک غیرپیوسته را بارگذاری کنید، هیچ‌یک از محتوای باقیمانده باینری بارگذاری نخواهد شد.
  
  به‌همین دلیل، اولین بایت بارگذاری‌شده در یک بارگذاری ازسرگرفته‌شده باید بایت بعدی پس‌از آخرین بایتی باشد که قبلاً با موفقیت در YouTube بارگذاری شده است. (بحث مربوط به سرصفحه Range را در مرحله ۴.۲ ببینید.
  
  بنابراین، اگر آخرین بایت در سرصفحه Range برابر با 999999 باشد، اولین بایت در درخواست ازسرگیری بارگذاری باید بایت ۱۰۰۰۰۰۰ باشد. (هر دو عدد از نمایه مبتنی بر ۰ استفاده می‌کنند.) اگر بخواهید بارگذاری را از بایت ۹۹۹۹۹۹ یا کمتر (بایت‌های هم‌پوشان) یا بایت ۱۰۰۰۰۰۱ یا بیشتر (بایت‌های نادیده‌گرفته‌شده) ازسر بگیرید، هیچ‌کدام از محتواهای دودویی بارگذاری نخواهد شد.

بارگذاری فایل به‌صورت تکه‌ای

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

دستورالعمل‌های بارگذاری فایل به‌صورت تکه‌ای تقریباً مشابه فرایند چهار مرحله‌ای است که قبلاً در این راهنما توضیح داده شده است. بااین‌حال، درخواست‌های شروع بارگذاری فایل (مرحله ۳ بالا) و ازسرگیری بارگذاری (مرحله ۴.۳ بالا) هر دو مقدار سرصفحه Content-Length و Content-Range را به‌طور متفاوتی تنظیم می‌کنند زمانی که فایل به‌صورت تکه‌ای بارگذاری می‌شود.

• مقدار سرصفحه Content-Length اندازه تکه‌ای را که درخواست ارسال می‌کند مشخص می‌کند. به محدودیت‌های زیر درباره اندازه تکه‌ها توجه کنید:

  • اندازه تکه باید مضربی از ۲۵۶ کیلوبایت باشد. (این محدودیت برای آخرین تکه اعمال نمی‌شود زیرا اندازه کل فایل ممکن است مضربی از ۲۵۶ کیلوبایت نباشد.) به‌یاد داشته باشید که تکه‌های بزرگ‌تر کارآمدتر هستند.

  • اندازه تکه باید برای هر درخواست در توالی بارگذاری یکسان باشد، به‌استثنای آخرین درخواست که اندازه تکه نهایی را مشخص می‌کند.

• سرصفحه Content-Range بایت‌های موجود در فایلی را که درخواست درحال بارگذاری آن است مشخص می‌کند. دستورالعمل‌های تنظیم سرصفحه Content-Range در مرحله ۴.۳ هنگام تنظیم این مقدار قابل‌اجرا است.

  برای مثال، مقدار bytes 0-524287/2000000 نشان می‌دهد که درخواست درحال ارسال ۵۲۴٬۲۸۸ بایت اول (۲۵۶ × ۲۰۴۸) در یک فایل ۲٬۰۰۰٬۰۰۰ بایتی است.

مثال زیر قالب اولین درخواست از مجموعه‌ای از درخواست‌ها را نشان می‌دهد که یک فایل ۲٬۰۰۰٬۰۰۰ بایتی را به‌صورت تکه‌تکه بارگذاری می‌کند:

PUT UPLOAD_URL HTTP/1.1
Authorization: Bearer AUTH_TOKEN
Content-Length: 524888
Content-Type: video/*
Content-Range: bytes 0-524287/2000000

{bytes 0-524287}

اگر درخواستی غیراز درخواست نهایی موفقیت‌آمیز باشد، سرور API با پاسخ 308 (Resume Incomplete) پاسخ می‌دهد. قالب پاسخ همان قالبی خواهد بود که در مرحله ۴.۲: پردازش پاسخ میانای برنامه‌سازی کاربردی در بالا شرح داده شده است.

از مقدار بالایی که در سرصفحه Range پاسخ میانای برنامه‌سازی کاربردی برگردانده شده است برای تعیین محل شروع تکه بعدی استفاده کنید. همان‌طور که در مرحله ۴.۳: ازسر گرفتن بارگذاری توضیح داده شده است، برای بارگذاری تکه‌های فایل بعدی تا زمانی که کل فایل بارگذاری شود، به ارسال PUT درخواست ادامه دهید.

وقتی کل فایل بارگذاری شد، سرور با کد پاسخ HTTP 201 (Created) پاسخ می‌دهد و بخش‌های درخواست‌شده از منبع ویدیویی جدیداً ایجادشده را برمی‌گرداند.

اگر هر درخواستی قطع شد یا برنامه شما کد پاسخ 5xx دریافت کرد، برای تکمیل بارگذاری، روش توضیح‌داده‌شده در مرحله ۴ را دنبال کنید. اما به‌جای تلاش برای بارگذاری بقیه فایل، فقط بارگذاری بخش‌ها را از نقطه‌ای که بارگذاری را ازسر می‌گیرید ادامه دهید. حتماً وضعیت بارگذاری را بررسی کنید تا مشخص شود بارگذاری فایل را از کجا ازسر بگیرید. فرض نکنید که سرور همه (یا هیچ‌کدام از) بایت‌های ارسال‌شده در درخواست قبلی را دریافت کرده است.

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