內建 Google 服務

Google Apps Script 提供超過 30 種內建服務,能夠與使用者資料、其他 Google 系統和外部系統互動。這些服務以全域物件的形式提供,遵循 JavaScript 標準 Math 物件。舉例來說,就像 Math 提供方法 (例如 random()) 和常數 (例如 PI) 一樣,Apps Script 的試算表服務也提供 openById(id) 等方法、Range 等類別和 DataValidationCriteria 等列舉。

控制 Google Workspace 公用服務 (例如建立使用者介面、剖析 XML 或寫入記錄資料) 均在「指令碼服務」區段中收集。

新版 JavaScript 功能

Apps Script 支援兩個 JavaScript 執行階段:新型 V8 執行階段,以及由 Mozilla 的 Rhino JavaScript 解譯器提供技術的舊版執行階段。

V8 執行階段支援新型的 ECMAScript 語法和功能。Rhino 執行階段是以舊版 JavaScript 1.6 標準為基礎,還有 1.71.8 的一些功能。您可以自由選擇與指令碼搭配使用的執行階段,但強烈建議使用 V8 執行階段。

除了內建與進階 Google 服務外,每個執行階段都支援指令碼可用的 JavaScript 類別和物件。您的指令碼可以使用常見的物件,例如 ArrayDateRegExp,等等,以及 MathObject 全域物件。

使用自動完成功能

指令碼編輯器提供「內容輔助」功能,更常稱為「自動完成」功能,可顯示全域物件,以及指令碼目前結構定義中有效的方法和列舉。當您輸入全域物件、列舉或方法呼叫必須傳回 Apps Script 類別的全域物件、列舉或方法呼叫之後,系統就會自動顯示自動完成建議。例如:

  • 如果您輸入全域物件的全名,或從自動完成功能選取名稱,然後輸入 . (半形句號),系統就會顯示該類別的所有方法和列舉。
  • 如果輸入幾個字元,您就會看到所有以這些字元開頭的有效建議。

瞭解全域物件

每項服務都至少提供一個全域 (頂層) 物件;例如,Gmail 服務只能透過 GmailApp 物件存取。部分服務提供多個全域物件,例如,基礎服務包含四個全域物件:BrowserLoggerMimeTypeSession

呼叫方法

幾乎所有內建或進階服務的全域物件都包含傳回資料或 Apps Script 類別的方法。指令碼會以下列格式進行方法呼叫:

GlobalObjectName.methodName(argument1, argument2, ..., argumentN);

舉例來說,指令碼可透過呼叫 Gmail 服務的 sendEmail(recipient, subject, body) 方法傳送電子郵件,如下所示:

GmailApp.sendEmail('claire@example.com', 'Subject line', 'This is the body.');

如果方法傳回另一個 Apps Script 類別,您就可以將方法呼叫鏈結成一行。(傳回類型會同時顯示在自動完成內及方法的參考說明文件中)。舉例來說,DocumentApp.create() 方法會傳回 Document,因此以下兩個程式碼部分是相同的:

var doc = DocumentApp.create('New document');
var body = doc.getBody();
body.appendParagraph('New paragraph.');

// Same result as above.
DocumentApp.create('New document').getBody().appendParagraph('New paragraph.');

存取子項類別

每個服務都包含一或多個子項類別,這些頂層類別無法以全域物件的形式存取。您不能使用 new 關鍵字建構這些類別,就像使用 Date 等標準 JavaScript 類別一樣;您只能呼叫傳回該類別的方法,才能存取子項類別。如果不確定如何存取特定類別,請造訪該服務的參考說明文件,並尋找會傳回所需類別的方法。

處理介面

少數服務包括特殊參考文件,在參考說明文件中標示為「介面」的特殊類別。這些是一般類別,做為無法事先判斷精確方法的方法傳回類型;舉例來說,Document Service 方法 Body.getChild(childIndex) 會傳回一般的 Element 物件。Element 是代表其他類別的介面,可能是 ParagraphTable。介面物件極少用到,不然就會改為呼叫 Element.asParagraph() 等方法,將物件投放到精確的類別。

使用列舉

大多數服務都包含幾個已命名值的列舉 (列舉類型)。舉例來說,雲端硬碟服務會使用列舉 AccessPermission 來判斷哪些使用者有權存取檔案或資料夾。在所有情況下,您都是從全域物件存取這些列舉。例如,呼叫 Folder.setSharing(accessType, permissionType) 方法看起來會像這樣:

// Creates a folder that anyone on the Internet can read from and write to. (Domain administrators can
// prohibit this setting for Google Workspace users.)
var folder = DriveApp.createFolder('Shared Folder');
folder.setSharing(DriveApp.Access.ANYONE, DriveApp.Permission.EDIT);