Class ScriptApp

移除指定的觸發條件，讓該觸發條件不再執行。

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

參數

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

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

取得物件，用於檢查使用者是否已授予所有指令碼需求的授權。在任何指令碼要求未經授權的情況下，這個物件也會提供授權網址，方便使用者授予這些權限。

部分指令碼執行作業可在未取得使用者同意的情況下開始，但指令碼必須使用所有必要範圍。這個物件中的資訊可讓您控制對需要特定範圍的程式碼區段存取權，並要求授權這些範圍的後續執行作業。

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

參數

回攻員

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

取得物件，用於檢查使用者是否已授予所要求的範圍授權。如果所要求的任何範圍都未經授權，這個物件也會提供授權網址，方便使用者授予這些權限。

部分指令碼執行作業可在未取得使用者同意的情況下開始，但前提是使用者同意指令碼使用所有必要的範圍。這個物件中的資訊可讓您控制對需要特定範圍的程式碼區段存取權，並要求授權這些範圍的後續執行作業。如果範圍無效，或指令碼「未要求」，就會導致錯誤。

const authInfo = ScriptApp.getAuthorizationInfo(ScriptApp.AuthMode.FULL, [
  'https://www.googleapis.com/auth/documents',
  'https://www.googleapis.com/auth/presentations',
]);
const status = authInfo.getAuthorizationStatus();
const url = authInfo.getAuthorizationUrl();

參數

回攻員

AuthorizationInfo：提供使用者授權狀態資訊的物件，以及授權網址 (如果缺少部分同意聲明)。

如果已授予 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}`);

回攻員

String：如果有可用的身分認同詞元，則傳回 String；否則傳回 null。

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

回攻員

InstallationSource：安裝來源。

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

這個方法傳回的權杖只包含指令碼目前需要的權限範圍。先前已授權但不再由指令碼使用的權限範圍不會包含在傳回的權杖中。如果需要額外的 OAuth 範圍 (超出指令碼本身所需的範圍)，可以指定指令碼的資訊清單檔案。

回攻員

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

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

Logger.log(
    `Current project has ${ScriptApp.getProjectTriggers().length} triggers.`,
);

回攻員

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

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

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

取得指令碼專案的專屬 ID。這是取得指令碼專案的專屬 ID 的首選方法，而非 getProjectKey()。這個 ID 可用於先前提供專案金鑰的所有位置。

回攻員

String：指令碼專案 ID。

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

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

回攻員

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

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

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());

參數

回攻員

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

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

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

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

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());

參數

回攻員

Trigger[]：在指定表單中，由此使用者擁有的觸發事件陣列。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

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

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

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());

參數

回攻員

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

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

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

讓有效使用者執行目前指令碼的授權失效。用於讓目前指令碼的所有權限失效。這對於標示為一次性授權的函式特別實用。由於一次性授權函式只能在指令碼取得授權後的第一次執行時呼叫，因此如果您想在之後執行動作，必須撤銷指令碼的所有授權，讓使用者再次看到授權對話方塊。

ScriptApp.invalidateAuth();

擲回

Error - 當驗證失敗時

建立狀態權杖的建構工具，可用於回呼 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：用於繼續建立狀態符記程序的物件。

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

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

參數

回攻員

TriggerBuilder：用於繼續觸發建立程序的物件。

授權

使用這個方法的腳本需要具備下列一或多個範圍的授權：

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

驗證使用者是否已針對指令碼要求的所有範圍授予同意聲明。如果執行流程依賴指令碼要求的所有範圍，請使用這個方法。如果缺少任何同意聲明，這個方法會結束目前的執行作業，並顯示授權提示，要求缺少的同意聲明。

這個方法只適用於使用者從支援精細同意聲明的介面執行指令碼時，例如從 Apps Script IDE 內執行。當指令碼在未支援的途徑 (例如 Google Workspace 外掛程式) 中執行時，如果缺少同意聲明，指令碼會在執行作業開始時顯示授權提示，要求所有範圍。

ScriptApp.requireAllScopes(ScriptApp.AuthMode.FULL);

參數

驗證使用者是否已同意授予要求的權限範圍。如果執行流程仰賴一或多項服務，請使用此方法。如果缺少任何指定的同意聲明，這個方法會結束目前的執行作業，並顯示授權提示，要求缺少的同意聲明。如果範圍無效或指令碼未要求，就會導致錯誤。

只有在使用者從支援精細同意聲明的介面執行指令碼時，這個方法才會生效，例如從 Apps Script IDE 內執行。當指令碼在未支援的途徑 (例如 Google Workspace 外掛程式) 中缺少同意聲明時，指令碼會在執行作業開始時顯示授權提示，要求所有範圍。

ScriptApp.requireScopes(ScriptApp.AuthMode.FULL, [
  'https://www.googleapis.com/auth/documents',
  'https://www.googleapis.com/auth/presentations',
]);

參數