تحميل الصور باستخدام واجهة برمجة التطبيقات Play Games Services Publishing API

متوقّفة نهائيًا: تم إيقاف واجهة برمجة التطبيقات هذه نهائيًا، ويتم حاليًا إزالتها، لذا يجب عدم استخدامها. تؤدي محاولة استخدام واجهة برمجة التطبيقات هذه إلى حدوث أخطاء.

تتيح لك واجهة برمجة التطبيقات Play Games Services Publishing API تحميل صورة لأحد موارد الألعاب.

خيارات التحميل

تتيح لك واجهة برمجة التطبيقات Play Games Services Publishing API تحميل أنواع معيّنة من البيانات الثنائية أو الوسائط. يتم تحديد الخصائص المحدّدة للبيانات التي يمكنك تحميلها في صفحة المرجع الخاصة بأي طريقة تتيح تحميل الوسائط:

• الحدّ الأقصى لحجم ملف التحميل: الحدّ الأقصى لكمية البيانات التي يمكنك تخزينها باستخدام هذه الطريقة.

• أنواع MIME المقبولة للوسائط: هي أنواع البيانات الثنائية التي يمكنك تخزينها باستخدام هذه الطريقة.

يمكنك تقديم طلبات التحميل بأي من الطرق التالية. حدِّد الطريقة التي تستخدمها من خلال مَعلمة الطلب uploadType.

• التحميل البسيط: uploadType=media. لنقل الملفات الصغيرة بسرعة، مثل الملفات التي يبلغ حجمها 5 ميغابايت أو أقل

• التحميل المتعدد الأجزاء: uploadType=multipart. لنقل الملفات الصغيرة والبيانات الوصفية بسرعة، يتم نقل الملف مع البيانات الوصفية التي تصفه، وكل ذلك في طلب واحد.

• التحميل القابل للاستئناف: uploadType=resumable. لضمان نقل البيانات بشكل موثوق، وهو أمر مهم بشكل خاص مع الملفات الأكبر حجمًا باستخدام هذه الطريقة، يمكنك استخدام طلب بدء جلسة يمكن أن يتضمّن بشكل اختياري بيانات وصفية. وهذه استراتيجية جيدة يمكن استخدامها لمعظم التطبيقات، لأنّها تعمل أيضًا مع الملفات الأصغر حجمًا مقابل طلب HTTP إضافي واحد لكل عملية تحميل.

عند تحميل الوسائط، عليك استخدام معرّف موارد موحّد خاص. في الواقع، تتضمّن الطرق التي تتيح تحميل الوسائط نقطتَي نهاية لمعرّف الموارد المنتظم (URI):

• معرّف الموارد المنتظم /upload الخاص بالوسائط يكون تنسيق نقطة نهاية التحميل هو معرّف الموارد المنتظم (URI) العادي للمورد مع البادئة "/upload". استخدِم معرّف الموارد الموحّد هذا عند نقل بيانات الوسائط نفسها.

  مثال: POST /upload/games/v1configuration/images/resourceId/imageType/imageType

• معرّف الموارد المنتظم العادي للبيانات الوصفية: إذا كان المرجع يحتوي على أي حقول بيانات، يتم استخدام هذه الحقول لتخزين البيانات الوصفية التي تصف الملف الذي تم تحميله. يمكنك استخدام معرّف الموارد المنتظم هذا عند إنشاء قيم البيانات الوصفية أو تعديلها.

  مثال: POST /games/v1configuration/images/resourceId/imageType/imageType

تحميل بسيط

إنّ الطريقة الأسهل لتحميل ملف هي تقديم طلب تحميل بسيط. يُعدّ هذا الخيار مناسبًا في الحالات التالية:

• الملف صغير بما يكفي لإعادة تحميله بالكامل في حال تعذّر الاتصال.

• ما مِن بيانات وصفية لإرسالها. قد يكون هذا صحيحًا إذا كنت تخطط لإرسال بيانات وصفية لهذا المرجع في طلب منفصل، أو إذا لم تكن البيانات الوصفية متاحة أو غير متوافقة. لاستخدام ميزة "التحميل البسيط"، أرسِل طلب POST أو PUT إلى معرّف الموارد المنتظم (URI) /upload الخاص بالطريقة وأضِف مَعلمة طلب البحث uploadType=media. على سبيل المثال:

POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=media

