本頁面由 Cloud Translation API 翻譯而成。

Class ScriptApp

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

屬性

屬性	類型	說明
`AuthMode`	`AuthMode`	列舉，用於識別 Apps Script 可透過觸發函式執行的授權服務類別。
`AuthorizationStatus`	`AuthorizationStatus`	列舉，表示指令碼的授權狀態。
`EventType`	`EventType`	列舉，表示觸發事件的類型。
`InstallationSource`	`InstallationSource`	列舉表示指令碼以外掛程式形式安裝至使用者的方式。
`TriggerSource`	`TriggerSource`	列舉，表示導致觸發條件觸發的事件來源。
`WeekDay`	`Weekday`	代表星期幾的列舉。

方法

方法	傳回類型	簡短說明
`deleteTrigger(trigger)`	`void`	移除指定觸發條件，使其不再執行。
`getAuthorizationInfo(authMode)`	`AuthorizationInfo`	取得物件，檢查使用者是否已授權所有指令碼需求。
`getAuthorizationInfo(authMode, oAuthScopes)`	`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`	開始建立可安裝的觸發條件，觸發時會呼叫指定函式。
`requireAllScopes(authMode)`	`void`	驗證使用者是否已同意指令碼要求的所有範圍。
`requireScopes(authMode, oAuthScopes)`	`void`	驗證使用者是否已同意授予要求的範圍。

已淘汰的方法

方法	傳回類型	簡短說明
`getProjectKey()`	`String`	取得目前指令碼的專案金鑰。
`getScriptTriggers()`	`Trigger[]`	取得與目前專案和使用者相關聯的所有可安裝的觸發條件。

內容詳盡的說明文件

`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]);
}

參數

名稱	類型	說明
`trigger`	`Trigger`	要刪除的觸發條件。

授權

使用這個方法的指令碼需要一或多個下列範圍的授權：

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

`getAuthorizationInfo(authMode)`

取得物件，檢查使用者是否已授權所有指令碼需求。如果任何指令碼需求未獲授權，這個物件也會提供授權網址，供使用者授予這些權限。

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

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

參數

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

回攻員

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

`getAuthorizationInfo(authMode, oAuthScopes)`

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

部分指令碼執行作業可能會在未取得使用者同意的情況下啟動，但指令碼使用的所有必要範圍都必須取得使用者同意。這個物件中的資訊可讓您控管程式碼區段的存取權，這些區段需要特定範圍，並要求授權這些範圍以供後續執行。如果範圍無效或指令碼不需要，就會導致錯誤。

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

參數

名稱	類型	說明
`authMode`	`AuthMode`	要求授權資訊的授權模式；在幾乎所有情況下，`authMode` 的值都應為 `ScriptApp.AuthMode.FULL`，因為其他授權模式都不需要使用者授予授權。
`oAuthScopes`	`String[]`	要求授權資訊的 OAuth 範圍。

回攻員

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

`getInstallationSource()`

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

回攻員

InstallationSource - 安裝來源。

`getOAuthToken()`

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

這個方法傳回的權杖只包含指令碼目前需要的範圍。如果指令碼不再使用先前授權的範圍，傳回的權杖就不會包含這些範圍。如果需要超出指令碼本身要求的其他 OAuth 範圍，可以在指令碼的資訊清單檔案中指定這些範圍。

您可以使用這個方法呼叫 Apps Script 未直接支援的 Google API。使用 UrlFetchApp.fetch(url, params)，在 HTTP 要求的 `Authorization` 標頭中傳遞傳回的權杖。

const url = 'https://www.googleapis.com/drive/v3/files';
const method = 'GET';
const headers = {
  Authorization: 'Bearer ' + ScriptApp.getOAuthToken(),
};
const response = UrlFetchApp.fetch(url, {
  method,
  headers,
});

回攻員

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

參數

名稱	類型	說明
`document`	`Document`	可能含有可安裝觸發條件的 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());

參數

名稱	類型	說明
`form`	`Form`	可能含有可安裝觸發條件的 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());

參數

名稱	類型	說明
`spreadsheet`	`Spreadsheet`	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();

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

參數

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

回攻員

TriggerBuilder：用於繼續建構觸發條件的物件。

授權

使用這個方法的指令碼需要一或多個下列範圍的授權：

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

`requireAllScopes(authMode)`

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

只有在支援細部同意聲明的介面 (例如 Apps Script IDE) 中執行指令碼時，這個方法才有效。如果指令碼在不支援的介面 (例如 Google Workspace 外掛程式) 中執行，且缺少同意聲明，指令碼會在執行開始時顯示授權提示，要求所有範圍。

ScriptApp.requireAllScopes(ScriptApp.AuthMode.FULL);

參數

名稱	類型	說明
`authMode`	`AuthMode`	評估指令碼範圍時使用的授權模式。在幾乎所有情況下，`authMode` 的值都應為 `ScriptApp.AuthMode.FULL`，因為其他授權模式都不需要使用者授予授權。

`requireScopes(authMode, oAuthScopes)`

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

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

參數

名稱	類型	說明
`authMode`	`AuthMode`	需要評估所要求範圍的授權模式。在幾乎所有情況下，`authMode` 的值都應為 `ScriptApp.AuthMode.FULL`，因為其他授權模式都不需要使用者授予授權。
`oAuthScopes`	`String[]`	完成指定執行流程所需的 OAuth 範圍。

已淘汰的方法

`getProjectKey()`

已淘汰。請改用 getScriptId()。

取得目前指令碼的專案金鑰。專案金鑰是指令碼的專屬 ID，用於編寫與 newStateToken() 搭配使用的回呼網址。

在程式庫中呼叫時，這會傳回正在執行的最外層指令碼的專案金鑰。

回攻員

String - 目前指令碼的專案金鑰。

`getScriptTriggers()`

已淘汰。這項函式已淘汰，不應在新指令碼中使用。

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

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

回攻員

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

授權

使用這個方法的指令碼需要一或多個下列範圍的授權：

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

Class ScriptApp 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

屬性

方法

已淘汰的方法

內容詳盡的說明文件

deleteTrigger(trigger)

參數

授權

getAuthorizationInfo(authMode)

參數

回攻員

getAuthorizationInfo(authMode, oAuthScopes)

參數

回攻員

getIdentityToken()

回攻員

getInstallationSource()

回攻員

getOAuthToken()

回攻員

getProjectTriggers()

回攻員

授權

getScriptId()

回攻員

getService()

回攻員

getUserTriggers(document)

參數

回攻員

授權

getUserTriggers(form)

參數

回攻員

授權

getUserTriggers(spreadsheet)

參數

回攻員

授權

invalidateAuth()

擲回

newStateToken()

回攻員

newTrigger(functionName)

參數

回攻員

授權

requireAllScopes(authMode)

參數

requireScopes(authMode, oAuthScopes)

參數

已淘汰的方法

getProjectKey()

回攻員

getScriptTriggers()

回攻員

授權

Class ScriptApp

`deleteTrigger(trigger)`

`getAuthorizationInfo(authMode)`

`getAuthorizationInfo(authMode, oAuthScopes)`

`getIdentityToken()`

`getInstallationSource()`

`getOAuthToken()`

`getProjectTriggers()`

`getScriptId()`

`getService()`

`getUserTriggers(document)`

`getUserTriggers(form)`

`getUserTriggers(spreadsheet)`

`invalidateAuth()`

`newStateToken()`

`newTrigger(functionName)`

`requireAllScopes(authMode)`

`requireScopes(authMode, oAuthScopes)`

`getProjectKey()`

`getScriptTriggers()`