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

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

گزینه های آپلود

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

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

شما می توانید درخواست های آپلود را به یکی از روش های زیر ارسال کنید. روشی را که با پارامتر درخواست uploadType استفاده می کنید، مشخص کنید.

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

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

• URI / آپلود، برای رسانه. قالب نقطه پایانی آپلود، URI منبع استاندارد با پیشوند "/upload" است. از این URI هنگام انتقال خود داده رسانه استفاده کنید.

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

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

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

آپلود ساده

ساده ترین روش برای آپلود فایل، درخواست آپلود ساده است. این گزینه زمانی انتخاب خوبی است که:

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

برای استفاده از آپلود ساده، یک درخواست POST یا PUT به /upload URI روش ارسال کنید و پارامتر query uploadType=media اضافه کنید. به عنوان مثال:

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

هدرهای HTTP برای استفاده در هنگام درخواست آپلود ساده عبارتند از:

• Content-Type روی یکی از انواع داده های رسانه آپلود پذیرفته شده روش، که در مرجع API مشخص شده است، تنظیم کنید.
• 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 URI متد ارسال کنید و پارامتر query uploadType=multipart را اضافه کنید، برای مثال:

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

هدرهای سطح بالای HTTP برای استفاده در هنگام درخواست آپلود چند قسمتی عبارتند از:

• Content-Type . روی چندبخشی/مرتبط تنظیم کنید و رشته مرزی را که برای شناسایی بخش‌های درخواست استفاده می‌کنید، اضافه کنید.
• Content-Length . تعداد کل بایت ها را در بدنه درخواست تنظیم کنید. بخش رسانه درخواست باید کمتر از حداکثر اندازه فایل مشخص شده برای این روش باشد.

بدنه درخواست به عنوان یک نوع محتوای multipart/related [ RFC2387 ] فرمت شده است و دقیقاً شامل دو بخش است. قسمت ها با یک رشته مرزی مشخص می شوند و رشته مرزی نهایی با دو خط فاصله دنبال می شود.

هر بخش از درخواست چند قسمتی به یک سرصفحه Content-Type اضافی نیاز دارد:

1. بخش فراداده: باید اول باشد و Content-Type باید با یکی از قالب‌های فراداده پذیرفته شده مطابقت داشته باشد.
2. بخش رسانه: باید در رتبه دوم قرار گیرد و Content-Type باید با انواع MIME رسانه پذیرفته شده روش مطابقت داشته باشد.

مرجع API را برای لیست هر روش از انواع 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 جلسه قابل تجدید ارسال کنید.

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

توجه: URI آپلود پس از یک هفته منقضی می شود.

مرحله 1: یک جلسه قابل ازسرگیری را شروع کنید

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

مرجع API را برای لیست هر روش از انواع 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: URI جلسه قابل تجدید را ذخیره کنید

اگر درخواست شروع جلسه با موفقیت انجام شود، سرور API با یک کد وضعیت HTTP 200 OK پاسخ می دهد. علاوه بر این، یک هدر Location ارائه می کند که URI جلسه قابل ازسرگیری شما را مشخص می کند. سرصفحه Location ، که در مثال زیر نشان داده شده است، شامل بخش پارامتر query 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 ، همانطور که در پاسخ مثال بالا نشان داده شده است، URI جلسه ای است که به عنوان نقطه پایانی 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 دیگری از سرور دریافت کردید، رویه ذکر شده در رزومه آپلود قطع شده را دنبال کنید.

---

آپلود فایل به صورت تکه تکه

با آپلودهای قابل ازسرگیری، می توانید یک فایل را به قطعات تقسیم کنید و یک سری درخواست برای آپلود هر تکه به ترتیب ارسال کنید. این رویکرد ترجیحی نیست زیرا هزینه‌های عملکرد مرتبط با درخواست‌های اضافی وجود دارد و معمولاً نیازی به آن نیست. با این حال، ممکن است لازم باشد از chunking برای کاهش مقدار داده های منتقل شده در هر درخواست استفاده کنید. این زمانی مفید است که محدودیت زمانی ثابتی برای درخواست‌های فردی وجود داشته باشد، همانطور که برای کلاس‌های خاصی از درخواست‌های موتور برنامه Google صادق است. همچنین به شما امکان می دهد کارهایی مانند ارائه نشانه های پیشرفت آپلود برای مرورگرهای قدیمی که به طور پیش فرض از پیشرفت آپلود پشتیبانی نمی کنند، انجام دهید.

