بما أنّ مشاريع "برمجة تطبيقات Google" متوفّرة على Google Drive، يمكن للمطوّرين استيراد رمز المصدر لـ "برمجة تطبيقات Google" وتصديره باستخدام واجهة برمجة تطبيقات Google Drive (يجب عدم الخلط بينها وبين خدمة Drive في "برمجة تطبيقات Google").
على سبيل المثال، يمكن للمطوّر كتابة رمز Apps Script جديد على جهازه المحلي باستخدام محرّر الرموز المفضّل لديه واستخدام نظام التحكّم في الإصدارات مثل Git للتعاون مع مطوّرين آخرين. عند الانتهاء من إصدار، يمكنها تحميل (استيراد) الملفات إلى Google Drive باستخدام واجهة REST API، حيث يمكن استخدامها مثل أي مشروع آخر في "برمجة تطبيقات Google".
يمكن إجراء تغييرات على الرمز البرمجي في النُسخ المحلية ومزامنتها مع مشروع "برمجة تطبيقات Google" باستخدام Google Drive API. يمكن تنزيل المشاريع الحالية (تصديرها) من Google Drive إلى جهاز محلي.
الميزات والقيود
إذا كنت تريد استخدام Google Drive API لاستيراد المشاريع أو تصديرها، يُرجى الانتباه إلى ما يلي:
- من المتوقّع أن تنتهي ملفات النصوص البرمجية من جهة الخادم بالامتداد ".gs". يمكنك تطوير التطبيق محليًا باستخدام ملفات js.، ولكن احرص على إعادة تسميتها لتضمين الامتداد gs. قبل استيرادها إلى Google Drive.
- يجب أن تنتهي ملفات النصوص البرمجية من جهة العميل باللاحقة ".html". ويشمل ذلك ملفات .html أو .js أو .css من جهة العميل. يمكنك مرة أخرى تطوير المحتوى محليًا باستخدام إضافات أخرى، ولكن من المهم أن يكون لديك إضافة .html قبل استيراد المحتوى إلى Google Drive.
- عند استيراد ملفات المشروع إلى Google Drive، سيتم استبدال جميع البيانات الحالية في هذه الملفات. لا يمكنك إلحاق نص جزئي أو إدراجه، بل يجب تعديل الملف بأكمله.
- يجب أن تحتوي ملفات البرامج النصية من جهة الخادم على JavaScript صالح. إذا كانت هناك أخطاء في ملفات .js الخاصة بالخادم، ستتعذّر عملية تعديل Google Drive API وسيظهر الخطأ 5xx. يمكنك منع حدوث ذلك من خلال فحص التعليمات البرمجية قبل استيرادها.
- لا يمكن استيراد الملفات الفارغة. سيتعذّر تنفيذ طلب التعديل في Google Drive API وسيظهر الخطأ 5xx إذا حاولت تحميل ملف فارغ.
- يمكن استيراد النصوص البرمجية المستقلة أو تصديرها فقط. لا يمكن الوصول إلى النصوص البرمجية المرتبطة بالحاويات من خلال Google Drive API.
- يمكن استيراد أو تصدير رمز المصدر فقط. ولا يتم عرض موارد مثل خصائص المشاريع أو السجلات من خلال Google Drive API. لا يمكن تنفيذ إجراءات مثل تحديد إصدار النص البرمجي أو نشره أو تنفيذه من خلال Google Drive API.
- لا يقتصر الأمر على ملف
Code.gsواحد على الخادم. يمكنك توزيع رمز الخادم على ملفات متعددة لتسهيل عملية التطوير. يتم تحميل جميع ملفات الخادم في مساحة الاسم العامة نفسها، لذا استخدِم فئات JavaScript عندما تريد توفير تغليف آمن.
واجهة برمجة تطبيقات Drive
تتيح Google Drive API للمطوّرين الوصول إلى الملفات في Google Drive آليًا. تستخدم واجهة برمجة التطبيقات هذه GET لتنزيل الملفات وPUT/POST لتحميل الملفات. يُرجى الرجوع إلى صفحة "نظرة عامة على Google Drive API"
للحصول على مستندات مفصّلة وبدء سريع.
سيركّز هذا الدليل على عرض الملفات ونقلها باستخدام مورد الملفات باستخدام طلبات البيانات من واجهة برمجة التطبيقات التالية:
التفويض
يجب أن يوافق مستخدم مصادَق عليه على كلّ الطلبات الموجّهة إلى Google Drive API من خلال بروتوكول OAuth 2.0. لمزيد من التفاصيل، يُرجى الرجوع إلى مستندات تفويض Google Drive API.
بالإضافة إلى النطاقات الأخرى التي قد يحتاجها التطبيق (مثل https://www.googleapis.com/auth/drive)، يجب أن تطلب جميع التطبيقات التي تحاول استيراد مشاريع Google Apps Script أو تصديرها النطاق الخاص التالي:
https://www.googleapis.com/auth/drive.scripts
عرض قائمة بالمشاريع الحالية
لإدراج جميع مشاريع Apps Script في Drive، استخدِم مورد الملفات
للبحث عن الملفات التي يكون نوع MIME الخاص بها هو application/vnd.google-apps.script.
لفلترة الردّ بحيث يتضمّن الملفات التي تملكها فقط، أدرِج مَعلمة البحث 'me' in owners.
في ما يلي نموذج طلب وردّ يعرض مصفوفة من مشاريع Apps Script تم إرجاعها من خلال استجابة JSON.
GET https://www.googleapis.com/drive/v2/files?q=mimeType%3D'application%2Fvnd.google-apps.script'+and+'me'+in+owners Authorization: Bearer ya29.fakebearerstring
{ "kind": "drive#fileList", "etag": "\"kjsas92/f3zGUXczKMxEB_9ZTMRFOF3d1ZU\"", "selfLink": "https://www.googleapis.com/drive/v2/files?q=mimeType%3D'application/vnd.google-apps.script'+and+'me'+in+owners", "items": [ { "kind": "drive#file", "id": "1vi0uwcMdHsRv1YFtgq7XdiTGSdqgjIYpdQNC0A_Udn79LOhH0vYL132D", "etag": "\"kjsas92/MTM3MDk3ODY5ODQyNg\"", "selfLink": "https://www.googleapis.com/drive/v2/files/1vi0uwcMdHsRv1YFtgq7XdiTGSdqgjIYpdQNC0A_Udn79LOhH0vYL132D", "alternateLink": "https://script.google.com/a/google.com/d/1vi0uwcMdHsRv1YFtgq7XdiTGSdqgjIYpdQNC0A_Udn79LOhH0vYL132D/edit?usp=drivesdk", "iconLink": "https://ssl.gstatic.com/docs/doclist/images/icon_11_script_list.png", "title": "Mail merge", "mimeType": "application/vnd.google-apps.script", "description": "", "labels": { "starred": false, "hidden": false, "trashed": true, "restricted": false, "viewed": true }, "createdDate": "2013-06-11T19:24:45.188Z", "modifiedDate": "2013-06-11T19:24:58.426Z", "modifiedByMeDate": "2013-06-11T19:24:58.426Z", "lastViewedByMeDate": "2013-06-11T19:24:58.426Z", "parents": [ { "kind": "drive#parentReference", "id": "0APdyIOzo7bWDUk9PVA", "selfLink": "https://www.googleapis.com/drive/v2/files/1vi0uwcMdHsRv1YFtgq7XdiTGSdqgjIYpdQNC0A_Udn79LOhH0vYL132D/parents/0APdyIOzo7bWDUk9PVA", "parentLink": "https://www.googleapis.com/drive/v2/files/0APdyIOzo7bWDUk9PVA", "isRoot": true } ], "exportLinks": { "application/json": "https://script.google.com/feeds/download/export?id=1234567890abcefghijklmnopqrstuvwxyz&format=json" }, "userPermission": { "kind": "drive#permission", "etag": "\"kjsas92/259X2r5DVstv1CcIQTjt_RQPSW8\"", "id": "me", "selfLink": "https://www.googleapis.com/drive/v2/files/1vi0uwcMdHsRv1YFtgq7XdiTGSdqgjIYpdQNC0A_Udn79LOhH0vYL132D/permissions/me", "role": "owner", "type": "user" }, "quotaBytesUsed": "0", "ownerNames": [ "John Doe" ], "owners": [ { "kind": "drive#user", "displayName": "John Doe", "picture": { "url": "https://lh4.googleusercontent.com/-yd1rIb6Pe2Y/AAAAAAAAAAI/AAAAAAAAAGs/PP5vTuZonik/s64/photo.jpg" }, "isAuthenticatedUser": true, "permissionId": "1234566789" } ], "lastModifyingUserName": "John Doe", "lastModifyingUser": { "kind": "drive#user", "displayName": "John Doe", "picture": { "url": "https://lh4.googleusercontent.com/-yd1rIb6Pe2Y/AAAAAAAAAAI/AAAAAAAAAGs/PP5vTuZonik/s64/photo.jpg" }, "isAuthenticatedUser": true, "permissionId": "1234566789" }, "editable": true, "writersCanShare": true, "shared": false, "explicitlyTrashed": true, "appDataContents": false } ] }
إذا كنت تعرف رقم تعريف ملف مشروع "برمجة التطبيقات"، يمكنك استرداده مباشرةً باستخدام طلب واجهة برمجة التطبيقات التالي:
GET https://www.googleapis.com/drive/v2/files/1234567890abcefghijklmnopqrstuvwxyz
Authorization: Bearer ya29.fakebearerstring
تصدير المشاريع من Drive
بعد الحصول على مورد File من واجهة برمجة التطبيقات، ستتضمّن السمة exportLinks عنوان URL يمكن استخدامه لجلب محتوى المشروع كبيانات JSON. في ما يلي عيّنة من الشكل الذي قد يبدو عليه عنوان URL هذا:
https://script.google.com/feeds/download/export?id=1234567890abcefghijklmnopqrstuvwxyz&format=json
أرسِل طلبًا إلى عنوان URL هذا لاسترداد محتوى المشروع نفسه.
تأكَّد من تضمين عنوان Authorization مع رمز OAuth Bearer نفسه.
في ما يلي نموذج طلب وردّ:
GET https://script.google.com/feeds/download/export?id=1234567890abcefghijklmnopqrstuvwxyz&format=json Authorization: Bearer ya29.fakebearerstring
{ "files": [ { "id":"9basdfbd-749a-4as9b-b9d1-d64basdf803", "name":"Code", "type":"server_js", "source":"function doGet() {\n return HtmlService.createHtmlOutputFromFile(\u0027index\u0027);\n}\n" }, { "id":"3asf7c0d-1afb-4a9-8431-5asdfc79e7ae", "name":"index", "type":"html", "source":"\u003chtml\u003e\n \u003cbody\u003e\n Hello, world!\n \u003c/body\u003e\n\u003c/html\u003e" } ] }
يتضمّن المثال أعلاه رمزًا لتطبيق ويب بسيط من دليل HTML
Service. يُرجى العِلم
أنّك ستتلقّى مصفوفة من Files، كلّ منها تتضمّن السمات الأربع التالية:
id |
المعرّف الداخلي لملف ضمن مشروع، وهو مطلوب للإشارة إلى هذا الملف أثناء التحديثات. |
name |
اسم الملف بدون امتدادات، كما هو معروض في "محرّر النصوص البرمجية". |
type |
نوعا الملفات هما server_js وhtml. |
source |
رمز المصدر المرمّز المتضمّن في الملف |
استيراد المشاريع إلى Drive
لتعديل مشروع حالي، أرسِل طلب HTTP PUT إلى واجهة برمجة التطبيقات الخاصة بملف
update مع fileId المناسب.
يعرض المثال أدناه نموذجًا لمعاملة خاصة بجزء تحميل الوسائط. باستخدام إحدى مكتبات البرامج، يمكن لتطبيقك بسهولة تضمين البيانات الوصفية والوسائط في طلب التحميل نفسه. يُرجى العِلم أنّ العنوان
Content-Type يحدّد نوع المحتوى الذي تم تحميله في هذه الحالة.
PUT https://www.googleapis.com/upload/drive/v2/files/1234567890abcefghijklmnopqrstuvwxyz Authorization: Bearer ya29.fakebearerestring Content-Type: application/vnd.google-apps.script+json
{ "files": [ { "id":"9basdfbd-749a-4as9b-b9d1-d64basdf803", "name":"Code", "type":"server_js", "source":"function doGet() {\n return HtmlService.createHtmlOutputFromFile(\u0027index\u0027);\n}\n" }, { "id":"3asf7c0d-1afb-4a9-8431-5asdfc79e7ae", "name":"index", "type":"html", "source":"\u003chtml\u003e\n \u003cbody\u003e\n New message!!\n \u003c/body\u003e\n\u003c/html\u003e" } ] }
إنشاء ملفات جديدة ضمن مشروع
لإنشاء ملف جديد ضمن مشروع، أرسِل طلب PUT لملف بدون السمة id. إذا أدرجت ملفًا يتضمّن معرّفًا غير معروف، سيعرض النظام رسالة خطأ.
حذف الملفات داخل مشروع
لحذف ملف من مشروع، أرسِل طلب PUT لا يتضمّن هذا الملف (ولكن يتضمّن جميع الملفات الأخرى في المشروع). سيتم حذف أي ملف لم يتم إرساله مرة أخرى أثناء عملية الاستيراد من الخادم.
إعادة تسمية الملفات ضِمن مشروع
لإعادة تسمية ملف ضمن مشروع، أرسِل طلب PUT مع id الحالي ولكن مع name جديد. يُرجى العِلم أنّ الخادم يتجاهل أي محاولات للتغيير إلى type.
إنشاء مشروع جديد
لإنشاء مشروع جديد، أرسِل طلب POST إلى واجهة برمجة التطبيقات الخاصة بالملف
insert. كما هو الحال مع طلب update، يمكنك استخدام مكتبة برامج للعميل لتضمين بيانات وصفية، مثل اسم المشروع ووصفه.
في ما يلي نموذج لمعاملة تحميل الوسائط. سيؤدي ذلك إلى إنشاء مشروع باسم "بلا عنوان" في Drive. المعلَمة convert في عنوان URL مطلوبة.
كما هو الحال مع طلب update، يجب تضمين عنوان Content-Type.
POST https://www.googleapis.com/upload/drive/v2/files?convert=true Authorization: Bearer ya29.fakebearerestring Content-Type: application/vnd.google-apps.script+json
{ "files": [ { "name":"Code", "type":"server_js", "source":"function doGet() {\n return HtmlService.createHtmlOutputFromFile(\u0027index\u0027);\n}\n" }, { "name":"index", "type":"html", "source":"\u003chtml\u003e\n \u003cbody\u003e\n Hello, world!!\n \u003c/body\u003e\n\u003c/html\u003e" } ] }