تحميل وسائط

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

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

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

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

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

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

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

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

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

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

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

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

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

ملاحظة: تنتهي صلاحية عنوان URL لتحميل المحتوى بعد أسبوع واحد.

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

لبدء عملية تحميل قابلة للاستئناف، أرسِل طلب POST أو PUT إلى معرّف الموارد المنتظم (URI) الخاص بالطريقة /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 للوسائط المقبولة وحدود الحجم للملفات التي يتم تحميلها.

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

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

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

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

عند اكتمال تحميل الملف بالكامل، يستجيب الخادم برمز 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

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

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

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

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

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

• .NET
• Java
• PHP
• Python
• Ruby