Class ScriptApp

ScriptApp

存取及操控指令碼發布和觸發條件。這個類別可讓使用者建立指令碼觸發條件，並控管以服務形式發布指令碼。

屬性

屬性類型說明
AuthModeAuthMode列舉項目，指出 Apps Script 能透過已觸發的函式執行的授權服務類別。
AuthorizationStatusAuthorizationStatus列舉表示指令碼授權狀態的列舉。
EventTypeEventType列舉，表示觸發事件的類型。
InstallationSourceInstallationSource列舉表示外掛程式是以外掛程式的形式安裝給使用者。
TriggerSourceTriggerSource列舉，用來表示導致觸發條件觸發的事件來源。
WeekDayWeekday列舉代表星期幾。

方法

方法傳回類型簡短說明
deleteTrigger(trigger)void移除指定的觸發條件，使其不再執行。
getAuthorizationInfo(authMode)AuthorizationInfo取得用於判斷使用者是否需要授權此指令碼使用一或多項服務的物件，並提供授權對話方塊的網址。
getIdentityToken()String如果已授予 openid 範圍，請為有效使用者取得 OpenID Connect 識別權杖。
getInstallationSource()InstallationSource傳回列舉值，指出指令碼如何安裝為目前使用者的外掛程式 (例如，使用者是否透過 Chrome 線上應用程式商店自行安裝，或網域管理員是否為所有使用者安裝)。
getOAuthToken()String取得有效使用者的 OAuth 2.0 存取權杖。
getProjectTriggers()Trigger[]取得與目前專案和目前使用者相關聯的所有可安裝觸發條件。
getScriptId()String取得指令碼專案的專屬 ID。
getService()Service取得用於控制將指令碼發布為網頁應用程式的物件。
getUserTriggers(document)Trigger[]針對此指令碼或外掛程式，取得這位使用者在指定文件中擁有的所有可安裝觸發條件。
getUserTriggers(form)Trigger[]根據這個指令碼或外掛程式，以指定表單取得這位使用者擁有的所有可安裝觸發條件。
getUserTriggers(spreadsheet)Trigger[]取得這位使用者在指定試算表 (僅限此指令碼或外掛程式) 內擁有的所有可安裝觸發條件。
invalidateAuth()void讓有效使用者必須執行目前的指令碼，才能取得授權。
newStateToken()StateTokenBuilder建立可用於回呼 API 的狀態權杖 (例如 OAuth 流程) 的建構工具。
newTrigger(functionName)TriggerBuilder開始建立可安裝觸發條件，觸發時就會呼叫指定函式。

內容詳盡的說明文件

deleteTrigger(trigger)

移除指定的觸發條件，使其不再執行。 

// Deletes all triggers in the current project.
var triggers = ScriptApp.getProjectTriggers();
for (var i = 0; i < triggers.length; i++) {
  ScriptApp.deleteTrigger(triggers[i]);
}

參數

名稱類型說明
triggerTrigger要刪除的觸發條件。

授權

使用這個方法的指令碼必須取得以下一或多個範圍的授權：

  • https://www.googleapis.com/auth/script.scriptapp

getAuthorizationInfo(authMode)

取得用於判斷使用者是否需要授權此指令碼使用一或多項服務的物件，並提供授權對話方塊的網址。如果指令碼是以使用可安裝觸發條件的外掛程式形式發布，這項資訊可用於控管使用者缺少必要授權的程式碼區塊的存取權。此外，外掛程式也可以要求使用者開啟授權對話方塊的網址，以便解決問題。 

var authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL);
status = authInfo.getAuthorizationStatus();
url = authInfo.getAuthorizationUrl();

參數

名稱類型說明
authModeAuthMode要求取得授權資訊的授權模式。在幾乎所有情況下，authMode 的值應為 ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL)，因為其他授權模式都不需要使用者授予權限

回攻員

AuthorizationInfo：可提供使用者授權狀態相關資訊的物件

getIdentityToken()

