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

توضّح هذه الصفحة كيفية تقديم طلب تحميل قابل للاستئناف إلى Google Photos Library API. عبر بروتوكول REST. يتيح لك هذا البروتوكول استئناف عملية التحميل بعد أن يؤدي تعذُّر الاتصال إلى إيقاف تدفق البيانات.

استخدِم خيار التحميل القابل للاستئناف في الحالات التالية:

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

يمكن أن تقلل عمليات التحميل القابلة للاستئناف من استخدام النطاق الترددي كذلك عند توفر شبكة حيث إنك لا تحتاج إلى إعادة تشغيل عمليات تحميل الملفات الكبيرة من البداية.

الخطوة 1: بدء جلسة تحميل

ابدأ جلسة تحميل قابلة للاستئناف من خلال إرسال طلب POST إلى https://photoslibrary.googleapis.com/v1/uploads. استخدام التحميل القابل للاستئناف عنوان URL المعروض في هذا الطلب، حمِّل الملف.

يجب أن يتضمّن طلب POST العناوين التالية:

حقول العناوين
Content-Length يتم الضبط على 0 لأنّ نص الطلب فارغ.
X-Goog-Upload-Command اضبط النوع على start.
X-Goog-Upload-Content-Type اضبطه على نوع mime للملف، على سبيل المثال، image/jpeg.
X-Goog-Upload-Protocol اضبط النوع على resumable.
X-Goog-Upload-Raw-Size يتم ضبطها على إجمالي عدد وحدات البايت لبيانات الملف المراد ضبطها النقل.

في ما يلي عنوان لطلب POST:

POST https://photoslibrary.googleapis.com/v1/uploads
Authorization: Bearer oauth2-token
Content-Length: 0
X-Goog-Upload-Command: start
X-Goog-Upload-Content-Type: mime-type
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Raw-Size: bytes-of-file

الخطوة 2: حفظ عنوان URL للجلسة

إذا كان الطلب ناجحًا، يعرض طلب POST رمز حالة HTTP‏ 200 OK، بما في ذلك العنوان التالي.

X-Goog-Upload-URL: url-to-make-uploads-to
X-Goog-Upload-Chunk-Granularity: chunk-granularity-in-bytes

يحتوي حقل العنوان x-goog-upload-chunk-granularity على محاذاة البايت ودقّة الحجم لجميع أجزاء البيانات التي يرسلها العميل. إذا تم التحميل في أجزاء متعددة، يجب أن تتم جميع عمليات التحميل، باستثناء عملية التحميل الأخيرة، بمضاعفات هذه القيمة. أي أن وحدات بايت التحميل للملف يجب محاذاته مع هذه القيمة. في الجزء الأخير، يمكنك تحميل الميغابايت المتبقية.

يحتوي حقل الرأس X-Goog-Upload-URL على عنوان URL فريد يجب استخدامه من أجل إكمال التحميل من خلال جميع الطلبات المتبقية. انسخ واحفظ عنوان URL للجلسة التي يمكن استئنافها هذا، حتى تتمكّن من استخدامه في الطلبات اللاحقة.

الخطوة 3: تحميل الملف

هناك طريقتان لتحميل ملف باستخدام جلسة قابلة للاستئناف:

  1. في طلب واحد: عادةً ما يكون هذا النهج هو الأفضل لأنّها تتطلّب طلبات أقلّ، وبالتالي تحقّق أداءً أفضل.

  2. في عدّة أجزاء في هذه الطريقة، يتم إجراء التحميلات في طلبات متعددة عن طريق تقسيم البيانات. يتم تقسيم البيانات في أقسام بمضاعفات x-goog-upload-chunk-granularity. إذا لزم الأمر، يمكن إعادة محاولة الطلبات المقسَّمة.

    استخدِم هذا النهج في الحالات التالية:

    • عليك تقليل كمية البيانات المنقولة في أي طلب واحد . قد تحتاج إلى إجراء ذلك عندما يكون هناك حدّ زمني ثابت للطلبات الفردية.
    • يجب توفير مؤشر مخصّص يعرض حجم التحميل التقدم.
    • يجب معرفة الحالات التي يكون فيها من الآمن تجاهل البيانات.

طلب واحد

