انجام یک بارگذاری مجدد

این صفحه نحوه ایجاد یک درخواست آپلود قابل ازسرگیری را در Street View Publish API توضیح می‌دهد. این پروتکل به شما این امکان را می دهد که پس از یک شکست ارتباطی که جریان داده ها را قطع می کند، عملیات آپلود را از سر بگیرید. از این گزینه استفاده کنید اگر:

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

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

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

شروع یک جلسه آپلود قابل ازسرگیری

پس از به دست آوردن uploadUrl ، می توانید یک جلسه آپلود مجدد را شروع کنید:

  1. یک درخواست POST به uploadUrl ایجاد کنید.

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

    • X-Goog-Upload-Protocol : روی resumable تنظیم کنید.
    • X-Goog-Upload-Header-Content-Length : تعداد کل بایت های داده فایل را تنظیم کنید که در درخواست های بعدی منتقل می شود.
    • X-Goog-Upload-Header-Content-Type : نوع MIME داده فایل را تنظیم کنید.
    • X-Goog-Upload-Command : برای start تنظیم کنید.

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

مثال: شروع یک جلسه آپلود قابل ازسرگیری

مثال زیر نشان می دهد که چگونه می توان یک جلسه از سرگیری برای آپلود یک فایل جدید را آغاز کرد. در این حالت فایل یک تصویر است و تعداد کل بایت های فایل 4200000 است. توجه داشته باشید که بدنه درخواست خالی است. بنابراین، هدر Content-Length روی 0 تنظیم شده است.

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234 HTTP/1.1
Authorization: Bearer [YOUR_AUTH_TOKEN]
Content-Length: 0
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Header-Content-Length: 4200000
X-Goog-Upload-Header-Content-Type: image/jpeg
X-Goog-Upload-Command: start

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

در حال ذخیره URL جلسه قابل ازسرگیری

برای درخواست ارسال شده برای شروع یک جلسه آپلود مجدد، سرور با یک کد وضعیت HTTP 200 OK ، شامل سرصفحه زیر پاسخ می دهد:

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

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

مثال: ذخیره URL جلسه قابل ازسرگیری

مثال زیر پاسخی را نشان می دهد که شامل URL جلسه قابل ازسرگیری و نیاز به جزئیات اندازه است.

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable

در حال آپلود فایل

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

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

درخواست تک

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

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

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

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

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

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

چند تکه

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

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

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

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

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

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

مثال: آپلود فایل

درخواست تک

مثال زیر یک درخواست قابل ازسرگیری برای آپلود کل فایل JPEG 4200000 بایتی در یک درخواست را با استفاده از URL جلسه قابل ازسرگیری که در مرحله قبل به دست آمد نشان می دهد:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 4200000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0

[BYTES 0-4199999]

اگر درخواست موفق شد، یک کد وضعیت HTTP 200 OK دریافت می کنید.

چند تکه

مثال زیر یک درخواست قابل ازسرگیری برای آپلود یک فایل JPEG با حجم 4200000 بایت در چند تکه با استفاده از URL جلسه قابل ازسرگیری و جزئیات اندازه بدست آمده در مرحله قبل را نشان می دهد. این مثال از یک اندازه 2097000 بایت استفاده می کند که مضرب 2 مگابایت (مبی بایت) است.

تکه اول:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0



[BYTES 0-2096999]

تکه دوم:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 2097000
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 2097000



[BYTES 2097000-4193999]

آخرین تکه:

POST https://streetviewpublish.googleapis.com/media/user/123456789/photo/01234?upload_id=AEnB2U&upload_protocol=resumable HTTP/1.1
Content-Length: 6000
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 4194000



[BYTES 4194000-4200000]

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

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

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

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