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

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

لاحظ أن API التحميل القابل للاستئناف ليست الطريقة الوحيدة لتحميل الملفات. تحتوي العديد من العُقد على عنصر ربط يدعم التحميل، ولكن لا يمتلك أغلبها طريقة لمعالجة الملفات الكبيرة أو طريقة لاستئناف جلسة التحميل بعد مقاطعتها.

ستشير مراجع نقاط النهاية التي تدعم مؤشرات الملفات التي تم تحميلها إلى ما إذا كانت نقاط النهاية تدعم المؤشرات التي يتم إرجاعها بواسطة API التحميل القابل للاستئناف.

خطوات التحميل

تنطوي عملية تحميل الملف على خطوتين:

1. استخدم نقطة النهاية عمليات تحميل التطبيق لوصف الملف وإنشاء جلسة تحميل.
2. استخدم معرف جلسة التحميل الذي يتم إرجاعه لبدء عملية التحميل.

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

الخطوة الأولى: إنشاء جلسة

أرسل POST طلبًا يصف ملفك لنقطة نهاية تحميلات التطبيق ({app-id}/uploads) . عند نجاح العملية، سيتم إرجاع معرف جلسة تحميل والذي يمكنك استخدامه في الخطوة التالية لبدء التحميل.

بنية الطلب

POST https://graph.facebook.com/{api-version}/{app-id}/uploads
  &file_length={file-length}
  &file_type={file-type}
  &access_token={access-token}

العناصر النائبة للمعلمات:

• {api-version} — إصدار Graph API.
• {app-id} — معرف التطبيق. الملف الذي تم تحميله والذي سيتم ربطه بهذا التطبيق. يجب أن يتوفر لدى مستخدم التطبيق دور مسؤول أو مطوّر في هذا التطبيق.
• file-length — حجم الملف بالبايت.
• file-type — نوع MIME للملف. القيم الصالحة هي: application/pdf وimage/jpeg وimage/jpg وimage/png وvideo/mp4
• {access-token} — رمز وصول المستخدم الخاص بمستخدم التطبيق.

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

الاستجابة

{
  "id": "{id}"
}

قيم خاصية الاستجابة:

• {id} — معرف جلسة التحميل.

عينة من الطلب

curl -X POST \
 "https://graph.facebook.com/v19.0/584544743160774/uploads?file_length=109981&file_type=image/png&access_token=EAAIT..."

عينة من الاستجابة

{
    "id": "upload:MTphd..."
}

الخطوة الثانية: بدء التحميل

يمكنك بدء جلسة التحميل من خلال إرسال طلب POST إلى عنوان مضيف Graph API وإلحاق جلسة التحميل {id} مع العناوين المطلوبة الموضحة أدناه. وعند نجاح العملية، يتم إرجاع مؤشر الملف {h} والذي يمكنك استخدامه فيما بعد مع أي نقاط نهاية Graph API التي تدعم مؤشرات الملفات التي تم إرجاعها بواسطة API التحميل القابل للاستئناف.

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

بنية الطلب

POST https://graph.facebook.com/{api-version}/{upload-session-id}
  --header 'Authorization: OAuth {access-token}' 
  --header 'file_offset: 0'
  --data-binary @{file-name}

قيم العناصر النائبة

• {api-version} — إصدار Graph API.
• {upload-session-id} — معرف جلسة التحميل الذي تم إرجاعه في الخطوة الأولى.
• {access-token} — رمز وصول المستخدم الخاص بمستخدم التطبيق. يجب أن يكون لمستخدم التطبيق دور في التطبيق المستهدف في الخطوة الأولى.
• {file-name} — اسم الملف المطلوب تحميله.

يجب تضمين رمز الوصول في العنوان وإلا فسيفشل طلبك.

الاستجابة

{
  "h": "{h}"
}

قيم خاصية الاستجابة:

• {h} — مؤشر الملف الخاص بالملف الذي تم تحميله

عينة من الطلب

curl -X POST \
 "https://graph.facebook.com/v19.0/upload:MTphd..." \
 --header "Authorization: OAuth EAAIT..." \
 --header "file_offset: 0" \
 --data-binary @cats_are_jerks.png

عينة من الاستجابة

{
    "h": "2:c2FtcGxl..."
}

حالات المقاطعة

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

بنية الطلب

GET https://graph.facebook.com/{api-version}/{upload-session-id}
  ?access_token={access-token}

قيم العناصر النائبة:

• {api-version} — إصدار Graph API.
• {upload-session-id} — معرف جلسة التحميل الذي تم إرجاعه في الخطوة الأولى: إنشاء جلسة.
• {access-token} — رمز وصول المستخدم الخاص بمستخدم التطبيق.

الاستجابة

{
  "id": "{id}",
  "file_offset": {file-offset}
}

قيم خاصية الاستجابة:

• {id} — معرف جلسة التحميل الذي تم الاستعلام عنه.
• {file-offset} — عدد صحيح يشير إلى عدد وحدات البايت التي تم تحميلها بنجاح.

التقط القيمة file_offset وكرر الخطوة الثانية: بدء التحميل، مع تعيين القيمة إلى عنوان file_offset المتوافق. سيؤدي هذا إلى استئناف عملية التحميل من نقطة التوقف.

عينة من الطلب

curl -X GET \
 "https://graph.facebook.com/v19.0/upload:MTphd...&access_token=EAAIT..." \

عينة من الاستجابة

{
  "id": "upload:MTphd",
  "file_offset": 5238
}