تستخدم Google تكنولوجيا الذكاء الاصطناعي لترجمة المحتوى إلى لغتك المفضّلة، وقد تتضمّن بعض الأخطاء.

تحميل المرفقات

تتيح لك واجهة برمجة التطبيقات Gmail API تحميل بيانات الملفات عند إنشاء مسودة أو تعديلها أو عند إدراج رسالة أو إرسالها.

خيارات التحميل

تتيح لك واجهة برمجة التطبيقات Gmail API تحميل أنواع معيّنة من البيانات الثنائية أو الوسائط. يتم تحديد الخصائص المحدّدة للبيانات التي يمكنك تحميلها في الصفحة المرجعية لأي طريقة تتيح تحميل الوسائط:

الحدّ الأقصى لحجم الملف الذي يمكن تحميله: الحدّ الأقصى لكمية البيانات التي يمكنك تخزينها باستخدام هذه الطريقة.
أنواع MIME للوسائط المقبولة: أنواع البيانات الثنائية التي يمكنك تخزينها باستخدام هذه الطريقة.

يمكنك تقديم طلبات التحميل بأي من الطرق التالية. حدِّد الطريقة التي تستخدمها مع مَعلمة الطلب uploadType.

التحميل البسيط: uploadType=media للنقل السريع للملفات الأصغر حجمًا، على سبيل المثال، 5 ميغابايت أو أقل.
التحميل المتعدّد الأجزاء: uploadType=multipart لنقل الملفات الصغيرة والبيانات الوصفية بسرعة، يتم نقل الملف مع البيانات الوصفية التي تصفه، وكل ذلك في طلب واحد.
التحميل القابل للاستئناف: uploadType=resumable لضمان نقل الملفات بشكل موثوق، خاصةً الملفات الكبيرة. باستخدام هذه الطريقة، يمكنك استخدام طلب بدء جلسة، والذي يمكن أن يتضمّن بيانات وصفية بشكل اختياري. هذه استراتيجية جيدة للاستخدام في معظم التطبيقات، لأنّها تعمل أيضًا مع الملفات الأصغر حجمًا مقابل طلب HTTP إضافي واحد لكل عملية تحميل.

عند تحميل الوسائط، يمكنك استخدام معرّف موارد منتظم (URI) خاص. في الواقع، تتضمّن الطرق التي تتيح تحميل الوسائط نقطتَي نهاية لعنوان URI:

معرّف الموارد المنتظم (URI) لـ ‎/upload، للوسائط يكون تنسيق نقطة نهاية التحميل هو معرّف الموارد المنتظم (URI) العادي للمورد مع البادئة "‎/upload". استخدِم عنوان URI هذا عند نقل بيانات الوسائط نفسها.
مثلاً: POST /upload/gmail/v1/users/userId/messages/send
معرّف الموارد المنتظم (URI) للمورد العادي، للبيانات الوصفية. إذا كان المورد يحتوي على أي حقول بيانات، يتم استخدام هذه الحقول لتخزين البيانات الوصفية التي تصف الملف الذي تم تحميله. يمكنك استخدام معرّف الموارد المنتظم (URI) هذا عند إنشاء قيم البيانات الوصفية أو تعديلها.
مثال: POST /gmail/v1/users/userId/messages/send

التحميل البسيط

إنّ الطريقة الأسهل لتحميل ملف هي تقديم طلب تحميل بسيط. يُعدّ هذا الخيار مناسبًا في الحالات التالية:

الملف صغير بما يكفي لتحميله مرة أخرى بالكامل في حال تعذّر الاتصال.
ما مِن بيانات وصفية لإرسالها. قد يكون هذا صحيحًا إذا كنت تخطط لإرسال بيانات وصفية لهذا المورد في طلب منفصل، أو إذا لم تكن هناك بيانات وصفية متاحة أو متوافقة.

لاستخدام ميزة التحميل البسيط، عليك إرسال طلب POST أو PUT إلى معرّف الموارد المنتظم (URI) /upload الخاص بالطريقة وإضافة مَعلمة طلب البحث uploadType=media. على سبيل المثال:

POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=media

تشمل عناوين HTTP التي يجب استخدامها عند إجراء طلب تحميل بسيط ما يلي:

‫Content-Type: يتم ضبطها على أحد أنواع بيانات الوسائط المقبولة للتحميل، والمحدّدة في مرجع واجهة برمجة التطبيقات.
‫Content-Length: اضبط هذه القيمة على عدد وحدات البايت التي يتم تحميلها. هذا الحقل غير مطلوب إذا كنت تستخدم ترميز النقل المجزّأ.