تتضمّن عناوين HTTP التي يجب استخدامها عند إرسال طلب تحميل بسيط ما يلي:

• Content-Type. يجب ضبطها على أحد أنواع بيانات الوسائط المقبولة للتحميل في الطريقة، المحدّدة في مرجع Publishing API.

• استبدِل Content-Length بعدد وحدات البايت التي تحمّلها. غير مطلوب إذا كنت تستخدم ترميز النقل المقسَّم.

مثال: تحميل بسيط

يعرض المثال التالي كيفية استخدام طلب تحميل بسيط لواجهة Play Games Services Publishing API.

POST /upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=media HTTP/1.1
Host: www.googleapis.com
Content-Type: image/png
Content-Length: number_of_bytes_in_file
Authorization: Bearer your_auth_token

PNG data

إذا نجح الطلب، يعرض الخادم رمز الحالة 200 OK HTTP مع أي بيانات وصفية. على سبيل المثال:

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

التحميل المتعدد الأجزاء

إذا كانت لديك بيانات وصفية تريد إرسالها مع البيانات التي سيتم تحميلها، يمكنك تقديم طلب multipart/related واحد. هذا الخيار مناسب إذا كانت البيانات التي ترسلها صغيرة بما يكفي لإعادة تحميلها بالكامل في حال تعذّر الاتصال.

لاستخدام ميزة "التحميل المتعدد الأجزاء"، أرسِل طلب POST أو PUT إلى معرّف الموارد المنتظم (URI) /upload الخاص بالطريقة وأضِف مَعلمة طلب البحث uploadType=multipart. على سبيل المثال:

POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=multipart

تتضمّن عناوين HTTP العالية المستوى التي يجب استخدامها عند إرسال طلب تحميل متعدد الأجزاء ما يلي:

-Content-Type: اضبط القيمة على multipart/related وأدرِج سلسلة الحدود التي تستخدمها لتحديد أجزاء الطلب.

استبدِل Content-Length بإجمالي عدد وحدات البايت في نص الطلب. يجب أن يكون الجزء الخاص بالوسائط في الطلب أصغر من الحد الأقصى لحجم الملف المحدّد لهذه الطريقة.

يتم تنسيق نص الطلب كنوع محتوى متعدد الأجزاء/مرتبط RFC2387 ويحتوي على جزأين بالضبط. يتم تحديد الأجزاء من خلال سلسلة حدود، وتتبع سلسلة الحدود النهائية شرطتان أفقيتان.

يحتاج كل جزء من الطلب المتعدد الأجزاء إلى عنوان Content-Type إضافي:

• جزء البيانات الوصفية: يجب أن يظهر أولاً، ويجب أن يتطابق Content-Type مع أحد تنسيقات البيانات الوصفية المقبولة.

• جزء الوسائط: يجب أن يأتي ثانيًا، ويجب أن يتطابق نوع المحتوى مع أحد أنواع MIME المقبولة للوسائط في الطريقة.

راجِع مرجع Publishing API للاطّلاع على قائمة بأنواع MIME المقبولة للوسائط والحدود القصوى لحجم الملفات التي يتم تحميلها لكل طريقة.

ملاحظة: لإنشاء جزء البيانات الوصفية أو تعديله فقط، بدون تحميل البيانات المرتبطة، أرسِل طلب POST أو PUT إلى نقطة نهاية المورد العادية: https://www.googleapis.com/games/v1configuration/images/resourceId/imageType/imageType

مثال: التحميل المتعدد الأجزاء

يوضّح المثال أدناه طلب تحميل متعدد الأجزاء لواجهة برمجة التطبيقات Play Games Services Publishing API.

POST /upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=multipart HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length: number_of_bytes_in_entire_request_body

--foo_bar_baz
Content-Type: application/json; charset=UTF-8

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

--foo_bar_baz
Content-Type: image/png

PNG data
--foo_bar_baz--

في حال نجاح الطلب، يعرض الخادم رمز الحالة 200 OK HTTP مع أي بيانات وصفية:

HTTP/1.1 200
Content-Type: application/json

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

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

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

تشمل خطوات استخدام التحميل القابل للاستئناف ما يلي:

1. ابدأ جلسة قابلة للاستئناف. أرسِل طلبًا أوليًا إلى معرّف الموارد المنتظم الخاص بالتحميل يتضمّن البيانات الوصفية، إن وجدت.

