تتيح لك Google Drive API تحميل بيانات الملفات عند إنشاء File
أو تعديلها. للاطّلاع على معلومات حول كيفية إنشاء File
للبيانات الوصفية فقط، يمكنك مراجعة القسم إنشاء ملفات.
يمكنك إجراء 3 أنواع من عمليات التحميل:
التحميل البسيط (
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
2,999
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
احفظ عنوان URL للجلسة القابلة للاستئناف حتى تتمكن من تحميل بيانات الملف والاستعلام عن حالة التحميل. تنتهي صلاحية عنوان URL للجلسة القابلة للاستئناف بعد أسبوع واحد.
إذا كانت لديك بيانات وصفية للملف، أضِف البيانات الوصفية إلى نص الطلب بتنسيق 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 للجلسة القابلة للاستئناف بعد أسبوع واحد.انسخ عنوان 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 إلى 2,000,000.
التعامل مع أخطاء تحميل الوسائط
عند تحميل الوسائط، اتّبِع أفضل الممارسات التالية لمعالجة الأخطاء:
- بالنسبة إلى أخطاء
5xx
، يمكنك استئناف عمليات التحميل التي يتعذّر إتمامها بسبب انقطاع الاتصال أو إعادة المحاولة. لمزيد من المعلومات عن التعامل مع أخطاء5xx
، راجِع القسم حلّ خطأ5xx
. - بالنسبة إلى
403 rate limit
خطأ، يُرجى إعادة محاولة التحميل. لمزيد من المعلومات حول التعامل مع أخطاء403 rate limit
، يمكنك الاطّلاع على حلّ403 error: Rate limit exceeded
. - لأي أخطاء
4xx
(بما في ذلك403
) أثناء عملية تحميل قابلة للاستئناف، أعِد بدء عملية التحميل. تشير هذه الأخطاء إلى انتهاء صلاحية جلسة التحميل ويجب بدؤها من خلال طلب معرّف موارد منتظم (URI) جديد للجلسة. تنتهي صلاحية جلسات التحميل أيضًا بعد أسبوع واحد من عدم النشاط.
الاستيراد إلى أنواع "مستندات Google"
عند إنشاء ملف في Drive، قد تحتاج إلى تحويله إلى نوع ملف Google Workspace، مثل مستند Google أو "جدول بيانات Google". على سبيل المثال، ربما ترغب في تحويل مستند من معالج الكلمات المفضل لديك إلى مستند Google للاستفادة من ميزاته.
لتحويل ملف إلى نوع ملف محدّد في Google Workspace، حدِّد mimeType
في Google Workspace عند إنشاء الملف.
يوضّح ما يلي كيفية تحويل ملف CSV إلى جدول بيانات Google Workspace:
لغة Java
لغة Python
Node.js
2,999
NET.
لمعرفة ما إذا كانت هناك إحالة ناجحة متاحة، اطّلِع على مصفوفة
لمحة عن المورد في importFormats
قبل إنشاء الملف. تتوفّر الإحالات الناجحة المدعومة
بشكل ديناميكي في هذه المصفوفة. بعض تنسيقات الاستيراد الشائعة هي:
من | إلى |
---|---|
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
إلى مستند أو جدول بيانات أو
عرض تقديمي، يتم استبدال المحتوى الكامل للمستند.
عند تحويل صورة إلى مستند، يستخدم Drive تقنية التعرّف البصري على الأحرف
(OCR) لتحويل الصورة إلى نص. يمكنك تحسين جودة خوارزمية OCR من خلال تحديد رمز اللغة BCP 47 الساري في معلَمة ocrLanguage
.
يظهر النص المستخرَج في المستند بجانب الصورة المضمّنة.
استخدام معرّف تم إنشاؤه مسبقًا لتحميل الملفات
تتيح لك واجهة برمجة تطبيقات Drive استرداد قائمة بمعرّفات الملفات المنشأة مسبقًا والتي يتم استخدامها لتحميل الموارد وإنشائها. يمكن لطلبات التحميل وإنشاء الملفات استخدام
هذه المعرّفات التي تم إنشاؤها مسبقًا اضبط الحقل id
في البيانات الوصفية للملف.
لإنشاء أرقام تعريف تم إنشاؤها مسبقًا، عليك استدعاء file.generateIds بعدد أرقام التعريف لإنشاءها.
يمكنك إعادة محاولة إجراء عمليات التحميل بأمان باستخدام أرقام التعريف التي تم إنشاؤها مسبقًا في حال حدوث خطأ غير محدّد في الخادم
أو انتهاء مهلة. إذا تم إنشاء الملف بنجاح، ستعرض عمليات إعادة المحاولة
اللاحقة خطأ HTTP 409
ولن تنشئ ملفات
مكررة.
تحديد نص قابل للفهرسة لأنواع الملفات غير المعروفة
يمكن للمستخدمين استخدام واجهة مستخدم Drive للبحث عن محتوى المستند. يمكنك أيضًا استخدام
files.list والحقل fullText
للبحث
عن محتوى من تطبيقك. لمزيد من المعلومات، يمكنك الاطّلاع على
البحث عن الملفات والمجلدات.
يعمل Drive تلقائيًا على فهرسة المستندات للبحث عندما يتعرف على نوع الملف، بما في ذلك المستندات النصية وملفات PDF والصور التي تتضمن نصوصًا والأنواع الشائعة الأخرى. إذا كان تطبيقك يحفظ أنواعًا أخرى من الملفات (مثل الرسومات والفيديو
والاختصارات)، يمكنك تحسين قابلية الاكتشاف من خلال توفير نص قابل للفهرسة في
الحقل contentHints.indexableText
من الملف.
لمزيد من المعلومات حول النص القابل للفهرسة، يُرجى الاطّلاع على إدارة البيانات الوصفية للملفات.