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：身分識別權杖 (如有)，否則為 null。

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

回攻員

InstallationSource - 安裝來源。

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

這個方法傳回的權杖只包含指令碼目前需要的範圍。 如果指令碼不再使用先前授權的範圍，傳回的權杖就不會包含這些範圍。如果需要超出指令碼本身要求的其他 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();

建立觸發條件前，請確認相關聯的函式具備所有必要的 OAuth 權限。

參數

回攻員

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',
]);

參數