2. احفظ معرّف الموارد المنتظم (URI) للجلسة القابلة للاستئناف. احفظ معرّف الموارد المنتظم (URI) للجلسة الذي تم عرضه في رد الطلب الأوّلي، حيث ستستخدمه في الطلبات المتبقية في هذه الجلسة. حمّل الملف.

3. أرسِل ملف الوسائط إلى معرّف الموارد المنتظم (URI) الخاص بالجلسة القابلة للاستئناف.

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

ملاحظة: تنتهي صلاحية معرّف الموارد المنتظم (URI) الخاص بالتحميل بعد أسبوع.

بدء جلسة قابلة للاستئناف

لبدء عملية تحميل قابلة للاستئناف، أرسِل طلب POST أو PUT إلى معرّف الموارد المنتظم (URI) الخاص بالطريقة /upload وأضِف مَعلمة طلب البحث uploadType=resumable. على سبيل المثال:

POST https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable

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

استخدِم عناوين HTTP التالية مع الطلب الأوّلي:

• X-Upload-Content-Type. يتم ضبط هذا الحقل على نوع MIME الخاص بالوسائط لبيانات التحميل التي سيتم نقلها في الطلبات اللاحقة.

• X-Upload-Content-Length. يتم ضبط هذا الحقل على عدد وحدات بايت لبيانات التحميل التي سيتم نقلها في الطلبات اللاحقة. إذا كان طول المحتوى غير معروف عند إرسال هذا الطلب، يمكنك حذف هذا العنوان.

• في حال تقديم بيانات وصفية: Content-Type اضبط القيمة وفقًا لنوع بيانات البيانات الوصفية.

• Content-Length. يجب ضبطها على عدد وحدات البايت المقدَّمة في نص هذا الطلب الأوّلي. هذا الحقل غير مطلوب إذا كنت تستخدم ترميز النقل المقسَّم.

راجِع مرجع Publishing API للاطّلاع على قائمة بأنواع MIME المقبولة للوسائط والحدود القصوى لحجم الملفات التي يتم تحميلها لكل طريقة.

مثال: طلب بدء جلسة قابلة للاستئناف

يوضّح المثال التالي كيفية بدء جلسة قابلة للاستئناف لواجهة برمجة التطبيقات Play Games Services Publishing API.

POST /upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Length: 38
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Type: image/png
X-Upload-Content-Length: 2000000

{
  "kind": "gamesConfiguration#imageConfiguration",
  "url": string,
  "resourceId": string,
  "imageType": string
}

ملاحظة: لإرسال طلب أولي لتعديل قابل للاستئناف بدون بيانات وصفية، اترُك نص الطلب فارغًا، واضبط عنوان Content-Length على 0.

يوضّح القسم التالي كيفية التعامل مع الردّ.

حفظ معرّف الموارد المنتظم (URI) للجلسة القابلة للاستئناف

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

مثال: ردّ على بدء جلسة قابلة للاستئناف

في ما يلي الردّ على الطلب في الخطوة 1:

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

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

انسخ معرّف الموارد المنتظم (URI) للجلسة واحفظه لتتمكّن من استخدامه في الطلبات اللاحقة.

تحميل الملف

لتحميل الملف، أرسِل طلب PUT إلى معرّف الموارد المنتظم (URI) الخاص بالتحميل الذي حصلت عليه في الخطوة السابقة. يكون تنسيق طلب التحميل على النحو التالي:

PUT session_uri

تتضمّن عناوين HTTP التي يجب استخدامها عند تقديم طلبات تحميل الملفات القابلة للاستئناف Content-Length. اضبط هذا الحقل على عدد البايتات التي يتم تحميلها في هذا الطلب، وهو بشكل عام حجم ملف التحميل.

مثال: طلب تحميل ملف قابل للاستئناف

في ما يلي طلب قابل للاستئناف لتحميل ملف PNG بالكامل بحجم 2,000,000 بايت للمثال الحالي.

PUT https://www.googleapis.com/upload/games/v1configuration/images/resourceId/imageType/imageType?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: image/png

bytes 0-1999999

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

في حال انقطاع طلب التحميل أو تلقّي الرد HTTP 503 Service Unavailable أو أي رد آخر 5xx من الخادم، اتّبِع الإجراء الموضّح في استئناف عملية تحميل متوقّفة.

تحميل الملف على شكل أجزاء

