بارگذاری پیوست‌ها

Gmail API به شما امکان می‌دهد هنگام ایجاد یا به‌روزرسانی پیش‌نویس یا هنگام درج یا ارسال پیام، داده‌های فایل را بارگذاری کنید.

گزینه‌های بارگذاری

Gmail API به شما امکان می‌دهد انواع خاصی از داده‌های دودویی یا رسانه را بارگذاری کنید. ویژگی‌های خاص داده‌هایی که می‌توانید بارگذاری کنید در صفحه مرجع برای هر روشی که از بارگذاری رسانه پشتیبانی می‌کند مشخص شده است:

  • حداکثر اندازه فایل بارگذاری: حداکثر مقدار داده‌ای که می‌توانید با این روش ذخیره کنید.
  • انواع MIME رسانه پذیرفته‌شده: انواع داده‌های دودویی که می‌توانید بااستفاده از این روش ذخیره کنید.

می‌توانید درخواست‌های بارگذاری را به هریک از روش‌های زیر انجام دهید. روش مورداستفاده‌تان را با پارامتر درخواست uploadType مشخص کنید.

  • بارگذاری ساده: uploadType=media. برای انتقال سریع فایل‌های کوچک‌تر، مثلاً ۵ مگابایت یا کمتر.
  • بارگذاری چندبخشی: uploadType=multipart. برای انتقال سریع فایل‌های کوچک‌تر و فراداده؛ فایل را همراه با فراداده‌ای که آن را توصیف می‌کند، همه را در یک درخواست منتقل می‌کند.
  • بارگذاری ازسرگرفتنی: uploadType=resumable. برای انتقال مطمئن، به‌ویژه برای فایل‌های بزرگ‌تر. با این روش، از درخواست آغاز جلسه استفاده می‌کنید که می‌تواند به‌صورت اختیاری شامل فراداده باشد. این استراتژی خوبی برای استفاده در اکثر برنامه‌ها است، زیرا برای فایل‌های کوچک‌تر نیز با هزینه یک درخواست HTTP اضافی برای هر بارگذاری کار می‌کند.

وقتی رسانه بارگذاری می‌کنید، از شناسه منبع یکسان ویژه‌ای استفاده می‌کنید. درواقع، روش‌هایی که از بارگذاری رسانه پشتیبانی می‌کنند دو نقطه پایانی URI دارند:

  • ‫URI بارگذاری/، برای رسانه. قالب نقطه پایانی بارگذاری، URI منبع استاندارد با پیشوند «/upload» است. هنگام انتقال داده‌های رسانه، از این URI استفاده کنید.

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

  • URI منبع استاندارد، برای فراداده. اگر منبع حاوی فیلدهای داده باشد، از آن فیلدها برای ذخیره فراداده‌ای که فایل بارگذاری‌شده را توصیف می‌کند استفاده می‌شود. هنگام ایجاد یا به‌روزرسانی مقادیر فراداده می‌توانید از این URI استفاده کنید.

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

بارگذاری ساده

ساده‌ترین روش برای بارگذاری فایل، ایجاد یک درخواست بارگذاری ساده است. این گزینه در شرایط زیر انتخاب خوبی است:

  • فایل به‌اندازه کافی کوچک است که اگر اتصال قطع شد، بتوان آن را دوباره به‌طور کامل بارگذاری کرد.
  • فراداده‌ای برای ارسال وجود ندارد. اگر قصد دارید فراداده این منبع را در درخواست جداگانه‌ای ارسال کنید، یا اگر فراداده‌ای پشتیبانی نمی‌شود یا دردسترس نیست، ممکن است این مورد درست باشد.

برای استفاده از بارگذاری ساده، درخواست POST یا PUT به URI /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 به شناسه منبع یکسان /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 جلسه ازسرگرفتنی را ذخیره کنید. شناسه منبع یکسان جلسه را که در پاسخ درخواست اولیه برگردانده شده است ذخیره کنید؛ از آن برای درخواست‌های باقی‌مانده در این جلسه استفاده خواهید کرد.
  3. فایل را بارگذاری کنید. فایل رسانه را به URI جلسه ازسرگرفتنی ارسال کنید.