لتحميل الملف في طلب واحد، اتّبِع الخطوات التالية:

  1. أنشئ طلب POST لعنوان URL للجلسة القابلة للاستئناف.
  2. أضِف بيانات الملف إلى محتوى الطلب.

  3. أضِف رؤوس HTTP التالية:

    • Content-Length: يتم ضبطه على عدد وحدات البايت في الملف.
    • X-Goog-Upload-Command: تم ضبطها على upload, finalize.

  4. أرسِل الطلب.

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

إذا كان الطلب ناجحًا، ستتلقّى رمز حالة HTTP‏ 200 OK ورمز تنشيط تحميل في نص الاستجابة. أنشئ العنصر الإعلامي باستخدام الرمز المميّز لتحميل المحتوى.

شرائح متعددة

لتحميل الملف في أجزاء متعددة:

  1. أنشئ طلبًا من النوع POST إلى عنوان URL للجلسة التي يمكن استئنافها.

  2. أضِف بيانات المقطع إلى محتوى الطلب.

    باستثناء المقطع الأخير الذي يكمل التحميل، أنشئ إلى أجزاء أخرى في مضاعفات الحجم المقبول للأجزاء. اجعل حجم الجزء أكبر قدر ممكن لكي يكون التحميل فعّالاً.

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

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

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

  5. كرِّر هذه الخطوات لكل جزء متبقٍّ في الملف.

إذا نجح الطلب، ستتلقّى حالة HTTP 200 OK ورمز مميز للتحميل في نص الاستجابة. إنشاء ملف الوسائط باستخدام رمز التحميل هذا.

مثال

طلب واحد

يوضح المثال التالي طلبًا قابلاً للاستئناف لتحميل ملف JPEG بحجم 3039417 بايت في طلب واحد.

POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1
Content-Length: 0
X-Goog-Upload-Command: start
X-Goog-Upload-Content-Type: image/jpeg
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Raw-Size: 3039417
[no body]

يحتوي الردّ على عنوان URL لتحميل البيانات وحجم الجزء المتوقّع:

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable
X-Goog-Upload-Chunk-Granularity: 262144

طلب التحميل النهائي:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 3039417
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 0

[BYTES 0-4199999]

شرائح متعددة

يعرض المثال التالي طلبًا قابلاً للاستئناف لتحميلملف JPEG بحجم 3,039,417 بايت في أجزاء متعددة، باستخدام عنوان URL لجلسة قابلة للاستئناف ومقدار دقة حجم الجزء المقبول الذي تم الحصول عليه في الخطوة السابقة. يستخدم هذا المثال حجم مقطع يبلغ 262144 بايت تم إرجاعه في حقل العنوان، x-goog-upload-chunk-granularity، عندما تم إعداد جلسة تحميل واحدة. يُرجى العلم أنّ كل عملية تحميل تحتوي على بايت بمضاعفات 262,144.

يجب إعداد جلسة التحميل لتلقّي عنوان URL للتحميل وحجم المجموعة. كما هو موضح في الخطوة السابقة:

POST https://photoslibrary.googleapis.com/v1/uploads HTTP/1.1
Content-Length: 0
X-Goog-Upload-Command: start
X-Goog-Upload-Content-Type: image/jpeg
X-Goog-Upload-Protocol: resumable
X-Goog-Upload-Raw-Size: 3039417
[no body]

يحتوي الرد على عنوان URL للتحميل وحجم المقطع المتوقع:

HTTP/1.1 200 OK
X-Goog-Upload-URL: https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable
X-Goog-Upload-Chunk-Granularity: 262144

الجزء الأول:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 1048576
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 0

[BYTES 0-1048575]

الجزء الثاني:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 1048576
X-Goog-Upload-Command: upload
X-Goog-Upload-Offset: 1048576

[BYTES 1048576-2097151]

المقطع الأخير:

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 942265
X-Goog-Upload-Command: upload, finalize
X-Goog-Upload-Offset: 2097152

[BYTES 2097152-4200000]

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

إذا انقطع طلب التحميل أو إذا تلقّيت رمز حالة HTTP غير200، ابحث في الخادم لمعرفة مقدار التحميل الذي تمّ بنجاح.

في ما يلي طلب POST لعنوان URL للجلسة القابلة للاستئناف. X-Goog-Upload-Command يجب ضبطها على query.

POST https://photoslibrary.googleapis.com/v1/uploads?upload_id=AEnB2Urq&upload_protocol=resumable HTTP/1.1
Content-Length: 0
X-Goog-Upload-Command: query

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