إجراء تحميل قابل للاستئناف

توضّح هذه الصفحة كيفية إرسال طلب تحميل قابل للاستئناف في 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 لجلسة قابلة للاستئناف بعد 7 أيام.

انسخ عنوان 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 ميبابايت (MiB)، باستثناء الجزء الأخير الذي يُكمل عملية التحميل. حافظ على حجم الجزء بأكبر قدر ممكن حتى تكون عملية التحميل فعّالة.

3. أضِف عناوين HTTP التالية:

   • Content-Length: اضبط القيمة على عدد وحدات البايت في الجزء.
   • X-Goog-Upload-Command: اضبط القيمة على upload. بالنسبة إلى الجزء الأخير، اضبط القيمة على upload, finalize.
   • X-Goog-Upload-Offset: اضبط القيمة على الإزاحة التي يجب كتابة وحدات البايت عندها. يُرجى العِلم أنّه يجب تحميل وحدات البايت بالتسلسل.

4. أرسِل الطلب. إذا تمّت مقاطعة طلب التحميل أو إذا تلقّيت ردًا 5xx، اتّبِع الإجراءات الواردة في مقال استئناف عملية تحميل تمّت مقاطعتها.

5. كرِّر الخطوات من 1 إلى 4 لكل جزء متبقٍّ في الملف.

مثال: تحميل الملف

طلب واحد

يوضّح المثال التالي طلبًا قابلاً للاستئناف لتحميل ملف JPEG كامل بحجم 4,200,000 بايت في طلب واحد، باستخدام عنوان 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 بحجم 4,200,000 بايت في أجزاء متعدّدة، باستخدام عنوان URL للجلسة القابلة للاستئناف ودقة الحجم اللذَين تم الحصول عليهما في الخطوة السابقة. يستخدم هذا المثال حجم جزء يبلغ 2097000 بايت، وهو من مضاعفات 2 ميبابايت (MiB).

الجزء الأول:

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

يمكنك بعد ذلك استئناف التحميل عند هذه الإزاحة. يجب استئناف التحميل عند الإزاحة التي يقدّمها الخادم، إلا إذا أرسلت أمرًا مجمّعًا للتحميل والإكمال، وفي هذه الحالة يمكنك أيضًا استئناف التحميل عند الإزاحة 0.

إذا كان عنوان X-Goog-Upload-Status في استجابة HTTP لأمر طلب البحث متوفّرًا وكانت القيمة ليست active، يعني ذلك أنّه تم إنهاء عملية التحميل من قبل.