علاوه‌براین، برنامه‌هایی که از بارگذاری قابل ازسرگیری استفاده می‌کنند باید کدی برای ازسرگیری بارگذاری قطع‌شده داشته باشند. اگر بارگذاری قطع شود، متوجه می‌شوید که چه مقدار داده باموفقیت دریافت شده است و سپس بارگذاری را از همان نقطه ازسر می‌گیرید.

توجه: شناسه منبع یکسان بارگذاری پس‌از یک هفته منقضی می‌شود.

مرحله ۱: شروع جلسه ازسرگرفتنی

برای شروع بارگذاری قابل‌ازسرگیری، درخواست POST یا PUT به URI /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 تنظیم کنید.

بخش بعدی نحوه مدیریت پاسخ را شرح می‌دهد.

مرحله ۲: ذخیره کردن URI جلسه ازسرگرفتنی

اگر درخواست شروع جلسه موفقیت‌آمیز باشد، سرور API با رمز وضعیت HTTP 200 OK پاسخ می‌دهد. علاوه‌براین، سرصفحه Location را ارائه می‌دهد که URI جلسه ازسرگرفتنی شما را مشخص می‌کند. سرصفحه Location، که در مثال زیر نشان داده شده است، شامل بخش پارامتر پُرسمان upload_id است که شناسه بارگذاری یکتایی را برای استفاده در این جلسه ارائه می‌دهد.

مثال: پاسخ شروع جلسه ازسرگرفتنی

پاسخ به درخواست در مرحله ۱ در اینجا آمده است:

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 برای بارگذاری واقعی فایل یا پرس‌وجو درباره وضعیت بارگذاری استفاده خواهید کرد.

شناسه منبع یکسان جلسه را کپی و ذخیره کنید تا بتوانید از آن برای درخواست‌های بعدی استفاده کنید.

مرحله ۳: بارگذاری فایل

برای بارگذاری فایل، درخواست PUT را به URI بارگذاری که در مرحله قبل دریافت کردید ارسال کنید. قالب درخواست بارگذاری به‌صورت زیر است:

PUT session_uri

سرصفحه‌های HTTP که باید هنگام درخواست بارگذاری فایل قابل ازسرگیری استفاده شوند شامل Content-Length است. این را روی تعداد بایت‌هایی که در این درخواست بارگذاری می‌کنید تنظیم کنید، که معمولاً اندازه فایل بارگذاری است.

مثال: درخواست بارگذاری فایل قابل ازسرگیری

در اینجا یک درخواست قابل‌ازسرگیری برای بارگذاری کل فایل پیام ایمیل ۲٬۰۰۰٬۰۰۰ بایتی برای مثال فعلی آورده شده است.

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 خالی به URI بارگذاری، وضعیت فعلی بارگذاری را پُرسمان کنید. برای این درخواست، سرایندهای HTTP باید شامل سرایند Content-Range باشند که نشان می‌دهد موقعیت فعلی در فایل نامشخص است.  برای مثال، اگر طول کل فایل شما ۲٬۰۰۰٬۰۰۰ است، Content-Range را روی */2000000 تنظیم کنید. اگر اندازه کامل فایل را نمی‌دانید، Content-Range را روی */* تنظیم کنید.

    توجه: می‌توانید وضعیت را بین تکه‌ها درخواست کنید، نه فقط زمانی که بارگذاری قطع می‌شود. این کار برای مثال زمانی مفید است که بخواهید نشانگرهای پیشرفت بارگذاری را برای مرورگرهای قدیمی نشان دهید.

  2. دریافت تعداد بایت‌های بارگذاری‌شده. پاسخ پُرسمان وضعیت را پردازش کنید. سرور از سرصفحه Range در پاسخ خود استفاده می‌کند تا مشخص کند تاکنون کدام بایت‌ها را دریافت کرده است.  برای مثال، سرایند Range از 0-299999 نشان می‌دهد که ۳۰۰٬۰۰۰ بایت اول فایل دریافت شده است.
  3. بارگذاری داده‌های باقیمانده. درنهایت، اکنون که می‌دانید از کجا درخواست را ازسر بگیرید، داده‌های باقی‌مانده یا بخش فعلی را ارسال کنید. توجه داشته باشید که در هر دو حالت باید با داده‌های باقی‌مانده به‌عنوان یک بخش جداگانه رفتار کنید، بنابراین هنگام ازسرگیری بارگذاری باید سرصفحه Content-Range را ارسال کنید.
مثال: ازسر گرفتن بارگذاری قطع‌شده

۱) وضعیت بارگذاری را درخواست کنید.

درخواست زیر از سرصفحه Content-Range استفاده می‌کند تا نشان دهد موقعیت فعلی در فایل ۲٬۰۰۰٬۰۰۰ بایتی نامشخص است.

PUT {session_uri} HTTP/1.1
Content-Length: 0
Content-Range: bytes */2000000