مثال: التحميل البسيط

يعرض المثال التالي كيفية استخدام طلب تحميل بسيط لواجهة برمجة تطبيقات Gmail.

POST /upload/gmail/v1/users/userId/messages/send?uploadType=media HTTP/1.1
Host: www.googleapis.com
Content-Type: message/rfc822
Content-Length: number_of_bytes_in_file
Authorization: Bearer your_auth_token

Email Message data

إذا نجح الطلب، يعرض الخادم رمز الحالة 200 OK لبروتوكول HTTP مع أي بيانات وصفية:

HTTP/1.1 200
Content-Type: application/json

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

التحميل المتعدّد الأجزاء

إذا كانت لديك بيانات وصفية تريد إرسالها مع البيانات المطلوب تحميلها، يمكنك تقديم طلب multipart/related واحد. هذا خيار جيد إذا كانت البيانات التي ترسلها صغيرة بما يكفي لتحميلها مرة أخرى بالكامل في حال فشل الاتصال.

لاستخدام ميزة التحميل المتعدّد الأجزاء، أرسِل طلب POST أو PUT إلى معرّف الموارد المنتظم (URI) /upload الخاص بالطريقة وأضِف مَعلمة طلب البحث uploadType=multipart، على سبيل المثال:

POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=multipart

تشمل عناوين HTTP ذات المستوى الأعلى التي يجب استخدامها عند إنشاء طلب تحميل متعدد الأجزاء ما يلي:

Content-Type: اضبط هذه القيمة على multipart/related وأدرِج سلسلة الحدود التي تستخدمها لتحديد أجزاء الطلب.
‫Content-Length: يتم ضبطها على إجمالي عدد وحدات البايت في نص الطلب. يجب أن يكون جزء الوسائط في الطلب أقل من الحد الأقصى لحجم الملف المحدّد لهذه الطريقة.

يتم تنسيق نص الطلب كنوع محتوى multipart/related [RFC2387] ويحتوي على جزأين بالضبط. يتم تحديد الأجزاء من خلال سلسلة حدودية، وتتبع السلسلة الحدودية النهائية شرطتان.

يتطلب كل جزء من الطلب المتعدد الأجزاء عنوان Content-Type إضافيًا:

جزء البيانات الوصفية: يجب أن يأتي أولاً، ويجب أن يتطابق Content-Type مع أحد تنسيقات البيانات الوصفية المقبولة.
مقطع صوتي مشغَّل خلال المكالمة: يجب أن يأتي في المرتبة الثانية، ويجب أن يتطابق Content-Type مع أحد أنواع MIME للوسائط المقبولة في الطريقة.

يمكنك الاطّلاع على مرجع واجهة برمجة التطبيقات للحصول على قائمة بأنواع MIME للوسائط المقبولة والحدود القصوى لحجم الملفات التي يتم تحميلها لكل طريقة.

ملاحظة: لإنشاء أو تعديل الجزء الخاص بالبيانات الوصفية فقط، بدون تحميل البيانات المرتبطة، ما عليك سوى إرسال طلب POST أو PUT إلى نقطة النهاية العادية للمورد: https://www.googleapis.com/gmail/v1/users/userId/messages/send

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

يعرض المثال أدناه طلب تحميل متعدد الأجزاء لواجهة برمجة التطبيقات Gmail API.

POST /upload/gmail/v1/users/userId/messages/send?uploadType=multipart HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length: number_of_bytes_in_entire_request_body

--foo_bar_baz
Content-Type: application/json; charset=UTF-8

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

--foo_bar_baz
Content-Type: message/rfc822

Email Message data
--foo_bar_baz--

إذا نجح الطلب، يعرض الخادم رمز الحالة HTTP 200 OK مع أي بيانات وصفية:

HTTP/1.1 200
Content-Type: application/json

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

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

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

تشمل خطوات استخدام التحميل القابل للاستئناف ما يلي:

