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

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

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

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

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

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

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

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

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

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

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

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

مثال

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]

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]

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]

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 نباشد، نشان می دهد که آپلود قبلاً خاتمه یافته است.