تتيح لك Google Drive API تحميل بيانات الملفات عند إنشاء ملف File
أو تعديله. للحصول على معلومات عن كيفية إنشاءملف يقتصر على البيانات الوصفية، مثل مجلد، يُرجى الاطّلاع على مقالة إنشاء ملفات تتضمّن بيانات وصفية فقط.
هناك ثلاثة أنواع من عمليات التحميل التي يمكنك إجراؤها:
التحميل البسيط (
uploadType=media
): استخدِم هذا النوع من التحميل لنقل ملف وسائط صغير (5 ميغابايت أو أقل) بدون تقديم بيانات وصفية. لإجراء عمليةتحميل بسيطة، يُرجى الرجوع إلى تنفيذ عملية تحميل بسيطة.التحميل المتعدّد الأجزاء (
uploadType=multipart
): "استخدِم هذا النوع من التحميل لتحميل ملف صغير (5 ميغابايت أو أقل) مع البيانات الوصفية التي تصف الملف في طلب واحد. لتنفيذ عملية تحميل متعدّد الأجزاء، يُرجى الرجوع إلى مقالة تنفيذ عمليةتحميل متعدّد الأجزاء.التحميل القابل للاستئناف (
uploadType=resumable
): استخدِم هذا النوع من التحميل مع الملفات الكبيرة (أكبر من 5 ميغابايت) وفي حال احتمالية انقطاع الشبكة بشكل كبير، مثل إنشاء ملف من تطبيق متوافق مع الأجهزة الجوّالة. يُعدّ التحميل القابل للاستئناف أيضًا خيارًا جيدًا لمعظم التطبيقات لأنّه يعمل أيضًا مع الملفات الصغيرة بتكلفة منخفضة تتمثل في طلب HTTP إضافي واحد لكل عملية تحميل. لإجراء عملية تحميل قابلة للاستئناف، يُرجى الاطّلاع على مقالة تنفيذ عملية تحميل قابلة للاستئناف.
تُنفِّذ مكتبات عملاء Google API نوعًا واحدًا على الأقل من هذه الأنواع من عمليات التحميل. راجِع مستندات مكتبة العميل للحصول على تفاصيل إضافية حول كيفية استخدام كل نوع.
استخدام PATCH
مقارنةً بـ PUT
للتذكير، يتيح فعل HTTP PATCH
تعديلًا جزئيًا لمورد الملف،
في حين يتيح فعل HTTP PUT
استبدال المورد بالكامل. يُرجى العِلم أنّ PUT
يمكن أن تؤدي إلى تغييرات جذرية عند إضافة حقل جديد إلى مورد حالي.
عند تحميل مرجع ملف، اتّبِع الإرشادات التالية:
- استخدِم فعل HTTP المُسجَّل في مرجع واجهة برمجة التطبيقات للطلب الأوّلي لتحميل ملف قابل للاستئناف أو للطلب الوحيد لتحميل ملف بسيط أو متعدّد الأجزاء.
- استخدِم
PUT
لجميع الطلبات اللاحقة لإعادة تحميل المحتوى بعد انقطاعه بعد أن بدأ الطلب. تعمل هذه الطلبات على تحميل المحتوى بغض النظر عن الطريقة التي يتمّ استدعاؤها.
إجراء عملية تحميل بسيطة
لإجراء عملية تحميل بسيطة، استخدِم الطريقة
files.create
مع
uploadType=media
.
في ما يلي كيفية إجراء عملية تحميل بسيطة:
HTTP
أنشئ طلبًا من النوع
POST
إلى عنوان URI /upload الخاص بالطريقة مع مَعلمة الطلب uploadType=media
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=media
أضِف بيانات الملف إلى محتوى الطلب.
أضِف رؤوس HTTP التالية:
Content-Type
. اضبطه على نوع وسائط MIME للعنصر الذي يتم تحميله.Content-Length
. اضبط هذا الخيار على عدد البايتات التي تحمّلها. إذا كنت تستخدِم ترميز نقل مجزّأ، لن يكون هذا العنوان مطلوبًا.
أرسِل الطلب. إذا نجح الطلب، يعرض الخادم رمز الحالة
HTTP 200 OK
مع البيانات الوصفية للملف. {HTTP}
عند إجراء عملية تحميل بسيطة، يتم إنشاء بيانات وصفية أساسية ويتم استنتاج بعض السمات
من الملف، مثل نوع MIME أو modifiedTime
. يمكنك استخدام عملية تحميل بسيطة في الحالات التي تتوفّر فيها ملفات صغيرة وتكون البيانات الوصفية للملف غير مهمة.
تنفيذ عملية تحميل متعدّدة الأجزاء
يتيح لك طلب التحميل المتعدّد الأجزاء تحميل البيانات الوصفية والبيانات في الطلب نفسه. استخدِم هذا الخيار إذا كانت البيانات التي ترسلها صغيرة بما يكفي لتحميلها مرة أخرى، بأكملها، في حال تعذّر الاتصال.
لإجراء عملية تحميل متعدّد الأجزاء، استخدِم الطريقة
files.create
مع
uploadType=multipart
.
في ما يلي كيفية إجراء عملية تحميل متعدّد الأجزاء:
Java
Python
Node.js
PHP
NET.
HTTP
أنشئ طلبًا من النوع
POST
إلى عنوان URI /upload الخاص بالطريقة مع مَعلمة الطلب uploadType=multipart
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart
أنشئ نص الطلب. يجب تنسيق النص وفقًا لنوع المحتوى المتعدّد الأجزاء/المرتبط RFC 2387، والذي يحتوي على جزأين:
- البيانات الوصفية. يجب أن تظهر البيانات الوصفية أولاً وأن يكون لها
Content-Type
عنوان تم ضبطه علىapplication/json;
charset=UTF-8
. أضِف البيانات الوصفية للملف بتنسيق JSON. - الوسائط يجب أن تأتي الوسائط في المرّة الثانية وأن تحتوي على عنوان
Content-Type
من أي نوع MIME. أضِف بيانات الملف إلى جزء الوسائط.
حدِّد كل جزء باستخدام سلسلة حدودية يسبقها شرطة سفلية مزدوجة. بالإضافة إلى ذلك، أضِف واصلة بعد سلسلة الحدود النهائية.
- البيانات الوصفية. يجب أن تظهر البيانات الوصفية أولاً وأن يكون لها
أضِف عناوين HTTP ذات المستوى الأعلى التالية:
Content-Type
. اضبط القيمة علىmultipart/related
وأدرِج سلسلة الحدود التي تستخدمها لتحديد الأجزاء المختلفة من الطلب. على سبيل المثال:Content-Type: multipart/related; boundary=foo_bar_baz
Content-Length
. يتم ضبطه على إجمالي عدد وحدات البايت في نص الطلب.
أرسِل الطلب.
لإنشاء جزء البيانات الوصفية أو تعديله فقط، بدون البيانات المرتبطة به،
أرسِل طلبًا من النوع POST
أو PATCH
إلى نقطة نهاية المورد العادية:
https://www.googleapis.com/drive/v3/files
في حال نجاح الطلب،
يعرض الخادم رمز الحالة HTTP 200 OK
مع
البيانات الوصفية للملف.
عند إنشاء الملفات، يجب تحديد إضافة ملف في حقل name
الملف. على سبيل المثال، عند إنشاء ملف JPEG للصور، يمكنك تحديد رمز
مثل "name": "photo.jpg"
في البيانات الوصفية. تؤدي الطلبات اللاحقة إلى files.get
إلى عرض السمة fileExtension
للقراءة فقط
التي تحتوي على الإضافة المحدّدة أصلاً في حقل name
.
إجراء عملية تحميل قابلة للاستئناف
يتيح لك التحميل القابل للاستئناف استئناف عملية التحميل بعد أن يؤدي أحد أخطاء الاتصالات إلى إيقاف تدفق البيانات. بما أنّه ليس عليك إعادة بدء عمليات تحميل الملفات الكبيرة من البداية، يمكن أن تقلل عمليات التحميل القابلة للاستئناف أيضًا من استخدام معدل نقل البيانات في حال حدوث عطل في الشبكة.
تكون عمليات التحميل القابلة للاستئناف مفيدة عندما تتفاوت أحجام ملفاتك بشكل كبير أو عندما يكون هناك مهلة زمنية ثابتة للطلبات (مثل المهام التي تعمل في الخلفية لنظام التشغيل المتوافق مع الأجهزة الجوّالة وطلبات App Engine معيّنة). يمكنك أيضًا استخدام ميزة "التحميل القابل للاستئناف" في الحالات التي تريد فيها عرض شريط تقدّم التحميل.
يتألف التحميل القابل للاستئناف من عدة خطوات عالية المستوى:
- أرسِل الطلب الأوّلي واسترِد معرّف الموارد المنتظم للجلسة التي يمكن استئنافها.
- حمِّل البيانات وراقب حالة التحميل.
- (اختياري) في حال انقطاع عملية التحميل، استئنِفها.
إرسال الطلب الأوّلي
لبدء عملية تحميل قابلة للاستئناف، استخدِم طريقة
files.create
مع
uploadType=resumable
.
HTTP
أنشئ طلبًا من النوع
POST
إلى عنوان URI /upload الخاص بالطريقة مع مَعلمة الطلب uploadType=resumable
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable
إذا تمكّن طلب البدء من إكمال العملية، سيتضمّن الردّ رمز حالة HTTP
200 OK
. بالإضافة إلى ذلك، يتضمّن الردّ عنوانLocation
الذي يحدّد معرّف الموارد المنتظم (URI) للجلسة التي يمكن استئنافها:HTTP/1.1 200 OK Location: https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable&upload_id=xa298sd_sdlkj2 Content-Length: 0
احفظ معرّف URI للجلسة التي يمكن استئنافها حتى تتمكّن من تحميل بيانات الملف والاستعلام عن حالة التحميل. تنتهي صلاحية معرّف الموارد المنتظم لجلسة يمكن استئنافها بعد أسبوع واحد.
إذا كانت لديك بيانات وصفية للملف، أضِف البيانات الوصفية إلى محتوى الطلب بتنسيق JSON. بخلاف ذلك، اترك نص الطلب فارغًا.
أضِف رؤوس HTTP التالية:
X-Upload-Content-Type
: اختياري يتم ضبطه على نوع MIME لملف data، الذي يتم نقله في الطلبات اللاحقة. إذا لم يتم تحديد نوع MIME للبيانات في البيانات الوصفية أو من خلال هذا العنوان، يتم عرض العنصر على أنّهapplication/octet-stream.
.X-Upload-Content-Length
: اختياري يتم ضبطه على عدد وحدات البايت في بيانات الملف التي يتم نقلها في الطلبات اللاحقة.Content-Type
: مطلوب إذا كانت لديك بيانات وصفية للملف. اضبط القيمة علىapplication/json;
charset=UTF-8
.Content-Length
. مطلوب ما لم تكن تستخدم ترميز نقل مجزّأ. يتم ضبطه على عدد وحدات البايت في نص هذا الطلب الأوّلي.
أرسِل الطلب. إذا كان طلب بدء الجلسة ناجحًا، يحتوي الاستجابة على رمز الحالة
200 OK HTTP
. بالإضافة إلى ذلك، يحتوي الردّ على عنوانLocation
يحدّد معرّف الموارد المنتظم (URI) للجلسة التي يمكن استئنافها. استخدِم معرّف URI لجلسة يمكن استئنافها لتحميل بيانات الملف والاستعلام عن حالة التحميل. تنتهي صلاحية معرّف الموارد المنتظم لجلسة يمكن استئنافها بعد أسبوع واحد.انسخ عنوان URL للجلسة التي يمكن استئنافها واحفظه.
انتقِل إلى تحميل المحتوى.
تحميل المحتوى
هناك طريقتان لتحميل ملف باستخدام جلسة قابلة للاستئناف:
- تحميل المحتوى في طلب واحد: استخدِم هذا الأسلوب عندما يمكن تحميل الملف في طلب واحد، أو إذا لم يكن هناك حدّ زمني محدّد لأي طلب واحد، أو إذا لم تكن بحاجة إلى عرض مؤشر لتقدّم عملية التحميل. وهذا الأسلوب هو الأفضل لأنّه يتطلّب عددًا أقل من الطلبات ويحقّق أداءً أفضل.
تحميل المحتوى في أجزاء متعددة: استخدِم هذا الأسلوب إذا كان عليك تقليل كمية البيانات المنقولة في أي طلب فردي. قد تحتاج إلى تقليل البيانات المنقولة عندما يكون هناك حدّ زمني ثابت لطلبات فردية، كما يمكن أن يكون الحال بالنسبة إلى فئات معيّنة من طلبات App Engine. يكون هذا النهج مفيدًا أيضًا إذا كان عليك تقديم مؤشر مخصّص لمحاولة عرض مستوى تقدّم التحميل.
HTTP - طلب واحد
- أنشئ طلبًا باستخدام
PUT
إلى معرّف الموارد المنتظم (URI) للجلسة التي يمكن استئنافها. - أضِف بيانات الملف إلى محتوى الطلب.
- أضِف عنوان HTTP Content-Length، واضبطه على عدد البايتات في الملف.
- أرسِل الطلب. إذا انقطع طلب التحميل أو إذا تلقّيت الردّ
5xx
، اتّبِع الإجراء الموضّح في استئناف عملية تحميل متوقّفة.
HTTP - طلبات متعددة
أنشئ طلبًا باستخدام
PUT
إلى معرّف الموارد المنتظم (URI) للجلسة التي يمكن استئنافها.أضِف بيانات المقطع إلى محتوى الطلب. أنشئ أجزاء بمضاعفات حجم 256 كيلوبايت (256 × 1024 بايت)، باستثناء الجزء النهائي الذي يُكمِل عملية التحميل. يجب إبقاء حجم الجزء أكبر قدر ممكن لكي يكون التحميل فعّالاً.
أضِف رؤوس HTTP التالية:
Content-Length
. يتم ضبطه على عدد وحدات البايت في الجزء الحالي.Content-Range
. يمكنك ضبط الإعدادات لعرض البايتات في الملف الذي تحمّله. على سبيل المثال، يشير الرمزContent-Range: bytes 0-524287/2000000
إلى أنّك تحمّلContent-Range: bytes 0-524287/2000000
بايت (256 × 1024 × 2) في ملف بحجم 2,000,000 بايت.
أرسِل الطلب وعالج الاستجابة. إذا تم توقّف طلب التحميل أو إذا تلقّيت الردّ
5xx
، اتّبِع الإجراء الموضّح في مقالة استئناف عملية تحميل متوقّفة.كرِّر الخطوات من 1 إلى 4 لكل جزء متبقٍّ في الملف. استخدِم العنوان
Range
في الاستجابة لتحديد مكان بدء الجزء التالي. لا تفترض أنّ الخادم تلقّى جميع البايتات المُرسَلة في الطلب السابق.
عند اكتمال تحميل الملف بالكامل، ستتلقّى ردًا 200 OK
أو
201 Created
، بالإضافة إلى أي بيانات وصفية مرتبطة بالمورد.
استئناف عملية تحميل تمت مقاطعتها
إذا تم إنهاء طلب التحميل قبل تلقّي ردّ، أو إذا تلقّيت الردّ 503
Service Unavailable
، عليك استئناف عملية التحميل المتوقّفة.
HTTP
لطلب حالة التحميل، أنشئ طلبًا فارغًا من النوع
PUT
إلى معرّف الموارد المنتظِم للجلسة التي يمكن استئنافها.أضِف عنوان
Content-Range
للإشارة إلى أنّ الموضع الحالي في الملف غير معروف. على سبيل المثال، اضبطContent-Range
على*/2000000
إذا كان إجمالي طول الملف هو 2,000,000 بايت. إذا لم تكن تعرف الحجم الكامل للملف، اضبطContent-Range
على*/*
.أرسِل الطلب.
معالجة الردّ:
- يشير الرمز
200 OK
أو201 Created
إلى اكتمال عملية التحميل، وليس من الضروري اتّخاذ أي إجراء آخر. - يشير الرمز
308 Resume Incomplete
إلى أنّه عليك مواصلةتحميل الملف. - يشير الرمز
404 Not Found
إلى انتهاء صلاحية جلسة التحميل ويجب إعادة التحميل من البداية.
- يشير الرمز
إذا تلقّيت استجابة
308 Resume Incomplete
، عليك معالجة عنوانRange
للاستجابة لتحديد البايتات التي تلقّاها الخادم. إذا لم يتضمّن الردّRange
عنوانًا، يعني ذلك أنّه لم يتم استلام أي وحدات بايت. على سبيل المثال، يشير عنوانRange
bytes=0-42
إلى أنّه تم استلام أول 43 بايت من الملف وأنّ الجزء التالي المطلوب تحميله سيبدأ بالبايت 44.الآن بعد أن عرفت مكان استئناف التحميل، يمكنك مواصلة تحميل الملف بدءًا من البايت التالي. أدرِج عنوانًا
Content-Range
للإشارة إلى الجزء الذي ترسله من الملف. على سبيل المثال، يشير الرمزContent-Range: bytes 43-1999999
إلى أنّك تُرسِل البايتات من 44 إلى 2,000,000.
التعامل مع أخطاء تحميل الوسائط
عند تحميل الوسائط، اتّبِع أفضل الممارسات التالية للتعامل مع الأخطاء:
- بالنسبة إلى أخطاء
5xx
، يمكنك استئناف عمليات التحميل التي تعذّر إكمالها بسبب انقطاع الاتصال أو إعادة محاولة إكمالها. لمزيد من المعلومات عن معالجة أخطاء5xx
، يُرجى الرجوع إلى مقالة أخطاء 500 و502 و503 و504. - في حال ظهور
403 rate limit
خطأ، يُرجى إعادة المحاولة. لمزيد من المعلومات عن التعامل مع أخطاء403 rate limit
، يُرجى الاطّلاع على الخطأ 403:rateLimitExceeded
. - في حال حدوث أي أخطاء
4xx
(بما في ذلك403
) أثناء عملية تحميل قابلة للاستئناف، يُرجى إعادة بدءتحميل. تشير هذه الأخطاء إلى انتهاء صلاحية جلسة التحميل ويجب إعادة تشغيلها من خلال طلب معرّف موارد منتظم جديد للجلسة. تنتهي صلاحية جلسات التحميل أيضًا بعد أسبوع واحد من عدم النشاط.
أنواع المحتوى التي يمكن استيرادها إلى "مستندات Google"
عند إنشاء ملف في Drive، قد تحتاج إلى تحويل الملف إلى نوع ملف في Google Workspace، مثل "مستندات Google" أو "جداول بيانات Google". على سبيل المثال، قد تريد تحويل مستند من معالج النصوص المفضّل لديك إلى "مستندات Google" للاستفادة من ميزاته.
لتحويل ملف إلى نوع ملف معيّن في Google Workspace، حدِّد
Google Workspace mimeType
عند إنشاء الملف.
في ما يلي كيفية تحويل ملف CSV إلى جدول بيانات في Google Workspace:
Java
Python
Node.js
PHP
NET.
لمعرفة ما إذا كانت الإحالة الناجحة متاحة، تحقّق من صفيف importFormats
لمورد about
قبل إنشاء الملف.
تتوفّر الإحالات الناجحة المتوافقة ديناميكيًا في هذه الصفيف. في ما يلي بعض التنسيقات الشائعة
لاستيراد البيانات:
من | إلى |
---|---|
Microsoft Word وOpenDocument Text وHTML وRTF والنص العادي | مستندات Google |
Microsoft Excel وOpenDocument Spreadsheet وCSV وTSV والنصوص العادية | جداول بيانات Google |
Microsoft PowerPoint وOpenDocument Presentation | العروض التقديمية من Google |
JPEG أو PNG أو GIF أو BMP أو PDF | "مستندات Google" (يتم تضمين الصورة في مستند) |
نص عادي (نوع MIME خاص)، JSON | لغة برمجة تطبيقات Google |
عند تحميل الوسائط وتحويلها أثناء طلب update
إلىملف
"مستندات Google" أو "جداول بيانات Google" أو "العروض التقديمية من Google"، يتم استبدال
المحتوى الكامل للمستند.
عند تحويل صورة إلى مستند، يستخدم Drive ميزة التعرّف البصري على الأحرف (OCR) لتحويل الصورة إلى نص. يمكنك
تحسين جودة خوارزمية OCR من خلال تحديد رمز لغة BCP
47 الساري
في المَعلمة
ocrLanguage
. يظهر النص المستخرَج في "مستند Google" بجانب الصورة المضمّنة.
استخدام معرّف تم إنشاؤه مسبقًا لتحميل الملفات
تتيح لك Drive API استرداد قائمة بأرقام تعريف الملفات التي تم إنشاؤها مسبقًا والتي
تُستخدَم لتحميل الموارد وإنشائها. يمكن أن تستخدم طلبات التحميل وإنشاء الملفات
هذه الأرقام التعريفية التي تم إنشاؤها مسبقًا. اضبط الحقل id
في البيانات الوصفية للملف.
لإنشاء أرقام تعريف تم إنشاؤها مسبقًا، اتصل برقم files.generateIds
مع تحديد
عدد أرقام التعريف المطلوب إنشاؤها.
يمكنك إعادة محاولة عمليات التحميل بأمان باستخدام معرّفات تم إنشاؤها مسبقًا في حال حدوث خطأ أو مهلة غير محدّدة في الخادم. إذا تم إنشاء الملف بنجاح، تعرض المحاولة التالية
خطأ HTTP 409
ولا تنشئ ملفات مكرّرة.
تحديد النص القابل للفهرسة لأنواع الملفات غير المعروفة
يمكن للمستخدمين استخدام واجهة مستخدم Drive للعثور على محتوى المستند. يمكنك أيضًا
استخدام files.list
وحقل fullText
للبحث عن محتوى من تطبيقك. لمزيد من المعلومات، اطّلِع على البحث عن
الملفات والمجلدات.
يفهرس Drive المستندات تلقائيًا للبحث عندما يتعرّف على نوع الملف، بما في ذلك المستندات النصية وملفات PDF والصور التي تحتوي على نص وغيرها من الأنواع الشائعة. إذا كان تطبيقك يحفظ أنواعًا أخرى من الملفات (مثل الرسومات
والفيديوهات والاختصارات)، يمكنك تحسين إمكانية العثور عليه من خلال تقديم
نص قابل للفهرسة في حقل contentHints.indexableText
في الملف.
لمزيد من المعلومات عن النص القابل للفهرسة، يُرجى الاطّلاع على مقالة إدارة metadataملف.