如果已授予 openid 範圍，請為有效使用者取得 OpenID Connect 識別權杖。系統預設不會納入這個範圍，因此您必須在資訊清單檔案中將其新增為明確範圍，才能提出要求。納入 https://www.googleapis.com/auth/userinfo.email 或 https://www.googleapis.com/auth/userinfo.profile 範圍以在權杖中傳回其他使用者資訊。

傳回的 ID 權杖是經過編碼的 JSON Web Token (JWT)，必須解碼，才能擷取其中的資訊。以下範例說明如何解碼權杖，並擷取有效使用者的 Google 個人資料 ID。

var idToken = ScriptApp.getIdentityToken();
var body = idToken.split('.')[1];
var decoded = Utilities.newBlob(Utilities.base64Decode(body)).getDataAsString();
var payload = JSON.parse(decoded);
var profileId = payload.sub;
Logger.log('Profile ID: ' + profileId);
請參閱 OpenID Connect 說明文件，瞭解傳回的欄位 (憑證附加資訊) 的完整清單。

回攻員

String：身分權杖 (如有)，否則為 null。

getInstallationSource()

傳回列舉值，指出指令碼如何安裝為目前使用者的外掛程式 (例如，使用者是否透過 Chrome 線上應用程式商店自行安裝，或網域管理員是否為所有使用者安裝)。

回攻員

InstallationSource：安裝來源。

getOAuthToken()

取得有效使用者的 OAuth 2.0 存取權杖。如果指令碼的 OAuth 範圍足以授權其他一般需要專屬 OAuth 流程的 Google API (例如 Google Picker)，指令碼可以改為傳遞這個權杖，略過第二個授權提示。權杖會在一段時間後過期 (最少數分鐘)；指令碼應處理授權失敗，並在需要時呼叫此方法來取得新的權杖。

這個方法傳回的權杖只包含指令碼目前所需的範圍。先前已授權但指令碼已不再使用的範圍，不會顯示在傳回的權杖中。如果除了指令碼本身需要的其他 OAuth 範圍之外，您可以在指令碼的資訊清單檔案中指定這些範圍。

回攻員

String：以字串表示的 OAuth 2.0 權杖。

getProjectTriggers()

取得與目前專案和目前使用者相關聯的所有可安裝觸發條件。

Logger.log('Current project has ' + ScriptApp.getProjectTriggers().length + ' triggers.');

回攻員

Trigger[]：與此專案相關聯的目前使用者觸發條件的陣列。

授權

使用這個方法的指令碼必須取得以下一或多個範圍的授權：

  • https://www.googleapis.com/auth/script.scriptapp

getScriptId()

取得指令碼專案的專屬 ID。相較於 getProjectKey()，建議您採用這種方式取得指令碼專案的專屬 ID。這組 ID 可用於先前提供專案金鑰的所有位置，

回攻員

String：指令碼專案的 ID。

getService()

取得用於控制將指令碼發布為網頁應用程式的物件。 

// Get the URL of the published web app.
var url = ScriptApp.getService().getUrl();

回攻員

Service — 用於觀察及控制將指令碼發布為網頁應用程式的物件。

getUserTriggers(document)

針對此指令碼或外掛程式，取得這位使用者在指定文件中擁有的所有可安裝觸發條件。這個方法無法用來查看附加至其他指令碼的觸發條件。 

var doc = DocumentApp.getActiveDocument();
var triggers = ScriptApp.getUserTriggers(doc);
// Log the handler function for the first trigger in the array.
Logger.log(triggers[0].getHandlerFunction());

參數

名稱類型說明
documentDocument可能含有可安裝觸發條件的 Google 文件檔案。

回攻員

Trigger[]：使用者在指定文件中擁有的觸發條件陣列。

授權

使用這個方法的指令碼必須取得以下一或多個範圍的授權：

  • https://www.googleapis.com/auth/script.scriptapp

getUserTriggers(form)

根據這個指令碼或外掛程式，以指定表單取得這位使用者擁有的所有可安裝觸發條件。這個方法無法用來查看附加至其他指令碼的觸發條件。 

