استيراد المشروعات وتصديرها

بما أنّ مشاريع Apps Script تُحفظ على Google Drive، يمكن للمطوّرين استيراد رمز Apps Script المصدر و تصديره باستخدام Google Drive API (يجب عدم الخلط بينه وبين خدمة Drive في Apps Script).

على سبيل المثال، يمكن لمطوّر البرامج إنشاء رمز Apps Script جديد على جهازه المحلي باستخدام محرِّر الرموز المفضّل لديه واستخدام نظام التحكّم في الإصدارات مثل Git للتعاون مع مطوّرين آخرين. عند اكتمال أحد الإصدارات، يمكنها تحميل (استيراد) الملفات إلى Google Drive باستخدام واجهة برمجة التطبيقات REST API، حيث يمكن استخدامها مثل أي مشروع آخر من مشاريع Apps Script.

يمكن إجراء تغييرات على الرموز البرمجية في النُسخ المحلية ومزامنتها مع مشروع Apps Script باستخدام واجهة برمجة التطبيقات Google Drive API. يمكن تنزيل المشاريع الحالية (تصديرها) من Google Drive إلى جهاز كمبيوتر.

الميزات والقيود

إذا كنت تريد استخدام Google Drive API لاستيراد المشاريع أو تصديرها، يُرجى مراعاة ما يلي:

  1. من المتوقّع أن تنتهي ملفات النصوص البرمجية من جهة الخادم بالامتداد ".gs". يمكنك التطوير على الجهاز باستخدام ملفات js.، ولكن احرص على إعادة التسمية لتضمين امتداد .gs قبل الاستيراد إلى Google Drive.
  2. يجب أن تنتهي ملفات النصوص البرمجية من جهة العميل بـ "‎.html". ويشمل ذلك ملفات html .أو js. أو css .من جهة العميل. مرة أخرى، يمكنك تطوير المحتوى على الجهاز باستخدام إضافات أخرى، ولكن من المهم توفُّر إضافة ‎ .html قبل استيراد المحتوى إلى Google Drive.
  3. عند استيراد ملفات المشروع إلى Google Drive، سيتم استبدال كل البيانات الحالية في تلك الملفات. لا يمكنك إلحاق نص جزئي أو إدراجه، ويجب تعديل الملف بأكمله.
  4. يجب أن تحتوي ملفات النصوص البرمجية من جهة الخادم على JavaScript صالح. في حال حدوث أخطاء في ملفات js .على الخادم، سيؤدي طلب تعديل Google Drive API إلى تعذُّر إكماله مع ظهور خطأ 5xx. يمكنك منع حدوث ذلك من خلال فحص التعليمات البرمجية بحثًا عن الأخطاء قبل استيرادها.
  5. لا يمكن استيراد الملفات الفارغة. سيتعذّر إكمال طلب تعديل Google Drive API بظهور خطأ 5xx إذا حاولت تحميل ملف فارغ.
  6. يمكن استيراد النصوص البرمجية المستقلة أو تصديرها فقط. لا يمكن الوصول إلى النصوص البرمجية المرتبطة بالحاويات من خلال Google Drive API.
  7. يمكن استيراد أو تصدير الرمز المصدر فقط. ولا يتم أيضًا عرض موارد مثل ملفّات مشاريع أو السجلات من خلال Google Drive API. لا يمكن تنفيذ إجراءات مثل تحديد إصدار النص البرمجي أو نشره أو تنفيذه من خلال Google Drive API.
  8. لست محدودًا بملف 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" أو تصديرها النطاق الخاص التالي:

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
  }
 ]
}

إذا كنت تعرف رقم تعريف ملف مشروع "برمجة تطبيقات Google"، يمكنك استرجاعه مباشرةً باستخدام طلب البيانات التالي لواجهة برمجة التطبيقات:

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 يحتوي على رمز OAuthBearer الميز نفسه.

في ما يلي نموذج طلب وردّ:

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"
    }
  ]
}