تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

تحميلات قابلة للاستئناف

يمكنك تحميل مقاطع الفيديو بشكل أكثر موثوقية باستخدام بروتوكول التحميل القابل للاستئناف في Google APIs. يتيح لك هذا البروتوكول استئناف عملية التحميل بعد انقطاع الشبكة أو غيرها من حالات إخفاق الإرسال، ما يؤدي إلى توفير الوقت ومعدل نقل البيانات في حال حدوث أعطال في الشبكة.

يُعد استخدام التحميلات القابلة للاستئناف مفيدًا على وجه الخصوص في أي من الحالات التالية:

أنت بصدد نقل ملفات كبيرة.
احتمال كبير لتوقف الشبكة.
وتنشأ التحميلات من جهاز مزود باتصال بالإنترنت بمعدل نقل بيانات منخفض أو غير ثابت، مثل جهاز جوّال.

يوضح هذا الدليل تسلسل طلبات HTTP التي يُجريها أحد التطبيقات لتحميل مقاطع الفيديو باستخدام عملية تحميل قابلة للاستئناف. يستهدف هذا الدليل بشكل أساسي مطوّري البرامج الذين لا يمكنهم استخدام مكتبات عميل Google API، والتي يقدّم بعضها دعمًا أصليًا لعمليات التحميل القابلة للاستئناف. في الواقع، يوضّح دليل YouTube Data API - تحميل فيديو كيفية استخدام "مكتبة برامج Google APIs" للغة Python لتحميل فيديو باستخدام عملية تحميل قابلة للاستئناف.

ملاحظة: يمكنك أيضًا الاطّلاع على سلسلة الطلبات المقدّمة للتحميل القابل للاستئناف أو أي عملية أخرى لواجهة برمجة التطبيقات باستخدام إحدى مكتبات عملاء Google API مع تفعيل تسجيل HTTPS. على سبيل المثال، لتفعيل تتبّع HTTP للغة Python، استخدِم مكتبة httplib2:

httplib2.debuglevel = 4

الخطوة 1 - بدء جلسة قابلة للاستئناف

لبدء تحميل فيديو قابل للاستئناف، أرسل طلب POST إلى عنوان URL التالي. في عنوان URL، اضبط قيمة المَعلمة part على القيمة المناسبة لطلبك. تذكّر أن قيمة المعلّمة تحدّد الأجزاء التي تحتوي على الخصائص التي تضبطها، كما تحدد أيضًا الأجزاء التي تريد أن تشملها استجابة واجهة برمجة التطبيقات. يجب أن تكون قيم المعلمات في عنوان 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.

يوضح المثال التالي كيفية بدء جلسة قابلة للاستئناف لتحميل فيديو. ويعيّن الطلب خصائص (وسيتم استردادها) في الجزء video والجزء snippet من المورد، وسيسترد أيضًا الخصائص في الجزء 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 لواجهة برمجة التطبيقات.

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) للجلسة القابلة للاستئناف

إذا نجح طلبك، فسيستجيب خادم واجهة برمجة التطبيقات برمز حالة HTTP 200 (OK)، وستتضمن الاستجابة عنوان HTTP Location الذي يحدد معرف الموارد المنتظم (URI) للجلسة القابلة للاستئناف. هذا هو معرّف الموارد المنتظم (URI) الذي ستستخدمه لتحميل ملف الفيديو.

يعرض المثال أدناه نموذج استجابة من واجهة برمجة التطبيقات للطلب في الخطوة 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 - تحميل ملف الفيديو

بعد استخراج معرّف الموارد المنتظم للجلسة من استجابة واجهة برمجة التطبيقات، سيلزمك تحميل محتوى ملف الفيديو الفعلي إلى هذا الموقع. نص الطلب هو محتوى الملف الثنائي للفيديو الذي تحمّله. يوضح المثال أدناه تنسيق الطلب.

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 - إكمال عملية التحميل

سيؤدي طلبك إلى أحد السيناريوهات التالية:

اكتمل التحميل بنجاح.

يستجيب خادم واجهة برمجة التطبيقات برمز استجابة HTTP 201 (Created). نص الاستجابة هو مورد video الذي أنشأته.
تعذّر التحميل، ولكن يمكن استئنافه.

ينبغي أن تتمكن من استئناف التحميل في أي من الحالات التالية:
- تمت مقاطعة طلبك بسبب انقطاع الاتصال بين التطبيق وخادم واجهة برمجة التطبيقات. وفي هذه الحالة، لن تتلقى استجابة من واجهة برمجة التطبيقات.
- تحدد استجابة واجهة برمجة التطبيقات أيًا من رموز الاستجابة 5xx التالية. يجب أن تستخدم شفرتك استراتيجية التراجع الأسي عند استئناف التحميلات بعد تلقي أي من رموز الاستجابة هذه.
  - 500 – Internal Server Error
  - 502 – Bad Gateway
  - 503 – Service Unavailable
  - 504 – Gateway Timeout
