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

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