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

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

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

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

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

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

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

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

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

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

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

  مثال: 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 . روی یکی از انواع داده رسانه آپلود پذیرفته شده توسط متد، که در مرجع API مشخص شده است، تنظیم می‌شود.
• Content-Length . روی تعداد بایت‌هایی که آپلود می‌کنید تنظیم می‌شود. اگر از کدگذاری انتقال تکه‌ای (chunked transfer encoding) استفاده می‌کنید، لازم نیست.

مثال: آپلود ساده

مثال زیر نحوه‌ی استفاده از یک درخواست آپلود ساده برای 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
}

آپلود چند قسمتی

اگر می‌خواهید فراداده‌ای (metadata) را همراه با داده‌ها برای آپلود ارسال کنید، می‌توانید یک درخواست 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 رسانه‌ی پذیرفته‌شده و محدودیت‌های اندازه‌ی فایل‌های آپلود شده، به مرجع API مراجعه کنید.

توجه: برای ایجاد یا به‌روزرسانی بخش فراداده، بدون بارگذاری داده‌های مرتبط، کافیست یک درخواست 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 آپلود پس از یک هفته منقضی می‌شود.

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

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

مثال: درخواست شروع جلسه قابل از سرگیری

مثال زیر نحوه‌ی آغاز یک session با قابلیت از سرگیری برای 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 ، همانطور که در پاسخ مثال بالا نشان داده شده است، همان URI جلسه‌ای است که شما به عنوان نقطه پایانی HTTP برای انجام آپلود فایل واقعی یا پرس و جو در مورد وضعیت آپلود استفاده خواهید کرد.

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

مرحله ۳: آپلود فایل

برای آپلود فایل، یک درخواست 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 دیگری از سرور دریافت کردید، رویه ذکر شده در resume an interrupted upload را دنبال کنید.

---

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

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

برای اطلاعات بیشتر گسترش دهید

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

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

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

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

درخواستی که ۵۲۴۲۸۸ بایت اول را ارسال می‌کند، ممکن است چیزی شبیه به این باشد:

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 هر تکه فایل قطع شد یا اگر پاسخ HTTP 503 Service Unavailable یا هر پاسخ 5xx دیگری از سرور دریافت کردید، رویه ذکر شده در resume an interrupted upload را دنبال کنید، اما به جای آپلود بقیه فایل، به سادگی آپلود تکه‌ها را از آن نقطه ادامه دهید.

نکات مهم:

• حتماً از سرآیند Range در پاسخ برای تعیین محل شروع بخش بعدی استفاده کنید؛ فرض نکنید که سرور تمام بایت‌های ارسالی در درخواست قبلی را دریافت کرده است.
• هر URI آپلود طول عمر محدودی دارد و در نهایت منقضی می‌شود (در صورت عدم استفاده، ظرف یک روز یا بیشتر). به همین دلیل، بهتر است به محض دریافت URI آپلود، آپلود قابل از سرگیری را شروع کنید و آپلود قطع شده را کمی پس از وقوع وقفه از سر بگیرید.
• اگر درخواستی با شناسه جلسه آپلود منقضی شده ارسال کنید، سرور کد وضعیت 404 Not Found را برمی‌گرداند. هنگامی که خطای غیرقابل بازیابی در جلسه آپلود رخ می‌دهد، سرور کد وضعیت 410 Gone را برمی‌گرداند. در این موارد، باید یک آپلود قابل از سرگیری جدید را شروع کنید، یک URI آپلود جدید دریافت کنید و آپلود را از ابتدا با استفاده از نقطه پایانی جدید شروع کنید.

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

---

از سرگیری آپلود متوقف شده

اگر درخواست آپلود قبل از دریافت پاسخ خاتمه یابد یا اگر پاسخ HTTP 503 Service Unavailable را از سرور دریافت کنید، باید آپلود متوقف شده را از سر بگیرید. برای انجام این کار:

1. درخواست وضعیت. با ارسال یک درخواست PUT خالی به آدرس URL آپلود، وضعیت فعلی آپلود را بررسی کنید. برای این درخواست، هدرهای HTTP باید شامل یک هدر Content-Range باشند که نشان می‌دهد موقعیت فعلی در فایل ناشناخته است. برای مثال، اگر طول کل فایل شما ۲,۰۰۰,۰۰۰ است Content-Range را روی */2000000 تنظیم کنید. اگر اندازه کامل فایل را نمی‌دانید، Content-Range روی */* تنظیم کنید.

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

2. تعداد بایت‌های آپلود شده را دریافت کنید. پاسخ حاصل از پرس‌وجوی وضعیت را پردازش کنید. سرور از سرآیند Range در پاسخ خود برای مشخص کردن بایت‌هایی که تاکنون دریافت کرده است استفاده می‌کند. به عنوان مثال، سرآیند Range با مقدار 0-299999 نشان می‌دهد که 300000 بایت اول فایل دریافت شده است.
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 مشاهده شد، از استراتژی backoff نمایی استفاده کنید. این خطاها می‌توانند در صورت بارگذاری بیش از حد سرور رخ دهند. backoff نمایی می‌تواند به کاهش این نوع مشکلات در دوره‌های حجم بالای درخواست‌ها یا ترافیک سنگین شبکه کمک کند.
• انواع دیگر درخواست‌ها نباید با روش بازگشت نمایی مدیریت شوند، اما همچنان می‌توانید تعدادی از آنها را دوباره امتحان کنید. هنگام امتحان مجدد این درخواست‌ها، تعداد دفعات امتحان مجدد آنها را محدود کنید. به عنوان مثال، کد شما می‌تواند قبل از گزارش خطا، ده بار امتحان مجدد یا کمتر را محدود کند.
• هنگام انجام آپلودهای قابل از سرگیری، با شروع کل آپلود از ابتدا، خطاهای 404 Not Found و 410 Gone را مدیریت کنید.

عقب‌نشینی نمایی

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

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

جریان پیاده‌سازی backoff نمایی ساده به شرح زیر است:

1. یک درخواست به API ارسال کنید.
2. یک پاسخ HTTP 503 دریافت کنید، که نشان می‌دهد باید درخواست را دوباره امتحان کنید.
3. ۱ ثانیه + عدد_تصادفی_میلی_ثانیه صبر کنید و درخواست را دوباره امتحان کنید.
4. یک پاسخ HTTP 503 دریافت کنید، که نشان می‌دهد باید درخواست را دوباره امتحان کنید.
5. ۲ ثانیه + عدد تصادفی_میلی‌ثانیه صبر کنید و درخواست را دوباره امتحان کنید.
6. یک پاسخ HTTP 503 دریافت کنید، که نشان می‌دهد باید درخواست را دوباره امتحان کنید.
7. ۴ ثانیه + عدد_تصادفی_میلی_ثانیه صبر کنید و درخواست را دوباره امتحان کنید.
8. یک پاسخ HTTP 503 دریافت کنید، که نشان می‌دهد باید درخواست را دوباره امتحان کنید.
9. ۸ ثانیه + عدد تصادفی_میلی‌ثانیه صبر کنید و درخواست را دوباره امتحان کنید.
10. یک پاسخ HTTP 503 دریافت کنید، که نشان می‌دهد باید درخواست را دوباره امتحان کنید.
11. ۱۶ ثانیه + عدد تصادفی_میلی‌ثانیه صبر کنید و درخواست را دوباره امتحان کنید.
12. توقف. گزارش یا ثبت خطا.

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

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

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

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

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