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

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

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

كتل متعددة

لتحميل الملف في مقاطع متعددة:

  1. أنشئ طلب POST لعنوان URL للجلسة القابلة للاستئناف.

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

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

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

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

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

  5. كرر الخطوات المذكورة أعلاه لكل مقطع متبقٍ في الملف.

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

مثال

طلب واحد

يوضّح المثال التالي طلبًا قابلاً للاستئناف لتحميل ملف JPEG بحجم 3,039,417 بايت في طلب واحد.

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 للجلسة القابلة للاستئناف ومدى دقة حجم المجموعة المقبولة الذي تم الحصول عليه في الخطوة السابقة. يستخدم هذا المثال حجم مجموعة يبلغ 262,144 بايت، وتم عرضه في حقل العنوان 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

تتضمّن استجابة الخادم الرمز 200 OK لحالة HTTP والحجم الحالي للتحميل.

HTTP/1.1 200 OK
X-Goog-Upload-Status: active
X-Goog-Upload-Size-Received: 100

يمكنك بعد ذلك استئناف التحميل بهذه الإزاحة. يجب الاستئناف من الإزاحة التي يوفرها الخادم ما لم ترسل أمر تحميل وإنهاء مجمّع، وفي هذه الحالة يمكنك أيضًا الاستئناف من الإزاحة 0.

إذا كان عنوان X-Goog-Upload-Status في استجابة HTTP لأمر طلب البحث ظاهرًا ولم تكن القيمة active، هذا يعني أنّه سبق أن تم إنهاء عملية التحميل.