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

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