內建 Google 服務

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

如需控管Google Workspace 產品的服務參考文件,請前往這個網站側欄中「參考資料」標題下方的「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 類別時一樣;您只能藉由呼叫傳回該類別的方法來存取子項類別。如果您不確定如何存取特定類別,請造訪服務參考說明文件的根頁面,找出可傳回所需類別的方法。

處理介面

部分服務包括參考說明文件中標示為「介面」的特殊類別。這類一般類別可做為無法事先決定精確類型的方法傳回類型,例如文件服務方法 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);