جارٍ تحميل الملفات

تسمح لك واجهة Google Play Developer API بتحميل الصور أو ملفات apk أو expansionfiles لإجراء تعديل. نستخدم الصور أدناه كمثال.

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

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

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

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

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

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

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

    مثلاً: POST /upload/androidpublisher/v3/applications/packageName/edits/editId/listings/language/imageType

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

    مثال: POST /androidpublisher/v3/applications/packageName/edits/editId/listings/language/imageType

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

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

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

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

POST https://www.googleapis.com/upload/androidpublisher/v3/applications/packageName/edits/editId/listings/language/imageType?uploadType=media

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

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

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

يوضح المثال التالي استخدام طلب تحميل بسيط واجهة Google Play Developer API:

POST /upload/androidpublisher/v3/applications/packageName/edits/editId/listings/language/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

{
  "image": {
    "id": string,
    "url": string,
    "sha1": string
  }
}

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

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

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

POST https://www.googleapis.com/upload/androidpublisher/v3/applications/packageName/edits/editId/listings/language/imageType?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/androidpublisher/v3/applications/packageName/edits/editId/listings/language/imageType

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

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

POST /upload/androidpublisher/v3/applications/packageName/edits/editId/listings/language/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

{
  "image": {
    "id": string,
    "url": string,
    "sha1": string
  }
}

--foo_bar_baz
Content-Type: image/png

PNG data
--foo_bar_baz--

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

HTTP/1.1 200
Content-Type: application/json

{
  "image": {
    "id": string,
    "url": string,
    "sha1": string
  }
}

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

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

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

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

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

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

الخطوة 1: بدء جلسة قابلة للاستئناف

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

POST https://www.googleapis.com/upload/androidpublisher/v3/applications/packageName/edits/editId/listings/language/imageType?uploadType=resumable

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

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

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

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

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

يوضّح المثال التالي كيفية بدء جلسة قابلة للاستئناف لواجهة Google Play Developer API.

POST /upload/androidpublisher/v3/applications/packageName/edits/editId/listings/language/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

{
  "image": {
    "id": string,
    "url": string,
    "sha1": string
  }
}

ملاحظة: في ما يتعلّق بطلب التعديل الأولي القابل للاستئناف بدون بيانات وصفية، اترك نص الطلب فارغًا، واضبط عنوان 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/androidpublisher/v3/applications/packageName/edits/editId/listings/language/imageType?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

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

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

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

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

PUT session_uri

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

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

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

PUT https://www.googleapis.com/upload/androidpublisher/v3/applications/packageName/edits/editId/listings/language/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 بايت)، باستثناء المقطع النهائي الذي يكمل التحميل. إذا كنت تستخدم التقسيم، من المهم الحفاظ على حجم المقطع أكبر قدر ممكن للحفاظ على كفاءة التحميل.

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

قد يبدو الطلب الذي يرسل أول 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، بالإضافة إلى عنوان Range الذي يحدد إجمالي عدد وحدات البايت التي تم تخزينها حتى الآن:

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

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

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

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

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

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

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