تتيح لك 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)/لطريقة التحميل باستخدام معلَمة طلب البحث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 لبيانات الملف، والتي يتم نقلها في الطلبات اللاحقة. إذا لم يتم تحديد نوع 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
فارغًا معرّف الموارد المنتظم (URI) الخاص بالجلسة القابلة للاستئناف.أضِف عنوان
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"، يتم استبدال
المحتوى الكامل للمستند.
عند تحويل صورة إلى ملف في "مستندات Google"، يستخدم تطبيق Drive
ميزة التعرّف البصري على الأحرف (OCR) لتحويل الصورة إلى نص. يمكنك
تحسين جودة خوارزمية التعرّف البصري على الحروف من خلال تحديد رمز لغة BCP
47 الساري
في المَعلمة
ocrLanguage
. يظهر النص المُستخرَج في المستند بجانب الصورة المضمّنة.
استخدام معرّف تم إنشاؤه مسبقًا لتحميل الملفات
تتيح لك Drive API استرداد قائمة بأرقام تعريف الملفات التي تم إنشاؤها مسبقًا والتي
تُستخدَم لتحميل الموارد وإنشائها. يمكن أن تستخدم طلبات التحميل وإنشاء الملفات
هذه الأرقام التعريفية التي تم إنشاؤها مسبقًا. اضبط الحقل id
في البيانات الوصفية للملف.
لإنشاء أرقام تعريف منشأة مسبقًا، يمكنك طلب files.generateIds
مع تضمين عدد المعرّفات التي سيتم إنشاؤها.
يمكنك إعادة محاولة عمليات التحميل بأمان باستخدام معرّفات تم إنشاؤها مسبقًا في حال حدوث خطأ أو مهلة غير محدّدة في الخادم. إذا تم إنشاء الملف بنجاح، تعرض المحاولة التالية
خطأ HTTP 409
ولا تنشئ ملفات مكرّرة.
تحديد النص القابل للفهرسة لأنواع الملفات غير المعروفة
يمكن للمستخدمين استخدام واجهة مستخدم Drive للعثور على محتوى المستند. يمكنك أيضًا
استخدام files.list
وحقل fullText
للبحث عن محتوى من تطبيقك. لمزيد من المعلومات، اطّلِع على البحث عن
الملفات والمجلدات.
يعمل Drive تلقائيًا على فهرسة المستندات للبحث عند التعرّف على نوع الملف، بما في ذلك المستندات النصية وملفات PDF والصور التي تحتوي على نص والأنواع الشائعة الأخرى. إذا كان تطبيقك يحفظ أنواعًا أخرى من الملفات (مثل الرسومات
والفيديوهات والاختصارات)، يمكنك تحسين إمكانية العثور عليه من خلال تقديم
نص قابل للفهرسة في حقل contentHints.indexableText
في الملف.
لمزيد من المعلومات عن النص القابل للفهرسة، يُرجى الاطّلاع على مقالة إدارة metadata للملف.