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

توضِّح هذه الصفحة كيفية تقديم طلب تحميل قابل للاستئناف إلى 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 بحجم 3039417 بايت في أجزاء متعددة، باستخدام الجلسة القابلة للاستئناف عنوان URL ودقة حجم المجموعة المقبولة التي تم الحصول عليها في الخطوة السابقة. يستخدم هذا المثال حجم مقطع يبلغ 262144 بايت تم إرجاعه في حقل العنوان، x-goog-upload-chunk-granularity، عندما تم إعداد جلسة التحميل. لاحظ أن كل عملية تحميل تحتوي على وحدات بايت في مضاعفات 262144.

يجب إعداد جلسة التحميل لتلقّي عنوان 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، ما يشير إلى أن التحميل تم إنهاؤها بالفعل.