برای اطلاعات بیشتر باز کنید

اگر داده‌ها را به صورت تکه‌ای آپلود می‌کنید، هدر Content-Range به همراه سرصفحه Content-Length مورد نیاز برای آپلود فایل کامل نیز لازم است:

• Content-Length . همانطور که برای آخرین درخواست ممکن است روی اندازه تکه یا احتمالاً کمتر تنظیم کنید.
• Content-Range : تنظیم کنید تا نشان دهد کدام بایت ها در فایلی که آپلود می کنید. به عنوان مثال، Content-Range: bytes 0-524287/2000000 نشان می دهد که شما اولین 524288 بایت (256 x 1024 x 2) را در یک فایل 2000000 بایتی ارائه می کنید.

محدودیت اندازه قطعه: همه تکه‌ها باید مضرب ۲۵۶ کیلوبایت (۱۰۲۴×۲۵۶ بایت) باشند، به جز قسمت نهایی که آپلود را کامل می‌کند. اگر از chunking استفاده می کنید، مهم است که اندازه قطعه را تا حد امکان بزرگ نگه دارید تا بارگذاری کارآمد بماند.

مثال: درخواست آپلود فایل تکه تکه شده قابل ازسرگیری

درخواستی که 524288 بایت اول را ارسال می کند ممکن است به این صورت باشد:

PUT {session_uri} HTTP/1.1
Host: www.googleapis.com
Content-Length: 524288
Content-Type: message/rfc822
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 یا هر پاسخ 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 تنظیم کنید اگر طول کل فایل شما 2000000 باشد. اگر اندازه کامل فایل را نمی دانید، Content-Range روی */* تنظیم کنید.

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

2. دریافت تعداد بایت های آپلود شده پاسخ از پرس و جو وضعیت را پردازش کنید. سرور در پاسخ خود از هدر Range استفاده می کند تا مشخص کند که تا کنون کدام بایت را دریافت کرده است. به عنوان مثال، هدر Range از 0-299999 نشان می دهد که 300000 بایت اول فایل دریافت شده است.
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. یک درخواست به API بدهید.
2. پاسخ HTTP 503 را دریافت کنید، که نشان می دهد باید درخواست را دوباره امتحان کنید.
3. 1 ثانیه + random_number_milliseconds صبر کنید و دوباره درخواست را امتحان کنید.
4. پاسخ HTTP 503 را دریافت کنید، که نشان می دهد باید درخواست را دوباره امتحان کنید.
5. 2 ثانیه + random_number_milliseconds صبر کنید و دوباره درخواست را امتحان کنید.
6. پاسخ HTTP 503 را دریافت کنید، که نشان می دهد باید درخواست را دوباره امتحان کنید.
7. 4 ثانیه + random_number_milliseconds صبر کنید و دوباره درخواست را امتحان کنید.
8. پاسخ HTTP 503 را دریافت کنید، که نشان می دهد باید درخواست را دوباره امتحان کنید.
9. ۸ ثانیه + random_number_milliseconds صبر کنید و دوباره درخواست را امتحان کنید.
10. پاسخ HTTP 503 را دریافت کنید، که نشان می دهد باید درخواست را دوباره امتحان کنید.
11. 16 ثانیه + random_number_milliseconds صبر کنید و دوباره درخواست را امتحان کنید.
12. توقف کنید. یک خطا را گزارش یا ثبت کنید.

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

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

الگوریتم تنظیم شده است تا زمانی که n 5 باشد خاتمه یابد. این سقف مانع از تلاش مجدد مشتریان برای بی نهایت می شود و منجر به تأخیر کلی در حدود 32 ثانیه قبل از اینکه یک درخواست "خطایی غیرقابل جبران" تلقی شود، می شود. حداکثر تعداد بیشتری از تلاش های مجدد خوب است، به خصوص اگر یک آپلود طولانی در حال انجام باشد. فقط مطمئن شوید که تاخیر تلاش مجدد را در چیزی معقول، مثلاً کمتر از یک دقیقه محدود کنید.

راهنمای کتابخانه مشتری API

• دات نت
• جاوا
• PHP
• پایتون
• روبی