var form = FormApp.getActiveForm();
var triggers = ScriptApp.getUserTriggers(form);
// Log the trigger source for the first trigger in the array.
Logger.log(triggers[0].getTriggerSource());

參數

名稱類型說明
formForm可能含有可安裝觸發條件的 Google 表單檔案。

回攻員

Trigger[]：這位使用者擁有的觸發條件陣列，以特定表單形式呈現。

授權

使用這個方法的指令碼必須取得以下一或多個範圍的授權：

  • https://www.googleapis.com/auth/script.scriptapp

getUserTriggers(spreadsheet)

取得這位使用者在指定試算表 (僅限此指令碼或外掛程式) 內擁有的所有可安裝觸發條件。這個方法無法用來查看附加至其他指令碼的觸發條件。 

var ss = SpreadsheetApp.getActiveSpreadsheet();
var triggers = ScriptApp.getUserTriggers(ss);
// Log the event type for the first trigger in the array.
Logger.log(triggers[0].getEventType());

參數

名稱類型說明
spreadsheetSpreadsheet可能含有可安裝觸發條件的 Google 試算表檔案。

回攻員

Trigger[]：使用者在指定試算表中擁有的觸發條件陣列。

授權

使用這個方法的指令碼必須取得以下一或多個範圍的授權：

  • https://www.googleapis.com/auth/script.scriptapp

invalidateAuth()

讓有效使用者必須執行目前的指令碼，才能取得授權。用於撤銷目前指令碼的所有權限。這對於標示為一次性授權的函式特別實用。由於一次性授權函式只能在指令碼取得授權後首次執行，因此如果您想要之後執行動作，就必須撤銷指令碼擁有的任何授權，以便使用者再次查看授權對話方塊。

ScriptApp.invalidateAuth();

擲回

Error — 無效時

newStateToken()

建立可用於回呼 API 中的狀態權杖 (例如 OAuth 流程) 的建構工具。

// Generate a callback URL, given the name of a callback function. The script does not need to
// be published as a web app; the /usercallback URL suffix replaces /edit in any script's URL.
function getCallbackURL(callbackFunction) {
  // IMPORTANT: Replace string below with the URL from your script, minus the /edit at the end.
  var scriptUrl = 'https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz';
  var urlSuffix = '/usercallback?state=';
  var stateToken = ScriptApp.newStateToken()
      .withMethod(callbackFunction)
      .withTimeout(120)
      .createToken();
  return scriptUrl + urlSuffix + stateToken;
}

在大部分的 OAuth2 流程中，state 權杖會直接傳遞至授權端點 (而非做為回呼網址的一部分)，然後授權端點將其做為回呼網址的一部分傳遞。

例如：

  • 這個指令碼會將使用者重新導向至 OAuth2 授權網址：https://accounts.google.com/o/oauth2/auth?state=token_generated_with_this_method&callback_uri=https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback&other_oauth2_parameters
  • 使用者點選 [授權]，OAuth2 授權頁面會將使用者重新導向回 https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz/usercallback?state=token_generated_with_this_method&other_params_that_include_tokens_or_grants
  • 上述重新導向 (返回 http://script.google.com/...) 會使瀏覽器要求 /usercallback，進而叫用 StateTokenBuilder.withMethod(method) 指定的方法。

回攻員

StateTokenBuilder：用於繼續進行狀態權杖建構程序的物件。

newTrigger(functionName)

開始建立可安裝觸發條件，觸發時就會呼叫指定函式。

// Creates an edit trigger for a spreadsheet identified by ID.
ScriptApp.newTrigger('myFunction')
    .forSpreadsheet('1234567890abcdefghijklmnopqrstuvwxyz_a1b2c3')
    .onEdit()
    .create();

參數

名稱類型說明
functionNameString觸發條件觸發時要呼叫的函式。您可以使用內含程式庫中的函式，例如 Library.libFunction1。

回攻員

TriggerBuilder：用於繼續進行觸發條件建構程序的物件。

授權

使用這個方法的指令碼必須取得以下一或多個範圍的授權：

  • https://www.googleapis.com/auth/script.scriptapp

已淘汰的方法