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.
const triggers = ScriptApp.getProjectTriggers();
for (let 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。

const idToken = ScriptApp.getIdentityToken();
const body = idToken.split('.')[1];
const decoded = Utilities
                    .newBlob(
                        Utilities.base64Decode(body),
                        )
                    .getDataAsString();
const payload = JSON.parse(decoded);

Logger.log(`Profile ID: ${payload.sub}`);
如需完整的傳回欄位 (宣告) 清單，請參閱 OpenID Connect 說明文件。

回攻員

String：如果有可用的身分認同詞元，則傳回 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。這是取得指令碼專案的專屬 ID 的首選方法，而非 getProjectKey()。這個 ID 可用於先前提供專案金鑰的所有位置。

回攻員

String：指令碼專案 ID。

getService()

取得用於控制以網路應用程式形式發布指令碼的物件。

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

回攻員

Service：用於觀察及控制以網路應用程式形式發布指令碼的物件。

getUserTriggers(document)

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

const doc = DocumentApp.getActiveDocument();
const 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)

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

const form = FormApp.getActiveForm();
const 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)

只針對此指令碼或外掛程式，取得指定試算表中此使用者擁有的所有可安裝觸發事件。您無法使用這個方法查看附加至其他指令碼的觸發事件。

const ss = SpreadsheetApp.getActiveSpreadsheet();
const 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.
  const scriptUrl =
      'https://script.google.com/macros/d/1234567890abcdefghijklmonpqrstuvwxyz';
  const urlSuffix = '/usercallback?state=';
  const 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

已淘汰的方法