۲) تعداد بایت‌های بارگذاری‌شده تاکنون را از پاسخ استخراج کنید.

پاسخ سرور از سرصفحه Range استفاده می‌کند تا نشان دهد که تاکنون ۴۳ بایت اول فایل را دریافت کرده است. از مقدار بالایی سرصفحه Range برای تعیین محل شروع بارگذاری ازسرگرفته‌شده استفاده کنید.

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

توجه: اگر بارگذاری کامل شده باشد، ممکن است پاسخ وضعیت 201 Created یا 200 OK باشد. این اتفاق ممکن است زمانی رخ دهد که اتصال پس‌از بارگذاری همه بایت‌ها اما قبل‌از دریافت پاسخ از سرور توسط کارخواه قطع شود.

۳) بارگذاری را از نقطه‌ای که متوقف شده بود ازسر بگیرید.

درخواست زیر با ارسال بایت‌های باقی‌مانده فایل، از بایت ۴۳، بارگذاری را ازسر می‌گیرد.

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. ۱ ثانیه + random_number_milliseconds صبر کنید و درخواست را دوباره امتحان کنید.
  4. پاسخ HTTP 503 را دریافت کنید که نشان می‌دهد باید درخواست را دوباره امتحان کنید.
  5. ‫۲ ثانیه + random_number_milliseconds صبر کنید و درخواست را دوباره امتحان کنید.
  6. پاسخ HTTP 503 را دریافت کنید که نشان می‌دهد باید درخواست را دوباره امتحان کنید.
  7. Wait 4 seconds + random_number_milliseconds, and retry the request.
  8. پاسخ HTTP 503 را دریافت کنید که نشان می‌دهد باید درخواست را دوباره امتحان کنید.
  9. ‫۸ ثانیه + random_number_milliseconds صبر کنید و درخواست را دوباره امتحان کنید.
  10. پاسخ HTTP 503 را دریافت کنید که نشان می‌دهد باید درخواست را دوباره امتحان کنید.
  11. ‫۱۶ ثانیه + random_number_milliseconds صبر کنید و درخواست را دوباره امتحان کنید.
  12. ایست. خطایی را گزارش یا ثبت کنید.

در جریان بالا، random_number_milliseconds عدد تصادفی از میلی‌ثانیه‌های کمتر یا برابر با ۱۰۰۰ است. این کار ضروری است، زیرا ایجاد یک تأخیر تصادفی کوچک به توزیع یکنواخت‌تر بار کمک می‌کند و از احتمال هجوم به سرور جلوگیری می‌کند. مقدار random_number_milliseconds باید پس‌از هر انتظار بازتعریف شود.

توجه: زمان انتظار همیشه (2 ^ n) + random_number_milliseconds است، که n عدد صحیح یکنواخت افزایشی است که در ابتدا 0 تعریف شده است. عدد صحیح n برای هر تکرار (هر درخواست) ۱ عدد افزایش می‌یابد.

الگوریتم طوری تنظیم شده است که وقتی n برابر با ۵ است خاتمه یابد. این سقف مانع از آن می‌شود که کارخواه‌ها به‌طور نامحدود دوباره امتحان کنند و منجر به تأخیر کلی حدود ۳۲ ثانیه می‌شود تا اینکه درخواست «خطای غیرقابل‌بازیابی» تلقی شود. حداکثر تعداد دفعات تلاش مجدد بیشتر مشکلی ندارد، به‌ویژه اگر بارگذاری طولانی درحال انجام باشد؛ فقط مطمئن شوید که تأخیر تلاش مجدد را به چیزی معقول، مثلاً کمتر از یک دقیقه، محدود کنید.

راهنماهای کتابخانه کارخواه میانای برنامه‌سازی کاربردی