بدء جلسة قابلة للاستئناف أرسِل طلبًا أوليًا إلى معرّف الموارد المنتظم (URI) الخاص بالتحميل والذي يتضمّن البيانات الوصفية، إن توفّرت.
احفظ معرّف الموارد المنتظم (URI) الخاص بالجلسة القابلة للاستئناف. احفظ معرّف الموارد المنتظم (URI) للجلسة الذي تم عرضه في استجابة الطلب الأولي، لأنّك ستستخدمه للطلبات المتبقية في هذه الجلسة.
حمِّل الملف. أرسِل ملف الوسائط إلى معرّف الموارد المنتظم (URI) الخاص بالجلسة القابلة للاستئناف.

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

ملاحظة: تنتهي صلاحية معرّف الموارد المنتظم (URI) للتحميل بعد أسبوع واحد.

الخطوة 1: بدء جلسة قابلة للاستئناف

لبدء عملية تحميل قابلة للاستئناف، أرسِل طلب POST أو PUT إلى معرّف الموارد المنتظم (URI) /upload الخاص بالطريقة وأضِف مَعلمة طلب البحث uploadType=resumable، على سبيل المثال:

POST https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable

بالنسبة إلى طلب البدء هذا، يكون النص فارغًا أو يحتوي على البيانات الوصفية فقط، وستنقل المحتوى الفعلي للملف الذي تريد تحميله في الطلبات اللاحقة.

استخدِم عناوين HTTP التالية مع الطلب الأولي:

‫X-Upload-Content-Type: يتم ضبط هذه المَعلمة على نوع MIME للوسائط في بيانات التحميل التي سيتم نقلها في الطلبات اللاحقة.
X-Upload-Content-Length: يتم ضبطها على عدد وحدات بايت بيانات التحميل التي سيتم نقلها في الطلبات اللاحقة. إذا كان الطول غير معروف في وقت إرسال هذا الطلب، يمكنك حذف هذا العنوان.
في حال تقديم بيانات وصفية: Content-Type يتم ضبطه وفقًا لنوع بيانات البيانات الوصفية.
Content-Length: يجب ضبط هذه القيمة على عدد وحدات البايت المقدَّمة في نص هذا الطلب الأولي. هذا الحقل غير مطلوب إذا كنت تستخدم ترميز النقل المجزّأ.

مثال: طلب بدء جلسة قابلة للاستئناف

يوضّح المثال التالي كيفية بدء جلسة قابلة للاستئناف في Gmail API.

POST /upload/gmail/v1/users/userId/messages/send?uploadType=resumable HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer your_auth_token
Content-Length: 38
Content-Type: application/json; charset=UTF-8
X-Upload-Content-Type: message/rfc822
X-Upload-Content-Length: 2000000

{
  "id": string,
  "threadId": string,
  "labelIds": [
    string
  ],
  "snippet": string,
  "historyId": unsigned long,
  "payload": {
    "partId": string,
    "mimeType": string,
    "filename": string,
    "headers": [
      {
        "name": string,
        "value": string
      }
    ],
    "body": users.messages.attachments Resource,
    "parts": [
      (MessagePart)
    ]
  },
  "sizeEstimate": integer,
  "raw": bytes
}

ملاحظة: بالنسبة إلى طلب التعديل الأولي القابل للاستئناف بدون بيانات وصفية، اترك نص الطلب فارغًا واضبط العنوان Content-Length على 0.

يصف القسم التالي كيفية معالجة الاستجابة.

الخطوة 2: حفظ معرّف الموارد المنتظم (URI) للجلسة القابلة للاستئناف

إذا نجح طلب بدء الجلسة، يستجيب خادم واجهة برمجة التطبيقات برمز حالة HTTP‏ 200 OK. بالإضافة إلى ذلك، يوفّر الطلب عنوان Location يحدّد معرّف الموارد المنتظم (URI) للجلسة القابلة للاستئناف. يتضمّن العنوان Location، الموضّح في المثال أدناه، جزءًا من معلَمة طلب البحث upload_id يوفّر معرّف التحميل الفريد الذي يجب استخدامه لهذه الجلسة.

مثال: ردّ بدء جلسة قابلة للاستئناف

في ما يلي الردّ على الطلب في الخطوة 1:

HTTP/1.1 200 OK
Location: https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable&upload_id=xa298sd_sdlkj2
Content-Length: 0

قيمة العنوان Location، كما هو موضّح في مثال الاستجابة أعلاه، هي معرّف الموارد المنتظم (URI) للجلسة الذي ستستخدمه كنقطة نهاية HTTP لإجراء عملية تحميل الملف الفعلية أو طلب حالة التحميل.

انسخ معرّف الموارد المنتظم (URI) للجلسة واحفظه لتتمكّن من استخدامه في الطلبات اللاحقة.

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

