由於 Apps Script 專案位於 Google 雲端硬碟,開發人員可以使用 Google Drive API 匯入及匯出 Apps Script 原始碼 (別與 Apps Script 中的雲端硬碟服務混淆)。
舉例來說,開發人員可以使用自己慣用的程式碼編輯器,在本機電腦上編寫新的 Apps Script 程式碼,並使用 Git 等版本管控系統與其他開發人員協同合作。版本完成之後,她可以使用 REST API 將檔案上傳 (匯入) 至 Google 雲端硬碟,就像其他 Apps Script 專案一樣。
您可以在本機版本中變更程式碼,並使用 Google Drive API 同步處理至 Apps Script 專案。現有專案可以從 Google 雲端硬碟下載 (匯出) 至本機電腦。
功能和限制
如要使用 Google Drive API 匯入或匯出專案,請注意下列事項:
- 伺服器端指令碼檔案的結尾應為「.gs」。您可能希望在本機使用 .js 檔案進行開發,但在匯入 Google 雲端硬碟之前,請務必為 include 加上 .gs 副檔名。
- 用戶端指令碼檔案的結尾必須是「.html」。其中包括用戶端 .html、.js 或 .css 檔案。同樣地,您可以使用其他擴充功能在本機進行開發,但務必先使用 .html 擴充功能,再匯入 Google 雲端硬碟。
- 將專案檔案匯入 Google 雲端硬碟時,系統會覆寫這些檔案中的所有現有資料。您無法附加或插入部分文字,必須更新整個檔案。
- 伺服器端指令碼檔案必須包含有效的 JavaScript。如果伺服器 .js 檔案發生錯誤,Google Drive API 更新呼叫就會失敗,並顯示 5xx 錯誤。如要避免這種情況發生,您可以在匯入前檢查程式碼。
- 無法匯入空白檔案。如果您嘗試上傳空白檔案,Google Drive API 更新呼叫就會失敗,並顯示 5xx 錯誤。
- 只能匯入或匯出獨立指令碼。容器繫結指令碼無法透過 Google Drive API 存取。
- 只能匯入或匯出原始碼。專案屬性或記錄檔等資源也不會透過 Google Drive API 公開。您無法透過 Google Drive API 執行指令碼版本管理、發布或執行指令碼等動作。
- 不限於單一伺服器
Code.gs
檔案。您可以將伺服器程式碼分散到多個檔案上,方便開發。所有伺服器檔案都會載入相同的全域命名空間,因此請在您想提供安全封裝時使用 JavaScript 類別。
Drive API
Google Drive API 可讓開發人員以程式輔助方式存取 Google 雲端硬碟中的檔案。這個 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 專案,請使用檔案資源查詢 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 服務指南中簡易網頁應用程式的程式碼。請注意,系統會傳回 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
要求。凡是在匯入過程中沒有回傳的檔案,都會從伺服器中刪除。
重新命名專案中的檔案
如要重新命名專案中的檔案,請傳送含有現有 id
的 PUT
要求,以及新的 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" } ] }