آپلودهای قابل ازسرگیری

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

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

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

این راهنما توالی درخواست‌های HTTP را توضیح می‌دهد که یک برنامه کاربردی برای آپلود ویدیوها با استفاده از یک فرآیند آپلود قابل ازسرگیری انجام می‌دهد. این راهنما عمدتاً برای توسعه دهندگانی است که نمی توانند از کتابخانه های سرویس گیرنده Google API استفاده کنند، که برخی از آنها پشتیبانی بومی را برای آپلودهای قابل ازسرگیری ارائه می دهند. در واقع، YouTube Data API - Uploading a Video راهنمای نحوه استفاده از Google APIs Client Library برای پایتون برای آپلود یک ویدیو با استفاده از فرآیند آپلود مجدد قابل استفاده توضیح می دهد.

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

httplib2.debuglevel = 4

مرحله 1 - یک جلسه قابل ازسرگیری را شروع کنید

برای شروع آپلود مجدد ویدیو، یک درخواست POST به آدرس اینترنتی زیر ارسال کنید. در URL، مقدار پارامتر part را روی مقدار مناسب برای درخواست خود تنظیم کنید. به یاد داشته باشید که مقدار پارامتر قسمت هایی را که دارای ویژگی هایی هستند که شما تنظیم می کنید مشخص می کند و همچنین قسمت هایی را که می خواهید پاسخ API شامل آنها شود را مشخص می کند. مقادیر پارامتر در URL درخواست باید با URL رمزگذاری شوند.

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"
  }
}

مرحله 2 - URI جلسه قابل تجدید را ذخیره کنید

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

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

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

مرحله 3 - فایل ویدیویی را آپلود کنید

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

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

BINARY_FILE_DATA

درخواست هدرهای درخواست HTTP زیر را تنظیم می کند:

  • Authorization - نشانه مجوز برای درخواست.
  • Content-Length – اندازه فایلی که آپلود می کنید. این مقدار باید با مقدار هدر درخواست HTTP X-Upload-Content-Length در مرحله 1 یکسان باشد.
  • Content-Type – نوع MIME فایلی که آپلود می کنید. این مقدار باید با مقدار هدر درخواست HTTP X-Upload-Content-Type در مرحله 1 یکسان باشد.

مرحله 4 - مراحل آپلود را کامل کنید

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

  • آپلود شما با موفقیت انجام شد.

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

  • آپلود شما با موفقیت انجام نشد، اما می توان آن را از سر گرفت.

    در هر یک از موارد زیر باید بتوانید آپلود را از سر بگیرید:

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

    • پاسخ API هر یک از کدهای پاسخ 5xx زیر را مشخص می کند. کد شما باید در هنگام از سرگیری آپلودها پس از دریافت هر یک از این کدهای پاسخ، از استراتژی عقب نشینی نمایی استفاده کند.

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

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

  • آپلود شما برای همیشه ناموفق بود.

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

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

مرحله 4.1: وضعیت آپلود را بررسی کنید

برای بررسی وضعیت آپلود قابل ازسرگیری قطع شده، یک درخواست PUT خالی را به URL آپلودی که در مرحله 2 بازیابی کرده اید و در مرحله 3 نیز استفاده کرده اید ارسال کنید. در درخواست خود، مقدار سرصفحه 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

مرحله 4.2: پاسخ API را پردازش کنید

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

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

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

پاسخ نمونه زیر فرمت یک پاسخ API را برای آپلود مجدد نشان می دهد:

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

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

مرحله 4.3: بارگذاری را از سر بگیرید

برای از سرگیری آپلود، درخواست PUT دیگری را به URL آپلود ثبت شده در مرحله 2 ارسال کنید. متن درخواست را روی کد باینری برای بخشی از فایل ویدیویی که هنوز آپلود نشده است، تنظیم کنید.

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

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

  • Authorization - نشانه مجوز برای درخواست.

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

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

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

    • LAST_BYTE - شاخص عددی مبتنی بر 0 آخرین بایت از فایل باینری که آپلود می کنید. به طور معمول، این آخرین بایت در فایل است. بنابراین، به عنوان مثال، اگر اندازه فایل 3000000 بایت بود، آخرین بایت فایل شماره 2999999 خواهد بود.

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

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

    به این ترتیب، اولین بایت آپلود شده در آپلود از سر گرفته شده باید بایت بعدی پس از آخرین بایتی باشد که قبلاً با موفقیت در YouTube آپلود شده است. (به بحث هدر Range در مرحله 4.2 مراجعه کنید.

    بنابراین، اگر آخرین بایت در هدر Range 999999 باشد، اولین بایت در درخواست از سرگیری آپلود باید 1000000 بایت باشد. (هر دو عدد از یک شاخص مبتنی بر 0 استفاده می کنند.) اگر می خواهید بارگذاری را از بایت 999999 یا از سر بگیرید. کمتر (بایت های همپوشانی) یا بایت 1000001 یا بالاتر (بایت های پرش)، هیچ یک از محتوای باینری آپلود خواهد شد.

یک فایل را به صورت تکه ای آپلود کنید

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

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

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

    • اندازه قطعه باید مضربی از 256 کیلوبایت باشد. (این محدودیت برای آخرین قطعه اعمال نمی شود زیرا اندازه کل فایل ممکن است مضرب 256 کیلوبایت نباشد.) به یاد داشته باشید که تکه های بزرگتر کارآمدتر هستند.

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

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

    به عنوان مثال، مقدار bytes 0-524287/2000000 نشان می دهد که درخواست اولین 524288 بایت (256 x 2048) را در یک فایل 2000000 بایتی ارسال می کند.

مثال زیر فرمت اولین مورد از یک سری درخواست ها را نشان می دهد که یک فایل 2,000,000 بایتی را به صورت تکه آپلود می کند: 

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 ) پاسخ می دهد. فرمت پاسخ همان چیزی است که در مرحله 4.2 توضیح داده شده است: پاسخ API را پردازش کنید .

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

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

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

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