匯入及匯出專案

由於 Apps Script 專案位於 Google 雲端硬碟,開發人員可以使用 Google 雲端硬碟 API 匯入及匯出 Apps Script 原始碼 (請勿與 Apps Script 中的 Drive 服務混淆)。

舉例來說,開發人員可以在本機使用自己偏好的程式碼編輯器編寫新的 Apps Script 程式碼,並使用 Git 等版本管控系統與其他開發人員協作。版本完成後,她可以使用 REST API 將檔案上傳 (匯入) 至 Google 雲端硬碟,並像其他 Apps Script 專案一樣使用這些檔案。

您可以在本機版本上進行程式碼變更,並使用 Google 雲端硬碟 API 將其同步處理至 Apps Script 專案。您可以從 Google 雲端硬碟下載 (匯出) 現有專案至本機電腦。

功能和限制

如果您想使用 Google Drive API 匯入或匯出專案,請注意下列事項:

  1. 伺服器端指令碼檔案的結尾應為「.gs」。您可能會想使用本機的 .js 檔案進行開發,但請務必在匯入 Google 雲端硬碟前,先將檔案重新命名為 .gs 副檔名。
  2. 用戶端指令碼檔案的結尾必須是「.html」。這包括用戶端的 .html、.js 或 .css 檔案。再次提醒,您可以在本機使用其他擴充功能進行開發,但請務必先將檔案轉換為 .html 格式,再匯入 Google 雲端硬碟。
  3. 將專案檔案匯入 Google 雲端硬碟時,系統會覆寫這些檔案中的所有現有資料。您無法附加或插入部分文字,必須更新整個檔案。
  4. 伺服器端指令碼檔案必須包含有效的 JavaScript。如果伺服器 .js 檔案中有錯誤,Google Drive API 更新呼叫將會失敗,並顯示 5xx 錯誤。如要避免這種情況,請在匯入前先對程式碼進行 lint 檢查。
  5. 空白檔案無法匯入。如果您嘗試上傳空白檔案,Google 雲端硬碟 API 更新呼叫將會失敗,並顯示 5xx 錯誤。
  6. 只能匯入或匯出獨立的腳本。無法透過 Google Drive API 存取容器限定指令碼。
  7. 您只能匯入或匯出原始碼。您也無法透過 Google 雲端硬碟 API 提供專案屬性或記錄等資源。您無法透過 Google Drive API 執行指令碼版本管理、發布或執行指令碼等動作。
  8. 您不必使用單一伺服器 Code.gs 檔案。您可以將伺服器程式碼分散到多個檔案,方便開發。所有伺服器檔案都會載入至相同的全域命名空間,因此如要提供安全的封裝,請使用 JavaScript 類別。

Drive API

Google 雲端硬碟 API 可讓開發人員以程式輔助方式存取 Google 雲端硬碟中的檔案。這個 API 會使用 GET 下載檔案,並使用 PUT/POST 上傳檔案。如需詳細說明文件和快速入門指南,請參閱 Google Drive API 總覽頁面

本指南將著重於使用以下呼叫,透過 Files 資源列出及移動檔案:

授權

所有向 Google 雲端硬碟 API 發出的要求都必須獲得已驗證使用者透過 OAuth 2.0 通訊協定授權。詳情請參閱 Google Drive API 授權說明文件

除了應用程式可能需要的其他範圍 (例如 https://www.googleapis.com/auth/drive) 外,所有嘗試匯入或匯出 Google Apps Script 專案的應用程式都必須要求特殊範圍:

https://www.googleapis.com/auth/drive.scripts

列出現有專案

如要列出 Google 雲端硬碟中的所有 Apps Script 專案,請使用檔案資源查詢 MIME 類型為 application/vnd.google-apps.script 的檔案。如要篩選回應,只包含您擁有的檔案,請加入搜尋參數 'me' in owners

以下是要求和回應範例,顯示透過 JSON 回應傳回的 Apps Script 專案陣列。

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 專案的檔案 ID,可以使用下列 API 呼叫直接擷取:

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

從雲端硬碟匯出專案

從 API 取得 File 資源後,exportLinks 屬性就會包含可擷取的網址,以便將專案內容擷取為 JSON 資料。以下是這個網址的範例:

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

請對這個網址提出要求,擷取專案本身的內容。請務必加入含有相同 OAuth Bearer 權杖的 Authorization 標頭

以下是要求和回應的範例:

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 專案內檔案的內部 ID,用於在更新期間參照此檔案。
name 在指令碼編輯器中顯示的檔案名稱 (不含副檔名)。
type 這兩種檔案類型分別為 server_js 和 html。
source 檔案中包含的經過編碼的原始碼。

將專案匯入雲端硬碟

如要更新現有專案,請使用適當的 fileId 對檔案 update API 發出 HTTP PUT 呼叫。以下範例顯示媒體上傳部分的交易範例。使用其中一個用戶端程式庫,應用程式就能輕鬆在同一個上傳呼叫中加入中繼資料和媒體。請注意,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"
    }
  ]
}

在專案中建立新檔案

如要在專案中建立新檔案,請針對沒有 id 屬性的檔案傳送 PUT 要求。如果您納入含有不明 ID 的檔案,系統會擲回錯誤訊息。

刪除專案中的檔案

如要從專案中刪除檔案,請傳送不包含該檔案 (但包含專案中所有其他檔案) 的 PUT 要求。在匯入程序中,所有未傳回的檔案都會從伺服器中刪除。

重新命名專案中的檔案

如要重新命名專案中的檔案,請傳送 PUT 要求,其中包含現有的 id 和新的 name。請注意,伺服器會忽略任何嘗試變更為 type 的動作。

建立新專案

如要建立新專案,請將 POST 要求傳送至檔案 insert API。與 update 呼叫類似,您可以使用用戶端程式庫加入中繼資料,例如專案名稱和說明。

以下是媒體上傳交易的範例。系統會在雲端硬碟中建立名為「Untitled」的專案。網址中必須有 convert 參數。與 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"
    }
  ]
}