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

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

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

يكون استخدام ميزة "التحميل القابل للاستئناف" مفيدًا بشكل خاص في أيّ من الحالات التالية:

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

يوضّح هذا الدليل تسلسل طلبات HTTP التي يقدّمها التطبيق لتحميل الفيديوهات باستخدام عملية تحميل قابلة للاستئناف. هذا الدليل مخصّص في المقام الأول للمطوّرين الذين لا يمكنهم استخدام مكتبات عملاء Google API، التي توفّر بعض منها إمكانية تحميل ملفات الوسائط بشكل متقطّع. يشرح دليل YouTube Data API - تحميل فيديو كيفية استخدام مكتبة Google APIs Client Library للغة 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.

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

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: حفظ معرّف الموارد المنتظم للجلسة التي يمكن استئنافها

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

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

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

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

إذا أرسلت طلبًا باستخدام معرّف موارد منتظم لجلسة منتهي الصلاحية، سيعرض الخادم رمز استجابة HTTP‏ 404 (Not Found). وفي هذه الحالة، عليك بدء عملية تحميل جديدة قابلة للاستئناف والحصول على معرّف موارد منتظم جديد للجلسة وبدء عملية التحميل من البداية باستخدام المعرّف الجديد.

الخطوة 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 بايت.

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

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

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

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

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

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