آپلودهای قابل ازسرگیری

این صفحه نحوه ایجاد درخواست بارگذاری مجدد در Google Photos Library API از طریق پروتکل REST را شرح می دهد. این پروتکل به شما این امکان را می دهد که پس از یک شکست ارتباطی که جریان داده ها را قطع می کند، عملیات آپلود را از سر بگیرید.

از گزینه آپلود مجدد استفاده کنید اگر:

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

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

مرحله 1: شروع یک جلسه آپلود

با ارسال یک درخواست POST به https://photoslibrary.googleapis.com/v1/uploads ، یک جلسه آپلود قابل ازسرگیری را آغاز کنید. با استفاده از URL آپلود قابل ازسرگیری که در این درخواست بازگردانده شده است، فایل را آپلود کنید.

درخواست POST باید شامل سرصفحه های زیر باشد:

فیلدهای سرصفحه
Content-Length با خالی بودن بدنه درخواست، روی 0 تنظیم کنید.
X-Goog-Upload-Command برای start تنظیم کنید.
X-Goog-Upload-Content-Type نوع mime فایل را تنظیم کنید، به عنوان مثال، image/jpeg .
X-Goog-Upload-Protocol روی resumable تنظیم کنید.
X-Goog-Upload-Raw-Size تعداد کل بایت های داده فایلی که باید منتقل شود را تنظیم کنید.

در اینجا یک عنوان درخواست POST وجود دارد:

POST https://photoslibrary.googleapis.com/v1/uploads
Authorization: Bearer oauth2-token
Content-Length: 0
X-Goog-Upload-Command: start
X-Goog-Upload-Content-Type: mime-type
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Raw-Size: bytes-of-file

مرحله 2: ذخیره URL جلسه

در صورت موفقیت آمیز بودن، درخواست POST یک کد وضعیت HTTP 200 OK ، شامل هدر زیر را برمی گرداند.

X-Goog-Upload-URL: url-to-make-uploads-to
X-Goog-Upload-Chunk-Granularity: chunk-granularity-in-bytes

فیلد سرصفحه x-goog-upload-chunk-granularity حاوی تراز بایت و دانه بندی اندازه برای تمام تکه های داده ارسال شده توسط مشتری است. اگر آپلود در چند تکه انجام شود، همه آپلودها، به جز آخرین بارگذاری، باید در مضرب این مقدار انجام شوند. یعنی بایت های آپلود فایل باید با این مقدار تراز شوند. در آخرین قطعه، می توانید بایت های باقی مانده را آپلود کنید.

فیلد سرصفحه X-Goog-Upload-URL حاوی یک URL منحصر به فرد است که باید برای تکمیل آپلود در تمام درخواست های باقیمانده استفاده شود. این URL جلسه قابل ازسرگیری را کپی و ذخیره کنید تا بتوانید برای درخواست های بعدی از آن استفاده کنید.

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

دو راه برای آپلود یک فایل با یک جلسه مجدد وجود دارد:

  1. در یک درخواست واحد این رویکرد معمولا بهترین است، زیرا به درخواست های کمتری نیاز دارد و در نتیجه عملکرد بهتری دارد.

  2. در چند تکه در این رویکرد، آپلودها در چندین درخواست با تقسیم کردن داده ها انجام می شود. داده ها در مضرب x-goog-upload-chunk-granularity تکه تکه می شوند. در صورت لزوم، درخواست های تکه تکه شده را می توان دوباره امتحان کرد.

    از این روش استفاده کنید اگر:

    • شما باید مقدار داده های منتقل شده در هر درخواست را کاهش دهید. ممکن است لازم باشد این کار را زمانی انجام دهید که یک محدودیت زمانی ثابت برای درخواست‌های فردی وجود داشته باشد.
    • شما باید یک نشانگر سفارشی ارائه دهید که پیشرفت آپلود را نشان دهد.
    • باید بدانید چه زمانی دور انداختن داده ها ایمن است.

درخواست تک

برای آپلود فایل در یک درخواست:

  1. یک درخواست POST به URL جلسه قابل ازسرگیری ایجاد کنید.
  2. داده های فایل را به بدنه درخواست اضافه کنید.

  3. هدرهای HTTP زیر را اضافه کنید:

    • Content-Length : روی تعداد بایت های فایل تنظیم کنید.
    • X-Goog-Upload-Command : برای upload, finalize تنظیم کنید.

  4. درخواست را ارسال کنید.

