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

تحميل الصور باستخدام واجهة برمجة التطبيقات 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) خاص. في الواقع، تشتمل الطرق التي تدعم تحميل الوسائط على نقطتَي نهاية لمعرّف الموارد المنتظم (URI) وهما:

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

مثال: POST /upload/games/v1configuration/images/resourceId/imageType/imageType
معرّف الموارد المنتظم (URI) للمورد القياسي للبيانات الوصفية. إذا كان المورد يحتوي على أي حقول بيانات، يتم استخدام هذه الحقول لتخزين بيانات التعريف التي تصف الملف الذي تم تحميله. يمكنك استخدام معرّف الموارد المنتظم (URI) هذا عند إنشاء قيم البيانات الوصفية أو تعديلها.

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

تحميل بسيط

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

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

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

HTTP/1.1 200
Content-Type: application/json

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

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

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

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

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

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

Content-Type. يمكنك الضبط على "متعدد الأجزاء/ذات صلة" وتضمين سلسلة الحدود التي تستخدمها لتحديد أجزاء الطلب.

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

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

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

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

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

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

يوضّح المثال أدناه طلب تحميل متعدد الأجزاء لواجهة 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--

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

HTTP/1.1 200
Content-Type: application/json

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

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

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

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

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

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

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

لبدء عملية تحميل قابلة للاستئناف، يمكنك تقديم طلب POST أو PUT إلى معرّف الموارد المنتظم /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
}

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

حفظ عنوان URL للجلسة القابلة للاستئناف

إذا نجح طلب بدء الجلسة، يستجيب خادم واجهة برمجة التطبيقات برمز حالة 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 بحجم 2000000 بايت بالكامل للمثال الحالي.

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 بايت.

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

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

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

bytes 0-524288

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

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

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

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

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

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

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

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

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

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

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

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

اطلب حالة التحميل. يستخدم الطلب التالي عنوان نطاق المحتوى للإشارة إلى أن الموضع الحالي في الملف 2000000 بايت غير معروف.
```
PUT {session_uri} HTTP/1.1
Content-Length: 0
Content-Range: bytes */2000000
```
استخراج عدد وحدات البايت التي تم تحميلها حتى الآن من الاستجابة. يستخدم استجابة الخادم عنوان Range للإشارة إلى أنّه تلقّى أوّل 43 بايت من الملف حتى الآن. استخدم القيمة العليا لعنوان النطاق لتحديد مكان بدء التحميل المستأنف.

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

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

تراجع أسي

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

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

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

يمكنك تقديم طلب إلى واجهة برمجة التطبيقات.
يتم تلقّي استجابة HTTP 503، ما يشير إلى أنّه يجب إعادة محاولة الطلب.
يُرجى الانتظار لمدة ثانية واحدة مع قيمة عشوائية لـ العشوائي_number_milliseconds وإعادة محاولة الطلب.
يتم تلقّي استجابة HTTP 503، ما يشير إلى أنّه يجب إعادة محاولة الطلب.
انتظِر لمدة ثانيتين مع إضافة عشوائي_number_milliseconds، وأعِد محاولة إجراء الطلب.
يتم تلقّي استجابة HTTP 503، ما يشير إلى أنّه يجب إعادة محاولة الطلب.
انتظِر لمدة 4 ثوانٍ + العشوائي_number_milliseconds، ثم أعِد محاولة إجراء الطلب.
يتم تلقّي HTTP 503 response، للإشارة إلى أنّه يجب إعادة محاولة الطلب.
انتظِر لمدة 8 ثوانٍ مع إضافة عشوائي_number_milliseconds، ثم أعِد محاولة إجراء الطلب.
يتم تلقّي HTTP 503 response، للإشارة إلى أنّه يجب إعادة محاولة الطلب.
انتظِر لمدة 16 ثانية بالإضافة إلى قيمة عشوائية قدرها 16 ثانية عشوائيًا، ثم أعِد محاولة إجراء الطلب.
إيقاف. الإبلاغ عن خطأ أو تسجيله

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

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