لتحميل الملف، أرسِل طلب PUT إلى معرّف الموارد المنتظم (URI) الخاص بالتحميل الذي حصلت عليه في الخطوة السابقة. تنسيق طلب التحميل هو:

PUT session_uri

تتضمّن عناوين HTTP التي يجب استخدامها عند إنشاء طلبات تحميل الملفات القابلة للاستئناف Content-Length. اضبط هذه القيمة على عدد وحدات البايت التي يتم تحميلها في هذا الطلب، وهو بشكل عام حجم الملف الذي يتم تحميله.

مثال: طلب تحميل ملف قابل للاستئناف

في ما يلي طلب قابل للاستئناف لتحميل ملف رسالة البريد الإلكتروني بالكامل الذي يبلغ حجمه 2,000,000 بايت للمثال الحالي.

PUT https://www.googleapis.com/upload/gmail/v1/users/userId/messages/send?uploadType=resumable&upload_id=xa298sd_sdlkj2 HTTP/1.1
Content-Length: 2000000
Content-Type: message/rfc822

bytes 0-1999999

إذا نجح الطلب، يستجيب الخادم من خلال HTTP 201 Created، بالإضافة إلى أي بيانات وصفية مرتبطة بهذا المورد. إذا كان الطلب الأولي للجلسة القابلة للاستئناف هو PUT، لتعديل مورد حالي، ستكون استجابة النجاح هي 200 OK، بالإضافة إلى أي بيانات وصفية مرتبطة بهذا المورد.

إذا تمت مقاطعة طلب التحميل أو إذا تلقّيت استجابة HTTP 503 Service Unavailable أو أي استجابة 5xx أخرى من الخادم، اتّبِع الإجراء الموضّح في استئناف عملية تحميل تمت مقاطعتها.

تحميل الملف على أجزاء

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

التوسيع للحصول على مزيد من المعلومات

إذا كنت بصدد تحميل البيانات في أجزاء، يجب أيضًا تضمين العنوان Content-Range، بالإضافة إلى العنوان Content-Length المطلوب لتحميل الملفات الكاملة:

‫Content-Length: يتم ضبطها على حجم الجزء أو أقل، كما قد يكون الحال في الطلب الأخير.
Content-Range: يتم ضبطها لعرض وحدات البايت في الملف الذي يتم تحميله. على سبيل المثال، يشير الرمز Content-Range: bytes 0-524287/2000000 إلى أنّك تقدّم أول 524,288 بايت (256 × 1024 × 2) في ملف حجمه 2,000,000 بايت.

قيود حجم الأجزاء: يجب أن يكون حجم جميع الأجزاء من مضاعفات 256 كيلوبايت (256 × 1024 بايت)، باستثناء الجزء الأخير الذي يكمل عملية التحميل. إذا كنت تستخدم ميزة التقسيم، من المهم الحفاظ على حجم الأجزاء كبيرًا قدر الإمكان لضمان فعالية عملية التحميل.

مثال: طلب تحميل ملف مجزّأ قابل للاستئناف

قد يبدو الطلب الذي يرسل أول 524,288 بايت على النحو التالي:

PUT {session_uri} HTTP/1.1
Host: www.googleapis.com
Content-Length: 524288
Content-Type: message/rfc822
Content-Range: bytes 0-524287/2000000

bytes 0-524288

إذا نجح الطلب، يستجيب الخادم بالحالة 308 Resume Incomplete، بالإضافة إلى عنوان Range يحدّد إجمالي عدد وحدات البايت التي تم تخزينها حتى الآن:

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: bytes=0-524287

استخدِم القيمة العليا التي تم عرضها في العنوان Range لتحديد مكان بدء الجزء التالي. يُرجى مواصلة PUT كل جزء من الملف إلى أن يتم تحميل الملف بأكمله.

إذا تمت مقاطعة طلب PUT لأي جزء أو إذا تلقيت استجابة HTTP 503 Service Unavailable أو أي استجابة 5xx أخرى من الخادم، اتّبِع الإجراء الموضّح في استئناف عملية تحميل تمت مقاطعتها، ولكن بدلاً من تحميل بقية الملف، ما عليك سوى مواصلة تحميل الأجزاء من تلك النقطة.

ملاحظات مهمّة:

احرص على استخدام العنوان Range في الاستجابة لتحديد مكان بدء الجزء التالي، ولا تفترض أنّ الخادم قد تلقّى جميع وحدات البايت المُرسَلة في الطلب السابق.
لكل معرّف موارد منتظم (URI) للتحميل مدة صلاحية محدودة تنتهي في النهاية (خلال يوم أو نحو ذلك، في حال عدم استخدامه). لهذا السبب، من الأفضل بدء عملية تحميل قابلة للاستئناف فور الحصول على معرّف الموارد المنتظم (URI) الخاص بالتحميل، واستئناف عملية تحميل متقطعة بعد فترة قصيرة من حدوث الانقطاع.
إذا أرسلت طلبًا يتضمّن معرّف جلسة تحميل منتهية الصلاحية، يعرض الخادم رمز الحالة 404 Not Found. عند حدوث خطأ غير قابل للإصلاح في جلسة التحميل، يعرض الخادم رمز الحالة 410 Gone. في هذه الحالات، يجب بدء عملية تحميل جديدة قابلة للاستئناف والحصول على عنوان URI جديد للتحميل وبدء التحميل من البداية باستخدام نقطة النهاية الجديدة.

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

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

إذا تم إنهاء طلب تحميل قبل تلقّي ردّ أو إذا تلقّيت ردًّا من الخادم يتضمّن رمز HTTP 503 Service Unavailable، عليك استئناف عملية التحميل التي تمّت مقاطعتها. ولإجراء ذلك:

حالة الطلب: يمكنك الاستعلام عن الحالة الحالية لعملية التحميل من خلال إرسال طلب PUT فارغ إلى معرّف الموارد المنتظم (URI) الخاص بالتحميل. بالنسبة إلى هذا الطلب، يجب أن تتضمّن عناوين HTTP عنوان Content-Range يشير إلى أنّ الموضع الحالي في الملف غير معروف. على سبيل المثال، اضبط Content-Range على */2000000 إذا كان إجمالي طول الملف هو 2,000,000. إذا لم تكن تعرف الحجم الكامل للملف، اضبط Content-Range على */*.
ملاحظة: يمكنك طلب الحالة بين الأجزاء، وليس فقط في حال انقطاع عملية التحميل. يكون ذلك مفيدًا، على سبيل المثال، إذا كنت تريد عرض مؤشرات تقدّم التحميل للمتصفّحات القديمة.
الحصول على عدد وحدات البايت التي تم تحميلها معالجة الردّ من طلب الحالة يستخدم الخادم عنوان Range في استجابته لتحديد وحدات البايت التي تلقّاها حتى الآن. على سبيل المثال، يشير عنوان Range بقيمة 0-299999 إلى أنّه تم استلام أول 300,000 بايت من الملف.
حمِّل البيانات المتبقية. أخيرًا، بعد معرفة مكان استئناف الطلب، أرسِل البيانات المتبقية أو الجزء الحالي. يُرجى العِلم أنّه عليك التعامل مع البيانات المتبقية كجزء منفصل في كلتا الحالتين، لذا عليك إرسال العنوان Content-Range عند استئناف عملية التحميل.

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

‫1) اطلب حالة التحميل.

يستخدم الطلب التالي العنوان Content-Range للإشارة إلى أنّ الموضع الحالي في الملف الذي يبلغ حجمه 2,000,000 بايت غير معروف.

PUT {session_uri} HTTP/1.1
Content-Length: 0
Content-Range: bytes */2000000

‫2) استخرِج عدد وحدات البايت التي تم تحميلها حتى الآن من الردّ.

يستخدم ردّ الخادم العنوان Range للإشارة إلى أنّه تلقّى أول 43 بايت من الملف حتى الآن. استخدِم القيمة العليا لرأس Range لتحديد مكان بدء التحميل المستأنَف.

HTTP/1.1 308 Resume Incomplete
Content-Length: 0
Range: 0-42

ملاحظة: من الممكن أن تكون استجابة الحالة 201 Created أو 200 OK إذا اكتمل التحميل. قد يحدث ذلك في حال انقطاع الاتصال بعد تحميل جميع وحدات البايت ولكن قبل تلقّي العميل ردًا من الخادم.

‫3) استئناف التحميل من حيث توقّف

يستأنف الطلب التالي عملية التحميل من خلال إرسال وحدات البايت المتبقية من الملف، بدءًا من البايت 43.

PUT {session_uri} HTTP/1.1
Content-Length: 1999957
Content-Range: bytes 43-1999999/2000000

bytes 43-1999999