لاستئناف تحميل، اتبع الإرشادات للتحقق من حالة التحميل واستئناف التحميل أدناه. وتجدر الإشارة إلى أنّ كل معرّف موارد منتظم (URI) للجلسة يمكن استئنافه يكون له مدة محدودة وتنتهي صلاحيته في النهاية. لهذا السبب، ننصحك ببدء عملية تحميل قابلة للاستئناف فور الحصول على معرِّف الموارد المنتظم (URI) للجلسة واستئناف التحميل الذي تمت مقاطعته بعد فترة قصيرة من حدوث انقطاع في الخدمة.
تعذّر التحميل بشكل دائم.

بالنسبة إلى عملية التحميل التي تعذّر تحميلها، تحتوي الاستجابة على استجابة خطأ يساعد في توضيح سبب الإخفاق. بالنسبة إلى التحميل الذي يخفق بشكل دائم، ستحتوي استجابة واجهة برمجة التطبيقات على رمز استجابة 4xx أو رمز استجابة 5xx بخلاف الرموز الواردة أعلاه.

إذا أرسلت طلبًا بعنوان URL لجلسة منتهية الصلاحية، يعرض الخادم رمز استجابة 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: معالجة استجابة واجهة برمجة التطبيقات

إذا اكتمل التحميل فعلاً، بغض النظر عما إذا كان قد نجح التحميل أم أخفق، ستعرض واجهة برمجة التطبيقات الاستجابة نفسها التي أرسلتها عند اكتمال التحميل في الأصل.

ولكن إذا تمت مقاطعة التحميل أو كانت لا تزال قيد التقدم، فستحتوي استجابة واجهة برمجة التطبيقات على رمز استجابة HTTP 308 (Resume Incomplete). في الاستجابة، يحدّد العنوان Range عدد وحدات البايت للملف التي تم تحميلها بنجاح.

تمت فهرسة قيمة الرأس من 0. وعلى هذا النحو، تشير قيمة العنوان 0-999999 إلى أن أول 1,000,000 بايت من الملف تم تحميلها.
إذا لم يتم تحميل أي شيء حتى الآن، فلن تتضمن استجابة واجهة برمجة التطبيقات العنوان Range.

يعرض نموذج الرد أدناه تنسيق استجابة واجهة برمجة التطبيقات للتحميل القابل للاستئناف:

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

إذا كانت استجابة واجهة برمجة التطبيقات تتضمّن أيضًا العنوان 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 أن الطلب يرسل أول 524,288 بايت (256 x 2048) في ملف بحجم 2,000,000 بايت.

يوضح المثال أدناه تنسيق أول سلسلة من الطلبات التي ستحمِّل ملفًا حجمه 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}

في حال نجاح طلب غير الطلب النهائي، سيستجيب خادم واجهة برمجة التطبيقات باستجابة 308 (Resume Incomplete). سيكون تنسيق الاستجابة هو نفسه الموضح في الخطوة 4.2: معالجة استجابة واجهة برمجة التطبيقات أعلاه.

استخدِم القيمة العليا المعروضة في عنوان Range لاستجابة واجهة برمجة التطبيقات لتحديد مكان بدء المجموعة التالية. استمر في إرسال طلبات PUT، كما هو موضَّح في الخطوة 4.3: استئناف التحميل، لتحميل أجزاء الملف اللاحقة حتى يتم تحميل الملف بالكامل.

عندما يتم تحميل الملف بأكمله، يستجيب الخادم برمز استجابة HTTP 201 (Created) ويعرض الأجزاء المطلوبة من مورد الفيديو الذي تم إنشاؤه حديثًا.

في حال مقاطعة أي طلب أو تلقّي طلبك أي رمز استجابة من 5xx، اتّبِع الإجراء الموضّح في الخطوة 4 لإكمال عملية التحميل. ولكن بدلاً من محاولة تحميل بقية الملف، ما عليك سوى مواصلة تحميل الأجزاء من النقطة التي ستستأنف فيها التحميل. تأكد من استخدام حالة التحقق من التحميل لتحديد مكان استئناف تحميل الملف. لا تفترض أن الخادم استلم جميع (أو لا شيء) وحدات البايت المرسلة في الطلب السابق.

ملاحظة: يمكنك أيضًا طلب حالة عملية تحميل نشطة بين الأجزاء التي تم تحميلها. (ليس من الضروري أن تتم مقاطعة التحميل قبل أن تتمكن من استرداد حالته.)