تحميل المرفقات

تتيح لك واجهة برمجة التطبيقات Gmail API تحميل بيانات الملفات عند إنشاء أو تعديل مسودة أو عند إدراج أو إرسال رسالة.

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

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

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

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

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

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

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

    مثلاً: POST /upload/gmail/v1/users/userId/messages/send

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

    مثال: POST /gmail/v1/users/userId/messages/send

تحميل بسيط

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

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

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

POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=media

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

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

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

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

POST /upload/gmail/v1/users/userId/messages/send?uploadType=media HTTP/1.1
Host: www.googleapis.com
Content-Type: message/rfc822
Content-Length: number_of_bytes_in_file
Authorization: Bearer your_auth_token

Email Message data

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

HTTP/1.1 200
Content-Type: application/json

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

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

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

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

POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?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/gmail/v1/users/userId/messages/send

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

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

POST /upload/gmail/v1/users/userId/messages/send?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

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

--foo_bar_baz
Content-Type: message/rfc822

Email Message data
--foo_bar_baz--

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

HTTP/1.1 200
Content-Type: application/json

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

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

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

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

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

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

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

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

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

POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable

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

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

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

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

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

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

POST /upload/gmail/v1/users/userId/messages/send?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: message/rfc822
X-Upload-Content-Length: 2000000

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

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

يصف القسم التالي كيفية معالجة الاستجابة.

الخطوة 2: حفظ معرّف الموارد المنتظم للجلسة التي يمكن استئنافها

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

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

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

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

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

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

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

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

PUT session_uri

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

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

في ما يلي طلب يمكن استئنافه لتحميل ملف رسالة البريد الإلكتروني بالكامل الذي يبلغ حجمه 2,000,000 بايت في المثال الحالي.

PUT https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: message/rfc822

bytes 0-1999999

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

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

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

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

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

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

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

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

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

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