由於 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 匯入或匯出專案,請注意下列事項:
- 伺服器端指令碼檔案的結尾應為「.gs」。您可能會想使用本機的 .js 檔案進行開發,但請務必在匯入 Google 雲端硬碟前,先將檔案重新命名為 .gs 副檔名。
- 用戶端指令碼檔案的結尾必須是「.html」。這包括用戶端的 .html、.js 或 .css 檔案。再次提醒,您可以在本機使用其他擴充功能進行開發,但請務必先將檔案轉換為 .html 格式,再匯入 Google 雲端硬碟。
- 將專案檔案匯入 Google 雲端硬碟時,系統會覆寫這些檔案中的所有現有資料。您無法附加或插入部分文字,必須更新整個檔案。
- 伺服器端指令碼檔案必須包含有效的 JavaScript。如果伺服器 .js 檔案中有錯誤,Google Drive API 更新呼叫將會失敗,並顯示 5xx 錯誤。如要避免這種情況,請在匯入前先對程式碼進行 lint 檢查。
- 空白檔案無法匯入。如果您嘗試上傳空白檔案,Google 雲端硬碟 API 更新呼叫將會失敗,並顯示 5xx 錯誤。
- 只能匯入或匯出獨立的腳本。無法透過 Google Drive API 存取容器限定指令碼。
- 您只能匯入或匯出原始碼。您也無法透過 Google 雲端硬碟 API 提供專案屬性或記錄等資源。您無法透過 Google Drive API 執行指令碼版本管理、發布或執行指令碼等動作。
- 您不必使用單一伺服器
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" } ] }