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

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

مثال: حفظ عنوان 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. كرر الخطوات من 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 بحجم 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]

استئناف تحميل تمت مقاطعته

في حال مقاطعة طلب التحميل أو تلقّي رمز حالة 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، هذا يعني أنّه سبق وتم إنهاء عملية التحميل.