تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

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

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

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

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

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

تحميل بسيط

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

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

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

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

تتضمّن عناوين HTTP التي يجب استخدامها عند تقديم طلب تحميل بسيط ما يلي:

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

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

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

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

في حال نجاح الطلب، يعرض الخادم رمز الحالة 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
}

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

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

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

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 للتحميل مدة صلاحية محدودة وتنتهي صلاحيته في النهاية (في غضون يوم أو نحو ذلك، إذا لم يتم استخدامه). لهذا السبب، من الأفضل بدء عملية تحميل قابلة للاستئناف فور الحصول على معرّف الموارد الموحّد الخاص بالتحميل، واستئناف عملية تحميل تمّت مقاطعتها بعد فترة قصيرة من حدوث المقاطعة.
إذا أرسلت طلبًا يتضمّن معرّف جلسة تحميل منتهية الصلاحية، سيعرض الخادم رمز الحالة 404 Not Found. عند حدوث خطأ غير قابل للاسترداد في جلسة التحميل، يعرض الخادم رمز الحالة 410 Gone. في هذه الحالات، عليك بدء عملية تحميل جديدة قابلة للاستئناف والحصول على معرّف URI جديد للتحميل وبدء عملية التحميل من البداية باستخدام نقطة النهاية الجديدة.

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

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

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

حالة الطلب: يمكنك الاستعلام عن الحالة الحالية لعملية التحميل من خلال إصدار طلب 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، ما يشير إلى أنّه عليك إعادة محاولة الطلب
انتظِر لمدة ثانية واحدة + random_number_milliseconds وأعِد محاولة إجراء الطلب.
تلقّي الردّ HTTP 503، ما يشير إلى أنّه عليك إعادة محاولة الطلب
انتظِر لمدة ثانيتَين + random_number_milliseconds، ثم أعِد محاولة إجراء الطلب.
تلقّي الردّ HTTP 503، ما يشير إلى أنّه عليك إعادة محاولة الطلب
انتظِر لمدة 4 ثوانٍ + random_number_milliseconds، ثم أعِد محاولة إجراء الطلب.
تلقّي الردّ 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 ثانية قبل اعتبار الطلب "خطأ غير قابل للاسترداد". لا بأس بالحد الأقصى لعدد محاولات إعادة الإرسال، خاصةً إذا كان التحميل يستغرق وقتًا طويلاً، ولكن احرص على ألا يتجاوز التأخير في إعادة المحاولة مدة معقولة، مثلاً أقل من دقيقة واحدة.

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