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

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

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

يمكن إجراء تغييرات على الرمز البرمجي في النُسخ المحلية ومزامنتها مع مشروع "برمجة التطبيقات" باستخدام 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 أيضًا موارد مثل خصائص المشاريع أو السجلات. لا يمكن تنفيذ إجراءات مثل تحديد إصدارات النصوص البرمجية أو نشرها أو تنفيذها باستخدام 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

لاختبار نماذج الطلبات التالية، استخدِم رمزًا مميزًا لحامل OAuth 2.0 تم الحصول عليه من مساحة بروتوكول OAuth 2.0.

عرض قائمة بالمشاريع الحالية

لعرض جميع مشاريع برمجة تطبيقات في Drive، استخدِم مورد الملفات للاستعلام عن الملفات التي تحمل نوع MIME application/vnd.google-apps.script. لتصفية الردّ بحيث يتضمّن الملفات التي تملكها فقط، أدرِج مَعلمة البحث 'me' in owners.

في ما يلي نموذج طلب واستجابة يعرضان مصفوفة من مشاريع برمجة تطبيقات تم عرضها من خلال استجابة 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

لا يتطابق رقم تعريف ملف المشروع مع مفتاح المشروع. معرّف الملف هو سلسلة أبجدية رقمية في عنوان URL الخاص بالمشروع.

تصدير المشاريع من 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"
    }
  ]
}