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

این صفحه نحوه ارسال درخواست آپلود با قابلیت از سرگیری را در 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. درخواست را ارسال کنید.

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

مثال زیر نحوه شروع یک session با قابلیت از سرگیری برای آپلود یک فایل جدید را نشان می‌دهد. در این حالت، فایل یک تصویر است و تعداد کل بایت‌های موجود در فایل ۴۲۰۰۰۰۰ است. توجه داشته باشید که بدنه درخواست خالی است؛ بنابراین، هدر Content-Length روی ۰ تنظیم شده است.

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) قابل از سرگیری را کپی و ذخیره کنید تا بتوانید برای درخواست‌های بعدی از آن استفاده کنید.

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

چندین تکه

برای آپلود فایل در چند بخش:

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

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

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

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

  5. مراحل ۱ تا ۴ را برای هر بخش باقی‌مانده در فایل تکرار کنید.

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

درخواست تکی

مثال زیر یک درخواست از سرگیری برای آپلود کل یک فایل JPEG با حجم ۴,۲۰۰,۰۰۰ بایت را در یک درخواست واحد، با استفاده از 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 با حجم ۴,۲۰۰,۰۰۰ بایت را در چندین تکه، با استفاده از URL جلسه از سرگیری و جزئیات اندازه به دست آمده در مرحله قبل، نشان می‌دهد. این مثال از اندازه تکه‌ای برابر با ۲۰۹۷۰۰۰ بایت استفاده می‌کند که مضربی از ۲ مگابایت (مبی بایت) است.

تکه اول:

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]

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

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

  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

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

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