اگر درخواست آپلود قطع شد یا یک پاسخ 5xx دریافت کردید، رویه را در Resuming an interrupted upload دنبال کنید.

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

چند تکه

برای آپلود فایل در چند تکه:

  1. یک درخواست POST به URL جلسه قابل ازسرگیری ایجاد کنید.

  2. داده های قطعه را به بدنه درخواست اضافه کنید.

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

  3. هدرهای HTTP زیر را اضافه کنید:

    • Content-Length : روی تعداد بایت ها در قطعه تنظیم کنید.
    • X-Goog-Upload-Command : برای upload تنظیم کنید. برای آخرین تکه، برای upload, finalize .
    • X-Goog-Upload-Offset : روی افستی که بایت ها باید نوشته شوند تنظیم کنید. توجه داشته باشید که بایت ها باید به صورت سریال آپلود شوند. اولین افست 0 است.
  4. درخواست را ارسال کنید.

    اگر درخواست آپلود قطع شد یا یک پاسخ 5xx دریافت کردید، رویه را در Resuming an interrupted upload دنبال کنید.

  5. این مراحل را برای هر تکه باقی مانده در فایل تکرار کنید.

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

مثال

درخواست تک

مثال زیر یک درخواست قابل ازسرگیری برای آپلود یک فایل JPEG 3,039,417 بایتی در یک درخواست را نشان می دهد.

POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1
Content-Length: 0
X-Goog-Upload-Command: start
X-Goog-Upload-Content-Type: image/jpeg
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Raw-Size: 3039417
[no body]

پاسخ حاوی URL آپلود و اندازه قطعه مورد انتظار است:

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable
X-Goog-Upload-Chunk-Granularity: 262144

درخواست آپلود نهایی:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 3039417
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0

[BYTES 0-4199999]

چند تکه

مثال زیر یک درخواست قابل ازسرگیری برای آپلود یک فایل JPEG 3,039,417 بایتی در چند تکه، با استفاده از URL جلسه قابل ازسرگیری و جزئیات پذیرفته شده اندازه تکه به دست آمده در مرحله قبل را نشان می دهد. این مثال از یک اندازه 262144 بایت استفاده می کند که در قسمت هدر، x-goog-upload-chunk-granularity ، زمانی که جلسه آپلود مقداردهی اولیه شد، برگردانده شد. توجه داشته باشید که هر بارگذاری حاوی بایت هایی است که مضربی از 262144 هستند.

برای دریافت URL آپلود و اندازه قطعه همانطور که در مرحله قبل توضیح داده شد، جلسه آپلود را راه اندازی کنید:

POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1
Content-Length: 0
X-Goog-Upload-Command: start
X-Goog-Upload-Content-Type: image/jpeg
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Raw-Size: 3039417
[no body]

پاسخ حاوی URL آپلود و اندازه قطعه مورد انتظار است:

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable
X-Goog-Upload-Chunk-Granularity: 262144

تکه اول:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 1048576
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0

[BYTES 0-1048575]

تکه دوم:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 1048576
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 1048576

[BYTES 1048576-2097151]

آخرین تکه: 

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 942265
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 2097152

[BYTES 2097152-4200000]

از سرگیری آپلود قطع شده

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

در اینجا یک درخواست POST به URL جلسه قابل ازسرگیری است. X-Goog-Upload-Command باید روی query تنظیم شود. 

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 0
X-Goog-Upload-Command: query

پاسخ سرور شامل یک کد وضعیت HTTP 200 OK و اندازه فعلی آپلود است. 

HTTP/1.1 200 OK
X-Goog-Upload-Status: active
X-Goog-Upload-Size-Received: 100

سپس می توانید بارگذاری را با این افست از سر بگیرید. شما باید با آفست ارائه شده توسط سرور از سر بگیرید، مگر اینکه یک فرمان ترکیبی آپلود و نهایی را ارسال کنید، در این صورت می توانید با آفست 0 نیز ادامه دهید.

اگر هدر X-Goog-Upload-Status در پاسخ HTTP فرمان درخواست شما وجود داشته باشد و مقدار آن active نباشد، نشان می دهد که آپلود قبلاً خاتمه یافته است.