تتيح لك 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). يمكنك أيضًا استخدام عمليات التحميل القابلة للاستئناف في الحالات التي تريد فيها عرض شريط تقدم التحميل.
يتألف التحميل القابل للاستئناف من عدة خطوات عالية المستوى:
- أرسل الطلب الأولي واسترجع معرف الموارد المنتظم (URI) للجلسة القابلة للاستئناف.
- حمِّل البيانات وتتبَّع حالة التحميل.
- (اختياري) في حال إزعاج التحميل، يمكنك استئنافه.
إرسال الطلب الأولي
لبدء عملية تحميل قابلة للاستئناف، استخدِم طريقة 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 للجلسة القابل للاستئناف حتى تتمكن من تحميل بيانات الملف والاستعلام عن حالة التحميل. تنتهي صلاحية معرّف الموارد المنتظم (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) للجلسة القابلة للاستئناف لتحميل بيانات الملف والاستعلام عن حالة التحميل. تنتهي صلاحية معرّف الموارد المنتظم (URI) للجلسة القابلة للاستئناف بعد أسبوع واحد.انسخ عنوان URL للجلسة القابل للاستئناف واحفظه.
انتقِل إلى تحميل المحتوى.
تحميل المحتوى
هناك طريقتان لتحميل ملف في جلسة قابلة للاستئناف:
- تحميل محتوى في طلب واحد: استخدِم هذا الأسلوب عندما يكون من الممكن تحميل الملف في طلب واحد، أو إذا لم يكن هناك حد زمني ثابت لأي طلب فردي، أو إذا لم تكن بحاجة إلى عرض مؤشر لمستوى تقدّم التحميل. وهذا الأسلوب هو الأفضل لأنّه يتطلّب عددًا أقل من الطلبات وينتج عنه أداء أفضل.
تحميل المحتوى في مقاطع متعددة: استخدِم هذا الأسلوب إذا كان عليك تقليل كمية البيانات المنقولة في أي طلب واحد. قد تحتاج إلى تقليل البيانات المنقولة عندما يكون هناك حد زمني ثابت للطلبات الفردية، كما هو الحال مع فئات معيّنة من طلبات App Engine. هذه الطريقة مفيدة أيضًا إذا كان عليك توفير مؤشر مخصّص لعرض مدى تقدّم التحميل.
HTTP - طلب واحد
- أنشئ طلب
PUT
لمعرّف الموارد المنتظم (URI) للجلسة القابلة للاستئناف. - أضِف بيانات الملف إلى نص الطلب.
- أضِف عنوان HTTP لطول المحتوى، والذي يتم ضبطه على عدد وحدات البايت في الملف.
- أرسِل الطلب. إذا تمت مقاطعة طلب التحميل، أو إذا تلقّيت استجابة
5xx
، اتّبِع الإجراء الوارد في المقالة استئناف عملية تحميل تمت مقاطعتها.
HTTP - طلبات متعددة
أنشئ طلب
PUT
لمعرّف الموارد المنتظم (URI) للجلسة القابلة للاستئناف.أضِف بيانات المقطع إلى نص الطلب. أنشئ مقاطع بحجم مضاعفات يبلغ حجمها 256 كيلوبايت (256 × 1024 بايت)، باستثناء المقطع النهائي الذي يكمل التحميل. أبقِ حجم المقطع كبيرًا قدر الإمكان حتى يكون التحميل فعالاً.
إضافة عناوين HTTP التالية:
Content-Length
: يجب ضبط عدد وحدات البايت في المقطع الحالي.Content-Range
. يمكنك ضبط هذا الإعداد لعرض وحدات البايت في الملف الذي تريد تحميله. على سبيل المثال، يوضّحContent-Range: bytes 0-524287/2000000
أنّك تحمِّل أول 524,288 بايت (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 إلى 2000000.
التعامل مع أخطاء تحميل الوسائط
عند تحميل وسائط، اتّبِع أفضل الممارسات التالية لمعالجة الأخطاء:
- بالنسبة إلى أخطاء
5xx
، يمكنك استئناف أو إعادة محاولة عمليات التحميل التي تعذّر تنفيذها بسبب انقطاعات الاتصال. لمزيد من المعلومات حول التعامل مع أخطاء5xx
، يمكنك الاطّلاع على الأخطاء في 500 و502 و503 و504. - بالنسبة إلى
403 rate limit
خطأ، يُرجى إعادة محاولة التحميل. لمزيد من المعلومات حول التعامل مع أخطاء403 rate limit
، يمكنك الاطّلاع على الخطأ 403:rateLimitExceeded
. - بالنسبة إلى أي أخطاء
4xx
(بما في ذلك403
) خلال عملية تحميل قابلة للاستئناف، يُرجى إعادة بدء عملية التحميل. تشير هذه الأخطاء إلى انتهاء صلاحية جلسة التحميل ويجب بدؤها من خلال طلب معرّف موارد منتظم (URI) جديد للجلسة. تنتهي صلاحية جلسات التحميل أيضًا بعد مرور أسبوع على عدم النشاط.
الاستيراد إلى أنواع "مستندات Google"
عند إنشاء ملف في Drive، قد تحتاج إلى تحويله إلى نوع ملف Google Workspace، مثل "مستندات Google" أو "جداول بيانات Google". على سبيل المثال، ربما ترغب في تحويل مستند من معالج الكلمات المفضل لديك إلى محرر المستندات للاستفادة من ميزاته.
لتحويل ملف إلى نوع ملف محدّد في Google Workspace، حدِّد mimeType
في Google Workspace عند إنشاء الملف.
يوضّح ما يلي كيفية تحويل ملف 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) لتحويل الصورة إلى نص. يمكنك
تحسين جودة خوارزمية التعرّف البصري على الأحرف (OCR) عن طريق تحديد رمز اللغة BCP
47 الساري
في
مَعلمة
ocrLanguage
. يظهر النص المُستخرَج في المستند بجانب الصورة المضمّنة.
استخدام رقم تعريف تم إنشاؤه مسبقًا لتحميل الملفات
تتيح لك واجهة برمجة تطبيقات Drive استرداد قائمة بمعرّفات الملفات التي تم إنشاؤها مسبقًا والتي تُستخدَم لتحميل الموارد وإنشائها. يمكن لطلبات التحميل وإنشاء الملفات استخدام
هذه المعرّفات التي تم إنشاؤها مسبقًا اضبط الحقل id
في البيانات الوصفية للملف.
لإنشاء أرقام تعريف تم إنشاؤها مسبقًا، يمكنك استدعاء
files.generateIds
مع إدراج
عدد أرقام التعريف لإنشائها.
يمكنك إعادة محاولة التحميل بأمان باستخدام معرّفات تم إنشاؤها مسبقًا في حال حدوث خطأ غير محدد في الخادم أو حدوث مهلة غير محددة. إذا تم إنشاء الملف بنجاح، ستعرض عمليات
إعادة المحاولة التالية خطأ HTTP 409
ولن تنشئ ملفات مكررة.
تحديد نص قابل للفهرسة لأنواع الملفات غير المعروفة
يمكن للمستخدمين استخدام واجهة مستخدم Drive للعثور على محتوى المستند. يمكنك أيضًا استخدام files.list
والحقل fullText
للبحث عن محتوى من تطبيقك. لمزيد من المعلومات، راجع البحث عن الملفات والمجلدات.
يفهرس Drive تلقائيًا المستندات للبحث عندما يتعرّف على
نوع الملف، بما في ذلك المستندات النصية وملفات PDF والصور التي تحتوي على نصوص والأنواع الشائعة الأخرى. إذا كان تطبيقك يحفظ أنواعًا أخرى من الملفات (مثل الرسومات والفيديوهات والاختصارات)، يمكنك تحسين قابلية اكتشاف التطبيق من خلال تقديم نص قابل للفهرسة في الحقل contentHints.indexableText
من الملف.
لمزيد من المعلومات عن النص القابل للفهرسة، يُرجى الاطّلاع على إدارة البيانات الوصفية للملفات.