تحميل وسائط

تسمح ميزة تحميل الوسائط لواجهة برمجة التطبيقات Campaign Manager 360 API بتخزين البيانات في السحابة الإلكترونية وإتاحتها للخادم. يتضمن نوع البيانات الذي قد يرغب الشخص في تحميله الصور أو الفيديوهات أو ملفات PDF أو ملفات ZIP أو أي نوع آخر من البيانات.

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

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

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

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

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

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

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

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

  مثلاً: POST /upload/farm/v1/animals

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

  مثال: POST /farm/v1/animals

عملية تحميل بسيطة

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

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

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

POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=media

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

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

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

يوضح المثال التالي استخدام طلب تحميل بسيط واجهة برمجة تطبيقات المزرعة الخيالية.

POST /upload/farm/v1/animals?uploadType=media HTTP/1.1
Host: www.googleapis.com
Content-Type: image/jpeg
Content-Length: number_of_bytes_in_file
Authorization: Bearer your_auth_token

JPEG data

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

HTTP/1.1 200
Content-Type: application/json

{
  "name": "Llama"
}

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

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

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

POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=multipart

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

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

يكون نص الطلب بالتنسيق من نوع محتوى multipart/related [RFC2387] ويحتوي على جزءَين بالضبط. يتم تحديد الأجزاء من خلال سلسلة حدود، وتليها اثنتان من الواصلة.

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

1. جزء البيانات الوصفية: يجب أن يأتي أولاً، كما يجب أن يتطابق Content-Type مع أحد تنسيقات البيانات الوصفية المقبولة.
2. جزء الوسائط: يجب أن يأتي ثانيًا، ويجب أن يتطابق Content-Type مع أحد أنواع MIME المقبولة للوسائط في الطريقة.

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

ملاحظة: لإنشاء جزء البيانات الوصفية أو تعديله فقط، بدون تحميل البيانات المرتبطة، ما عليك سوى إرسال طلب POST أو PUT إلى نقطة نهاية المرجع العادية: https://www.googleapis.com/farm/v1/animals

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

يوضح المثال أدناه طلب تحميل متعدد الأجزاء لواجهة برمجة تطبيقات المزرعة الخيالية.

POST /upload/farm/v1/animals?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

{
  "name": "Llama"
}

--foo_bar_baz
Content-Type: image/jpeg

JPEG data
--foo_bar_baz--

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

HTTP/1.1 200
Content-Type: application/json

{
  "name": "Llama"
}

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

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

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

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

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

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

الخطوة 1: بدء جلسة يمكن استئنافها

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

POST https://www.googleapis.com/upload/farm/v1/animals?uploadType=resumable

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

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

• X-Upload-Content-Type يتم ضبط نوع MIME للوسائط الذي سيتم نقله في الطلبات اللاحقة.
• X-Upload-Content-Length. يتم ضبطه على عدد وحدات البايت لبيانات التحميل التي سيتم نقلها في الطلبات اللاحقة. إذا كان الطول غير معروف في وقت هذا الطلب، يمكنك حذف هذا العنوان.
• في حال تقديم بيانات وصفية: Content-Type. اضبط البيانات وفقًا لنوع بيانات البيانات الوصفية.
• Content-Length يتم ضبط هذا الإعداد على عدد وحدات البايت المتوفرة في نص هذا الطلب الأولي. لا يكون هذا العمود مطلوبًا إذا كنت تستخدم ترميز النقل المجزّأ.

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

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

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

POST /upload/farm/v1/animals?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/jpeg
X-Upload-Content-Length: 2000000

{
  "name": "Llama"
}

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

يصف القسم التالي كيفية التعامل مع الرد.

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

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

مثال على استجابة بدء جلسة يمكن استئنافها

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

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/farm/v1/animals?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

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

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

الخطوة 3: تحميل الملف

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

PUT session_uri

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

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

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

PUT https://www.googleapis.com/upload/farm/v1/animals?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: image/jpeg

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

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

قد يبدو الطلب الذي يرسل أول 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 لأي جزء أو إذا تلقّيت رمز استجابة HTTP 503 Service Unavailable أو أي استجابة أخرى 5xx من الخادم، اتّبِع الإجراء الموضّح في مقالة استئناف عملية تحميل متوقّفة، ولكن بدلاً من تحميل بقية الملف، ما عليك سوى مواصلة تحميل الأجزاء من تلك النقطة.

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

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

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

---

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

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

1. حالة الطلب: يمكنك الاستعلام عن الحالة الحالية لتحميل البيانات من خلال إرسال طلب PUT فارغ إلى معرّف الموارد المنتظِم لتحميل البيانات. بالنسبة إلى هذا الطلب، يجب أن تتضمّن رؤوس 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

ملاحظة: من الممكن أن تكون استجابة الحالة 201 Created أو 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. يُرجى الانتظار لمدة ثانية واحدة + Spam_number_milliseconds، ثم إعادة محاولة الطلب.
4. تلقّي ردّ HTTP 503، ما يشير إلى أنّه يجب إعادة محاولة الطلب.
5. انتظِر لمدة ثانيتَين + عدد_عشوائي_بالملي ثانية، ثم أعِد محاولة إجراء الطلب.
6. تلقّي ردّ HTTP 503، ما يشير إلى أنّه يجب إعادة محاولة الطلب.
7. انتظِر 4 ثوانٍ + عدد_عشوائي_بالملي ثانية، ثم أعِد محاولة إجراء الطلب.
8. تلقّي استجابة HTTP 503، ما يشير إلى أنّه عليك إعادة محاولة إرسال الطلب
9. انتظِر لمدة 8 ثوانٍ + عدد_عشوائي_بالملي ثانية، ثم أعِد محاولة إجراء الطلب.
10. تلقّي استجابة HTTP 503، ما يشير إلى أنّه عليك إعادة محاولة إرسال الطلب
11. انتظِر لمدة 16 ثانية + عدد_عشوائي_بالملي ثانية، ثم أعِد محاولة إجراء الطلب.
12. إيقاف. الإبلاغ عن خطأ أو تسجيله

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

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

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

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

• .NET
• Java
• PHP
• Python
• روبي