باستخدام عمليات التحميل القابلة للاستئناف، يمكنك تقسيم الملف إلى أجزاء وإرسال سلسلة من الطلبات لتحميل كل جزء بالتسلسل. لا يُنصح بهذا الأسلوب لأنّه يتضمّن تكاليف أداء مرتبطة بالطلبات الإضافية، كما أنّه غير ضروري بشكل عام. ومع ذلك، قد تحتاج إلى استخدام تقسيم البيانات إلى أجزاء لتقليل كمية البيانات التي يتم نقلها في أي طلب واحد. ويكون ذلك مفيدًا عندما يكون هناك حد زمني ثابت للطلبات الفردية، كما هو الحال بالنسبة إلى فئات معيّنة من طلبات Google App Engine. وتتيح لك أيضًا تنفيذ إجراءات، مثل تقديم مؤشرات تقدّم التحميل للمتصفّحات القديمة التي لا تتوافق تلقائيًا مع ميزة تقدّم التحميل.

إذا كنت تحمّل البيانات على شكل أجزاء، يجب توفير عنوان Content-Range، بالإضافة إلى عنوان Content-Length المطلوب لتحميل الملفات الكاملة:

• Content-Length. اضبط القيمة على حجم الجزء أو أقل، كما قد يكون الحال بالنسبة إلى الطلب الأخير.

• Content-Range: يتم ضبطها لعرض وحدات البايت في الملف الذي يتم تحميله. على سبيل المثال، يشير Content-Range: bytes 0-524287/2000000 إلى أنّك تقدّم أول 524,288 بايت (256 × 1024 × 2) في ملف يبلغ حجمه 2,000,000 بايت.

ملاحظة: يجب أن يكون حجم جميع الأجزاء من مضاعفات 256 كيلوبايت (256 × 1024 بايت)، باستثناء الجزء الأخير الذي يكمل عملية التحميل. في حال استخدام تقسيم الملفات، من المهم الحفاظ على حجم الأجزاء كبيرًا قدر الإمكان لضمان فعالية عملية التحميل.

التوسيع للحصول على مزيد من المعلومات

إذا كنت تحمّل البيانات على شكل أجزاء، يكون العنوان Content-Range مطلوبًا أيضًا، بالإضافة إلى العنوان Content-Length المطلوب لعمليات تحميل الملفات الكاملة:

• Content-Length. اضبط القيمة على حجم الجزء أو أقل، كما قد يكون الحال بالنسبة إلى الطلب الأخير.
• Content-Range: يتم ضبطها لعرض وحدات البايت في الملف الذي يتم تحميله.  على سبيل المثال، يشير Content-Range: bytes 0-524287/2000000 إلى أنّك تقدّم أول 524,288 بايت (256 × 1024 × 2) في ملف يبلغ حجمه 2,000,000 بايت.

قيود حجم الأجزاء: يجب أن يكون حجم جميع الأجزاء مضاعفًا لـ 256 كيلوبايت (256 × 1024 بايت)، باستثناء الجزء الأخير الذي يكمل عملية التحميل. في حال استخدام تقسيم الملفات، من المهم الحفاظ على حجم الأجزاء كبيرًا قدر الإمكان للحفاظ على كفاءة عملية التحميل.

مثال: طلب تحميل ملف مقسّم إلى أجزاء يمكن استئناف تحميلها

قد يبدو الطلب الذي يرسل أول 524,288 بايت على النحو التالي:

PUT {session_uri} HTTP/1.1
Host: www.googleapis.com
Content-Length: 524288
Content-Type: image/jpeg
Content-Range: bytes 0-524287/2000000

bytes 0-524288

في حال نجاح الطلب، يستجيب الخادم بالرمز 308 Resume Incomplete، بالإضافة إلى العنوان Range الذي يحدّد إجمالي عدد وحدات البايت التي تم تخزينها حتى الآن:

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: bytes=0-524287

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

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

ملاحظات مهمة:

• احرص على استخدام العنوان Range في الرد لتحديد موضع بدء الجزء التالي، ولا تفترض أنّ الخادم تلقّى جميع وحدات البايت المُرسَلة في الطلب السابق.
• لكل معرّف URI لعملية تحميل مدة صلاحية محدودة وتنتهي صلاحيته في النهاية (في غضون يوم أو نحو ذلك، إذا لم يتم استخدامه). لهذا السبب، من الأفضل بدء عملية تحميل قابلة للاستئناف فور الحصول على معرّف الموارد المنتظم الخاص بالتحميل، واستئناف عملية تحميل تمت مقاطعتها بعد فترة قصيرة من حدوث المقاطعة.
• إذا أرسلت طلبًا يتضمّن معرّف جلسة تحميل منتهية الصلاحية، سيعرض الخادم رمز الحالة 404 Not Found. عند حدوث خطأ غير قابل للاسترداد في جلسة التحميل، يعرض الخادم رمز الحالة 410 Gone. في هذه الحالات، يجب بدء عملية تحميل جديدة قابلة للاستئناف والحصول على معرّف موارد موحّد جديد للتحميل وبدء عملية التحميل من البداية باستخدام نقطة النهاية الجديدة.

عند اكتمال عملية تحميل الملف بأكملها، يستجيب الخادم بالرمز HTTP 201 Created مع أي بيانات وصفية مرتبطة بهذا المرجع. إذا كان هذا الطلب يهدف إلى تعديل كيان حالي بدلاً من إنشاء كيان جديد، كان رمز استجابة HTTP لعملية تحميل مكتملة هو 200 OK.

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

إذا تم إنهاء طلب تحميل قبل تلقّي رد أو إذا تلقّيت الرد HTTP 503 Service Unavailable من الخادم، عليك استئناف عملية التحميل التي تمّت مقاطعتها. لاستئناف عملية تحميل تم إيقافها، اتّبِع الخطوات التالية:

1. حالة الطلب يمكنك الاستعلام عن الحالة الحالية لعملية التحميل من خلال إصدار طلب PUT فارغ إلى معرّف الموارد المنتظم (URI) الخاص بعملية التحميل. بالنسبة إلى هذا الطلب، يجب أن تتضمّن عناوين HTTP العنوان Content-Range الذي يشير إلى أنّ الموضع الحالي في الملف غير معروف. على سبيل المثال، اضبط قيمة Content-Range على */2000000 إذا كان إجمالي طول الملف 2,000,000. إذا كنت لا تعرف الحجم الكامل للملف، اضبط Content-Range على */*.

   ملاحظة: يمكنك طلب معرفة الحالة بين أجزاء الفيديو، وليس فقط في حال انقطاع عملية التحميل. يكون ذلك مفيدًا، مثلاً، إذا أردت عرض مؤشرات تقدّم التحميل للمتصفّحات القديمة.

2. الحصول على عدد وحدات البايت التي تم تحميلها معالجة الردّ من طلب الحالة يستخدم الخادم عنوان Range في استجابته لتحديد عدد البايتات التي تلقّاها حتى الآن. على سبيل المثال، يشير العنوان Range الذي يتضمّن 0-299999 إلى أنّه تم تلقّي أول 300,000 بايت من الملف.

3. تحميل البيانات المتبقية أخيرًا، بعد أن عرفت مكان استئناف الطلب، أرسِل البيانات المتبقية أو الجزء الحالي. يُرجى العِلم أنّه عليك التعامل مع البيانات المتبقية كجزء منفصل في كلتا الحالتين، لذا عليك إرسال العنوان Content-Range عند استئناف عملية التحميل.

مثال: استئناف عملية تحميل تم إيقافها

1. طلب حالة التحميل يستخدم الطلب التالي العنوان Content-Range للإشارة إلى أنّ الموضع الحالي في الملف الذي يبلغ حجمه 2,000,000 بايت غير معروف.

   PUT {session_uri} HTTP/1.1
   Content-Length: 0
   Content-Range: bytes */2000000
   

2. استخرِج عدد وحدات البايت التي تم تحميلها حتى الآن من الردّ. يستخدم رد الخادم العنوان Range للإشارة إلى أنّه تلقّى أول 43 بايت من الملف حتى الآن. استخدِم القيمة العليا لعنوان Range لتحديد موضع بدء عملية التحميل التي تم استئنافها.

   HTTP/1.1 308 Resume Incomplete
   Content-Length: 0
   Range: 0-42
   

   ملاحظة: من المحتمل أن يكون ردّ الحالة 201Created أو 200 OK إذا اكتملت عملية التحميل. قد يحدث ذلك إذا انقطع الاتصال بعد تحميل جميع وحدات البايت ولكن قبل أن يتلقّى العميل ردًا من الخادم.