أفضل الممارسات

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

استئناف عمليات التحميل أو إعادة محاولة إجرائها في حال تعذُّرها بسبب انقطاع الاتصال أو ظهور أي أخطاء من النوع 5xx، بما في ذلك:
- 500 Internal Server Error
- 502 Bad Gateway
- 503 Service Unavailable
- 504 Gateway Timeout
استخدِم استراتيجية التراجع الأسي في حال ظهور أي خطأ في خادم 5xx عند استئناف طلبات التحميل أو إعادة محاولة إرسالها. يمكن أن تحدث هذه الأخطاء إذا كان الخادم محمّلاً بشكل زائد. يمكن أن يساعد التراجع الأسي في تخفيف هذه الأنواع من المشاكل خلال فترات ارتفاع عدد الطلبات أو حركة بيانات الشبكة الكثيفة.
يجب عدم معالجة الأنواع الأخرى من الطلبات باستخدام خوارزمية الرقود الأسي الثنائي، ولكن يمكنك إعادة محاولة تنفيذ عدد منها. عند إعادة محاولة إرسال هذه الطلبات، يجب الحدّ من عدد مرات إعادة المحاولة. على سبيل المثال، يمكن أن يقتصر الرمز على عشر محاولات أو أقل قبل الإبلاغ عن خطأ.
يمكنك معالجة الخطأين 404 Not Found و410 Gone عند إجراء عمليات تحميل قابلة للاستئناف من خلال بدء عملية التحميل بالكامل من جديد.

الرقود الأسي الثنائي

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

عند استخدام التراجع الأسي بشكل صحيح، يزيد من كفاءة استخدام معدل نقل البيانات، ويقلل من عدد الطلبات المطلوبة للحصول على استجابة ناجحة، ويزيد من معدل نقل الطلبات في البيئات المتزامنة.

في ما يلي خطوات تنفيذ استراتيجية بسيطة لتأخير المحاولة بشكل أسي:

أرسِل طلبًا إلى واجهة برمجة التطبيقات.
تلقّي ردّ HTTP 503، ما يشير إلى أنّه عليك إعادة محاولة إرسال الطلب
انتظِر لمدة ثانية واحدة + عدد_عشوائي_من_المللي_ثانية وأعِد محاولة إجراء الطلب.
تلقّي ردّ HTTP 503، ما يشير إلى أنّه عليك إعادة محاولة إرسال الطلب
انتظِر لمدة ثانيتين + عدد_عشوائي_من_المللي_ثانية، ثم أعِد محاولة إجراء الطلب.
تلقّي ردّ HTTP 503، ما يشير إلى أنّه عليك إعادة محاولة إرسال الطلب
انتظِر لمدة 4 ثوانٍ + عدد_عشوائي_من_المللي_ثانية، ثم أعِد محاولة إجراء الطلب.
تلقّي ردّ HTTP 503، ما يشير إلى أنّه عليك إعادة محاولة إرسال الطلب
انتظِر لمدة 8 ثوانٍ + random_number_milliseconds، ثم أعِد محاولة إجراء الطلب.
تلقّي ردّ HTTP 503، ما يشير إلى أنّه عليك إعادة محاولة إرسال الطلب
انتظِر لمدة 16 ثانية + random_number_milliseconds، ثم أعِد محاولة إجراء الطلب.
إيقاف الإبلاغ عن خطأ أو تسجيله

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

ملاحظة: تكون فترة الانتظار دائمًا (2 ^ n) + random_number_milliseconds، حيث n هو عدد صحيح يتزايد بشكل رتيب ويتم تحديده في البداية على أنّه 0. تتم زيادة العدد الصحيح n بمقدار 1 لكل تكرار (لكل طلب).

تم ضبط الخوارزمية على الإنهاء عندما تكون n تساوي 5. يمنع هذا الحدّ الأقصى العملاء من إعادة المحاولة بشكل لا نهائي، ويؤدي إلى تأخير إجمالي يبلغ حوالي 32 ثانية قبل أن يتم اعتبار الطلب "خطأ غير قابل للإصلاح". لا بأس في زيادة الحد الأقصى لعدد المحاولات، خاصةً إذا كانت عملية تحميل طويلة قيد التقدم، ولكن تأكَّد من وضع حد معقول لمهلة إعادة المحاولة، مثلاً أقل من دقيقة واحدة.

تحميل المرفقات تنظيم صفحاتك في مجموعات يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.