تتيح Google Drive API عدة أنواع من إجراءات التنزيل والتصدير، كما هو موضّح في الجدول التالي:
| إجراءات التنزيل |
|
||||
| إجراءات التصدير |
|
قبل تنزيل محتوى الملف أو تصديره، تأكَّد من أنّ المستخدمين يمكنهم تنزيل الملف باستخدام الحقل capabilities.canDownload في مورد files.
للحصول على أوصاف لأنواع الملفات المذكورة هنا، بما في ذلك ملفات blob وملفات Google Workspace، يُرجى الاطّلاع على أنواع الملفات.
يقدّم الجزء المتبقي من هذا المستند تعليمات مفصّلة حول تنفيذ هذه الأنواع من إجراءات التنزيل والتصدير.
تنزيل محتوى ملف blob
لتنزيل ملف كائن ثنائي كبير الحجم مخزَّن على Drive، استخدِم طريقة files.get مع معرّف الملف المطلوب تنزيله ومعلَمة عنوان URL alt=media. تخبر مَعلمة عنوان URL alt=media الخادم بأنّه يتم طلب تنزيل المحتوى كتنسيق استجابة بديل.
مَعلمة عنوان URL alt=media هي مَعلمة نظام متاحة في جميع واجهات Google REST API. إذا كنت تستخدم مكتبة برامج لعميل Drive API، لن تحتاج إلى ضبط هذه المَعلمة بشكل صريح لأنّ طريقة مكتبة البرامج للعميل تضيف مَعلمة عنوان URL alt=media إلى طلب HTTP الأساسي.
تعرض عيّنات الرموز البرمجية التالية كيفية استخدام طريقة files.get لتنزيل ملف:
برمجة التطبيقات
/**
* Downloads a file from Drive.
* @param {string} fileId The ID of the file to download.
* @return {Blob} The file content as a Blob.
*/
function downloadFile(fileId) {
var url = 'https://www.googleapis.com/drive/v3/files/' + fileId + '?alt=media';
var response = UrlFetchApp.fetch(url, {
headers: {
'Authorization': 'Bearer ' + ScriptApp.getOAuthToken()
}
});
return response.getBlob();
}
جافا
Python
Node.js
PHP
NET.
curl
curl -L "https://www.googleapis.com/drive/v3/files/FILE_ID?alt=media" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--output "FILE_NAME"
غيِّر القيم في السلسلة على الشكل التالي:
- FILE_ID: رقم تعريف الملف المطلوب تنزيله
- ACCESS_TOKEN: الرمز المميز للوصول الذي يمنح إذن الوصول إلى واجهة برمجة التطبيقات.
- FILE_NAME: اسم ملف الإخراج
يجب أن يتم منح إذن بتنزيل الملفات التي تم بدء تنزيلها من تطبيقك باستخدام نطاق يسمح بالوصول إلى محتوى الملفات للقراءة. على سبيل المثال، لا يُسمح لتطبيق يستخدم نطاق drive.readonly.metadata بتنزيل محتوى الملف.
تستخدم نماذج رموز مكتبة البرامج للعملاء نطاق الملفات drive المحظور الذي يتيح للمستخدمين عرض جميع ملفاتك على Drive وإدارتها. لمزيد من المعلومات حول نطاقات Drive، يُرجى الاطّلاع على مقالة اختيار نطاقات Google Drive API.
يمكن للمستخدمين الذين لديهم أذونات owner (لملفات "ملفاتي") أو أذونات organizer (لملفات مساحة التخزين السحابي المشتركة) حظر تنزيل الملفات من خلال العنصر DownloadRestrictionsMetadata. لمزيد من المعلومات، يُرجى الاطّلاع على منع المستخدمين من تنزيل ملفك أو طباعته أو نسخه.
يمكن لمالك الملف فقط تنزيل الملفات التي تم تصنيفها على أنّها مسيئة (مثل البرامج الضارة).
بالإضافة إلى ذلك، يجب تضمين مَعلمة طلب البحث get acknowledgeAbuse=true للإشارة إلى أنّ المستخدم أقرّ بمخاطر تنزيل برامج غير مرغوب فيها أو ملفات أخرى مسيئة. يجب أن يحذّر تطبيقك المستخدم بشكل تفاعلي قبل استخدام مَعلمة طلب البحث هذه.
التنزيل الجزئي
يتضمّن التنزيل الجزئي تنزيل جزء محدّد فقط من الملف. يمكنك تحديد جزء الملف الذي تريد تنزيله باستخدام نطاق بايت مع العنوان Range. على سبيل المثال:
Range: bytes=500-999
تنزيل محتوى ملف كائن ثنائي كبير الحجم (blob) في إصدار سابق
يمكنك فقط تنزيل مراجعات محتوى ملفات الكائنات الثنائية الكبيرة التي تم وضع علامة "الاحتفاظ بها للأبد" عليها. إذا أردت تنزيل نسخة معدَّلة، عليك ضبطها على "الاحتفاظ بها للأبد" أولاً. لمزيد من المعلومات، يُرجى الاطّلاع على تحديد المراجعات التي يجب حفظها من الحذف التلقائي.
لتنزيل محتوى ملفات blob في إصدار سابق، استخدِم طريقة
revisions.get مع رقم تعريف
الملف المطلوب تنزيله ورقم تعريف المراجعة ومعلَمة عنوان URL alt=media. تُعلم مَعلمة عنوان URL
alt=media الخادم بأنّه يتم طلب تنزيل المحتوى كتنسيق ردّ بديل. على غرار files.get، تقبل الطريقة revisions.get أيضًا مَعلمة طلب البحث الاختيارية acknowledgeAbuse والعنوان Range. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة إدارة العمليات الطويلة الأمد.
curl
curl -L "https://www.googleapis.com/drive/v3/files/FILE_ID/revisions/REVISION_ID?alt=media" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--output "FILE_NAME"
غيِّر القيم في السلسلة على الشكل التالي:
- FILE_ID: رقم تعريف الملف المطلوب تنزيله
- REVISION_ID: معرّف النسخة السابقة المطلوب تنزيلها
- ACCESS_TOKEN: الرمز المميز للوصول الذي يمنح إذن الوصول إلى واجهة برمجة التطبيقات.
- FILE_NAME: اسم ملف الإخراج
تنزيل محتوى ملف blob في متصفّح
لتنزيل محتوى ملفات blob المخزّنة على Drive من خلال متصفّح بدلاً من واجهة برمجة التطبيقات، استخدِم الحقل webContentLink الخاص بمورد files. إذا كان لدى المستخدم إذن بتنزيل الملف، سيتم عرض رابط لتنزيل الملف ومحتواه. يمكنك إما إعادة توجيه المستخدم إلى عنوان URL هذا أو تقديمه كرابط قابل للنقر.
curl
curl "https://www.googleapis.com/drive/v3/files/FILE_ID?fields=webContentLink" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--header "Accept: application/json"
غيِّر القيم في السلسلة على الشكل التالي:
- FILE_ID: معرّف الملف الذي تريد الحصول على رابط تنزيله.
- ACCESS_TOKEN: الرمز المميز للوصول الذي يمنح إذن الوصول إلى واجهة برمجة التطبيقات.
تنزيل محتوى ملف blob باستخدام عمليات طويلة الأمد
لتنزيل محتوى ملفات blob باستخدام العمليات الطويلة الأمد (LRO)، استخدِم طريقة files.download مع رقم تعريف الملف المطلوب تنزيله. يمكنك اختياريًا ضبط معرّف المراجعة.
هذه هي الطريقة الوحيدة لتنزيل ملفات Google Vids. إذا حاولت تصدير ملفات Google Vids، سيظهر لك الخطأ fileNotExportable.
لمزيد من المعلومات، يُرجى الاطّلاع على إدارة العمليات الطويلة الأمد.
curl
يبدأ أمر curl التالي عملية LRO ويعرض استجابة JSON. لتنزيل الملف أو طلب بيانات LRO، عليك إرسال طلب آخر باستخدام المعرّف الذي تم إرجاعه للحصول على عنوان URL الخاص بالمحتوى. بعد ذلك، يمكنك إرسال طلب curl نهائي إلى عنوان URL هذا لتنزيل الملف. لمزيد من المعلومات، يُرجى الاطّلاع على إدارة العمليات الطويلة الأمد.
curl --request POST "https://www.googleapis.com/drive/v3/files/FILE_ID/download?mimeType=video/mp4" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--header "Content-Length: 0" \
--header "Accept: application/json"
غيِّر القيم في السلسلة على الشكل التالي:
- FILE_ID: رقم تعريف الملف المطلوب تنزيله
- ACCESS_TOKEN: الرمز المميز للوصول الذي يمنح إذن الوصول إلى واجهة برمجة التطبيقات.
تصدير محتوى مستندات Google Workspace
لتصدير محتوى بايت لمستند Google Workspace، استخدِم طريقة files.export مع معرّف الملف المطلوب تصديره ونوع MIME الصحيح. يقتصر حجم المحتوى الذي يتم تصديره على 10 ميغابايت.
تعرض عيّنات الرموز البرمجية التالية كيفية استخدام طريقة files.export لتصدير مستند Google Workspace بتنسيق PDF:
برمجة التطبيقات
/**
* Exports a Google Workspace document.
* @param {string} fileId The ID of the file to export.
* @param {string} mimeType The MIME type to export to.
* @return {Blob} The exported content as a Blob.
*/
function exportPdf(fileId, mimeType) {
var url = 'https://www.googleapis.com/drive/v3/files/' + fileId + '/export?mimeType=' + encodeURIComponent(mimeType);
var response = UrlFetchApp.fetch(url, {
headers: {
'Authorization': 'Bearer ' + ScriptApp.getOAuthToken()
}
});
return response.getBlob();
}
جافا
Python
Node.js
PHP
NET.
curl
curl -L "https://www.googleapis.com/drive/v3/files/FILE_ID/export?mimeType=application/pdf" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--output "FILE_NAME.pdf"
غيِّر القيم في السلسلة على الشكل التالي:
- FILE_ID: رقم تعريف الملف المطلوب تنزيله
- ACCESS_TOKEN: الرمز المميز للوصول الذي يمنح إذن الوصول إلى واجهة برمجة التطبيقات.
- FILE_NAME: اسم ملف الإخراج
تستخدم نماذج رموز مكتبة البرامج drive النطاق المحظور الذي يتيح للمستخدمين عرض جميع ملفاتك على Drive وإدارتها. لمزيد من المعلومات حول نطاقات Drive، يُرجى الاطّلاع على مقالة اختيار نطاقات Google Drive API.
تحدّد عيّنات الرمز البرمجي أيضًا نوع MIME للتصدير على أنّه application/pdf. للحصول على قائمة كاملة بجميع أنواع MIME التي يمكن تصديرها والمتوافقة مع كل مستند من مستندات Google Workspace، يُرجى الرجوع إلى أنواع MIME التي يمكن تصديرها لمستندات Google Workspace.
تصدير محتوى مستند Google Workspace في متصفّح
لتصدير محتوى مستند Google Workspace من خلال متصفّح، استخدِم الحقل
exportLinks الخاص بمورد
files. استنادًا إلى نوع المستند، يتم عرض رابط لتنزيل الملف ومحتواه لكل نوع MIME متاح. يمكنك إما إعادة توجيه المستخدم إلى عنوان URL أو تقديمه كرابط قابل للنقر.
curl
curl "https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,exportLinks" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--header "Accept: application/json"
غيِّر القيم في السلسلة على الشكل التالي:
- FILE_ID: معرّف الملف الذي تريد الحصول على رابط تنزيله.
- ACCESS_TOKEN: الرمز المميز للوصول الذي يمنح إذن الوصول إلى واجهة برمجة التطبيقات.
تصدير محتوى مستند Google Workspace في إصدار سابق ضمن متصفّح
لتصدير محتوى مستند Google Workspace في إصدار سابق ضمن متصفّح، استخدِم طريقة revisions.get مع معرّف الملف المطلوب تنزيله ومعرّف المراجعة لإنشاء رابط تصدير يمكنك من خلاله إجراء عملية التنزيل. إذا كان لدى المستخدم إذن بتنزيل الملف، سيتم عرض رابط لتنزيل الملف ومحتواه. يمكنك إما إعادة توجيه المستخدم إلى عنوان URL هذا، أو تقديمه كرابط قابل للنقر.
curl
curl "https://www.googleapis.com/drive/v3/files/FILE_ID/revisions/REVISION_ID?fields=id,name,exportLinks" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--header "Accept: application/json"
غيِّر القيم في السلسلة على الشكل التالي:
- FILE_ID: رقم تعريف الملف المطلوب تنزيله
- REVISION_ID: معرّف النسخة السابقة المطلوب تنزيلها
- ACCESS_TOKEN: الرمز المميز للوصول الذي يمنح إذن الوصول إلى واجهة برمجة التطبيقات.
تصدير محتوى مستندات Google Workspace باستخدام العمليات الطويلة الأمد
لتصدير محتوى مستند Google Workspace باستخدام عمليات طويلة الأمد (LRO)، استخدِم طريقة files.download مع معرّف الملف الذي تريد تنزيله ومعرّف المراجعة. لمزيد من المعلومات،
يُرجى الاطّلاع على إدارة العمليات الطويلة الأمد.
curl
يبدأ أمر curl التالي عملية LRO ويعرض استجابة JSON. لتنزيل الملف أو طلب بيانات LRO، عليك إرسال طلب آخر باستخدام المعرّف الذي تم إرجاعه للحصول على عنوان URL الخاص بالمحتوى. بعد ذلك، يمكنك إرسال طلب curl نهائي إلى عنوان URL هذا لتنزيل الملف. لمزيد من المعلومات، يُرجى الاطّلاع على إدارة العمليات الطويلة الأمد.
curl --request POST "https://www.googleapis.com/drive/v3/files/FILE_ID/download?mimeType=MIME_TYPE&revisionId=REVISION_ID" \
--header "Authorization: Bearer ACCESS_TOKEN" \
--header "Content-Length: 0" \
--header "Accept: application/json"
غيِّر القيم في السلسلة على الشكل التالي:
- FILE_ID: رقم تعريف الملف المطلوب تنزيله
- MIME_TYPE: نوع MIME الذي سيتم التصدير إليه
- REVISION_ID: معرّف النسخة السابقة المطلوب تنزيلها
- ACCESS_TOKEN: الرمز المميز للوصول الذي يمنح إذن الوصول إلى واجهة برمجة التطبيقات.