3. استئناف التحميل من حيث توقّف، حيث يستأنف الطلب التالي عملية التحميل من خلال إرسال وحدات البايت المتبقية من الملف، بدءًا من البايت رقم 43.

   PUT {session_uri} HTTP/1.1
   Content-Length: 1999957
   Content-Range: bytes 43-1999999/2000000
   
   bytes 43-1999999
   

معالجة الأخطاء

عند تحميل الوسائط، من المفيد معرفة بعض أفضل الممارسات المتعلقة بمعالجة الأخطاء.

• استئناف أو إعادة محاولة عمليات التحميل التي يتعذّر إجراؤها بسبب انقطاع الاتصال أو أي أخطاء 5xx، بما في ذلك:

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

• استخدِم استراتيجية التراجع الأسي في حال تم عرض أي خطأ في الخادم 5xx عند استئناف طلبات التحميل أو إعادة محاولة تنفيذها. يمكن أن تحدث هذه الأخطاء إذا كان الخادم مثقلاً. يمكن أن يساعد التراجع الأسي في التخفيف من هذه الأنواع من المشاكل خلال الفترات التي تشهد عددًا كبيرًا من الطلبات أو حركة بيانات الشبكة الكثيفة.

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

• تعامَل مع الخطأين 404 Not Found و410 Gone عند إجراء عمليات تحميل قابلة للاستئناف من خلال إعادة بدء عملية التحميل بأكملها من البداية.

الرقود الأسي الثنائي

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

عند استخدام التراجع الأسي بشكل صحيح، يؤدي ذلك إلى زيادة كفاءة استخدام معدل نقل البيانات وتقليل عدد الطلبات اللازمة للحصول على استجابة ناجحة وزيادة معدل نقل البيانات إلى أقصى حد في البيئات المتزامنة.

في ما يلي خطوات تنفيذ أسلوب "التراجع الدليلي" البسيط:

1. إرسال طلب إلى واجهة برمجة التطبيقات
2. تلقّي الردّ HTTP 503، ما يشير إلى أنّه عليك إعادة محاولة الطلب
3. انتظِر لمدة ثانية واحدة + random_number_milliseconds وأعِد محاولة إجراء الطلب.
4. تلقّي الردّ HTTP 503، ما يشير إلى أنّه عليك إعادة محاولة الطلب
5. انتظِر لمدة ثانيتَين + random_number_milliseconds، ثم أعِد محاولة إجراء الطلب.
6. تلقّي الردّ HTTP 503، ما يشير إلى أنّه عليك إعادة محاولة الطلب
7. انتظِر 4 ثوانٍ + random_number_milliseconds، ثم أعِد محاولة إجراء الطلب.
8. تلقّي الرمز HTTP 503 response، ما يشير إلى أنّه عليك إعادة محاولة الطلب
9. انتظِر لمدة 8 ثوانٍ + random_number_milliseconds، ثم أعِد محاولة إجراء الطلب.
10. تلقّي الرمز HTTP 503 response، ما يشير إلى أنّه عليك إعادة محاولة الطلب
11. انتظِر لمدة 16 ثانية + random_number_milliseconds، ثم أعِد محاولة إجراء الطلب.
12. إيقاف. الإبلاغ عن خطأ أو تسجيله

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

ملاحظة: يكون وقت الانتظار دائمًا (2 ^ n) + random_number_milliseconds، حيث n هو عدد صحيح يتزايد بشكل رتيب ويتم تحديده في البداية على أنّه 0. تتم زيادة العدد الصحيح n بمقدار 1 في كل تكرار (كل طلب).

تم ضبط الخوارزمية على الإنهاء عندما تكون قيمة n هي 5. يمنع هذا الحدّ الأقصى العملاء من إعادة المحاولة إلى ما لا نهاية، ويؤدي إلى تأخير إجمالي يبلغ حوالي 32 ثانية قبل أن يُصنّف الطلب على أنّه "خطأ غير قابل للإصلاح". لا بأس بزيادة الحد الأقصى لعدد محاولات إعادة الإرسال، خاصةً إذا كان يجري تحميل ملف كبير الحجم، ولكن احرص على ألا يتجاوز تأخير إعادة الإرسال مدة معقولة، مثلاً أقل من دقيقة واحدة.

أدلة مكتبات عميل واجهة برمجة التطبيقات

• ‎.NET

• Java

• PHP

• Python

• Ruby