ייבוא וייצוא פרויקטים

מאחר שפרויקטים של Apps Script נמצאים ב-Google Drive, מפתחים יכולים לייבא ולייצא את קוד המקור של Apps Script באמצעות Google Drive API (לא להתבלבל עם Drive Service ב-Apps Script).

לדוגמה, מפתח יכול לכתוב קוד חדש של Apps Script במחשב המקומי שלו באמצעות עורך הקוד המועדף עליו, ולהשתמש במערכת לבקרת גרסאות כמו Git כדי לשתף פעולה עם מפתחים אחרים. כשהיא תסיים לעבוד על הגרסה, היא תוכל להעלות (לייבא) את הקבצים ל-Google Drive באמצעות ה-API ל-REST, שם אפשר להשתמש בהם כמו בכל פרויקט אחר של 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 classes כשרוצים לספק אנקפסולציה בטוחה.

Drive API

Google Drive API מאפשר למפתחים לגשת לקבצים ב-Google Drive באופן פרוגרמטי. ה-API הזה משתמש ב-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, משתמשים במשאב Files כדי לשלוח שאילתה לגבי קבצים עם סוג ה-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
  }
 ]
}

אם ידוע לכם מהו מזהה הקובץ של פרויקט Apps Script, תוכלו לאחזר אותו ישירות באמצעות קריאת ה-API הבאה:

GET https://www.googleapis.com/drive/v2/files/1234567890abcefghijklmnopqrstuvwxyz
Authorization:  Bearer ya29.fakebearerstring

ייצוא פרויקטים מ-Drive

אחרי שתקבלו משאב File מה-API, המאפיין exportLinks יכיל כתובת URL שאפשר לאחזר כדי לקבל את תוכן הפרויקט כנתוני JSON. דוגמה לכתובת ה-URL הזו:

https://script.google.com/feeds/download/export?id=1234567890abcefghijklmnopqrstuvwxyz&format=json

שולחים בקשה לכתובת ה-URL הזו כדי לאחזר את תוכן הפרויקט עצמו. חשוב לכלול כותרת Authorization עם אותו Bearer אסימון OAuth

הנה דוגמה לבקשה ולתגובה:

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, שבו כל אחד מכיל את 4 המאפיינים הבאים:

id מזהה פנימי של קובץ בפרויקט, שנחוץ כדי להפנות לקובץ הזה במהלך עדכונים.
name שם הקובץ ללא סיומות, כפי שהוא מוצג בכלי העריכה של הסקריפט.
type שני סוגי הקבצים הם server_js ו-html.
source קוד המקור המקודד שמכיל את הקובץ.

ייבוא פרויקטים ל-Drive

כדי לעדכן פרויקט קיים, מבצעים קריאה HTTP PUT לממשק ה-API של הקובץ 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 ל-API של הקובץ insert. בדומה לקריאה ל-update, אפשר להשתמש בספריית לקוח כדי לכלול מטא-נתונים כמו שם הפרויקט ותיאור שלו.

זו דוגמה לעסקה של העלאת מדיה. הפעולה הזו תיצור פרויקט בשם 'Untitled' ב-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"
    }
  ]
}