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

توضّح هذه الصفحة كيفية تقديم طلب تحميل قابل للاستئناف في واجهة برمجة التطبيقات لخدمة "التجوّل الافتراضي" Publish API. يتيح لك هذا البروتوكول استئناف عملية تحميل بعد أن يؤدي أحد أخطاء الاتصالات إلى إيقاف تدفق البيانات. استخدِم هذا الخيار في الحالات التالية:

  • إذا كنت تحمّل ملفات كبيرة
  • يكون احتمال انقطاع الاتصال بالشبكة أو حدوث أي مشكلة أخرى في الإرسال هو مرتفع (على سبيل المثال، إذا كنت تحمّل ملفًا من تطبيق متوافق مع الأجهزة الجوّالة).

يمكن أن تقلل عمليات التحميل القابلة للاستئناف أيضًا من استخدام معدل نقل البيانات عند حدوث تعطُّل في الشبكة، لأنّه ليس عليك إعادة بدء عمليات تحميل الملفات الكبيرة من الصفر.

إذا كنت ترسل ملفات صغيرة عبر اتصال شبكة موثوق به، يمكنك استخدامتحميل بسيط بدلاً من ذلك.

بدء جلسة تحميل قابلة للاستئناف

بعد الحصول على uploadUrl، يمكنك بدء جلسة upload قابلة للاستئناف:

  1. أنشئ طلب POST إلى uploadUrl.

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

    • X-Goog-Upload-Protocol: تم الضبط على resumable.
    • X-Goog-Upload-Header-Content-Length: يتم ضبطه على إجمالي عدد وحدات البايت في بيانات الملف، والتي سيتم نقلها في الطلبات اللاحقة.
    • X-Goog-Upload-Header-Content-Type: اضبطه على نوع MIME للملف data.
    • 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. في عدّة أجزاء استخدِم هذا الأسلوب في الحالات التالية:
    • عليك تقليل كمية البيانات المنقولة في أي طلب فردي. قد تحتاج إلى إجراء ذلك عندما يكون هناك حدّ زمني ثابت لطلبات individual .
    • يجب تقديم مؤشر مخصّص يعرض مستوى تقدّم التحميل.
    • يجب معرفة الحالات التي يكون فيها من الآمن تجاهل البيانات.

طلب واحد

لتحميل الملف في طلب واحد:

  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 بحجم 4,200,000 بايت في أجزاء متعددة، باستخدام عنوان 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، يعني ذلك أنّه سبق أن تم إنهاء عملية التحميل.