توضِّح هذه الصفحة كيفية تقديم طلب تحميل قابل للاستئناف إلى 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: تحميل الملف
هناك طريقتان لتحميل ملف يحتوي على جلسة قابلة للاستئناف:
- في طلب واحد. عادةً ما يكون هذا النهج هو الأفضل لأنّها تتطلّب طلبات أقلّ، وبالتالي تحقّق أداءً أفضل.
-
في عدّة أجزاء في هذه الطريقة، يتم إجراء التحميلات في طلبات متعددة عن طريق تقسيم البيانات. يتم تقسيم البيانات حسب مضاعفات
x-goog-upload-chunk-granularity
. إذا لزم الأمر، يمكن إعادة محاولة الطلبات المقسَّمة.استخدِم هذا الأسلوب في الحالات التالية:
- يجب تقليل كمية البيانات المنقولة في أي طلبك. قد تحتاج إلى القيام بذلك عندما يكون هناك حد زمني ثابت الطلبات الفردية.
- يجب تقديم مؤشر مخصّص يعرض مستوى تقدّم التحميل.
- تحتاج إلى معرفة متى يكون من الآمن تجاهل البيانات.
طلب واحد
لتحميل الملف في طلب واحد:
- أنشئ طلب
POST
لعنوان URL للجلسة القابلة للاستئناف. - أضِف بيانات الملف إلى نص الطلب.
أضِف عناوين HTTP التالية:
Content-Length
: يتم ضبطه على عدد وحدات البايت في الملف.X-Goog-Upload-Command
: تم الضبط علىupload, finalize
.
أرسِل الطلب.
في حال مقاطعة طلب التحميل أو تلقّيت 5xx
استجابة، اتبع الإجراء الموجود في استئناف
تمت مقاطعة التحميل.
إذا نجح الطلب، ستتلقّى حالة HTTP 200 OK
ورمز مميز للتحميل في نص الاستجابة.
إنشاء
ملف الوسائط باستخدام رمز التحميل هذا.
شرائح متعددة
لتحميل الملف في أجزاء متعددة:
- أنشئ طلب
POST
لعنوان URL للجلسة القابلة للاستئناف. -
أضف بيانات المقطع إلى نص الطلب.
باستثناء المقطع الأخير الذي يكمل عملية التحميل، أنشئ إلى أجزاء أخرى في مضاعفات الحجم المقبول للأجزاء. إبقاء أكبر حجم ممكن حتى يكون التحميل فعالاً.
-
أضِف عناوين HTTP التالية:
Content-Length
: يتم ضبطه على عدد وحدات البايت في مقطع.X-Goog-Upload-Command
: تم ضبطها علىupload
. بالنسبة إلى المقطع الأخير، اضبط القيمة علىupload, finalize
.X-Goog-Upload-Offset
: ضبط على الإزاحة التي وحدات البايت. تجدر الإشارة إلى أنّه يجب تحميل وحدات البايت. بشكل متسلسل. الإزاحة الأولى هي0
.
- أرسِل الطلب.
في حال مقاطعة طلب التحميل أو تلقّيت
5xx
استجابة، اتبع الإجراء الموجود في استئناف تمت مقاطعة التحميل. - كرر هذه الخطوات لكل مقطع متبقٍ في الملف.
إذا نجح الطلب، ستتلقّى حالة 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
، ما يشير إلى أن التحميل
تم إنهاؤها بالفعل.