Class ScriptApp

ScriptApp

存取及操控指令碼發布和觸發條件。這個類別可讓使用者建立指令碼 會觸發及控管將指令碼做為服務發布

屬性

屬性類型說明
AuthModeAuthMode列舉項目，用於識別 Apps Script 可存取哪些授權服務類別 透過觸發的函式執行
AuthorizationStatusAuthorizationStatus列舉表示指令碼授權狀態的列舉。
EventTypeEventType列舉表示觸發事件類型的列舉。
InstallationSourceInstallationSource列舉說明以外掛程式形式安裝指令碼的方式。
TriggerSourceTriggerSource列舉表示觸發觸發條件的事件來源。
WeekDayWeekday代表星期幾的列舉。

方法

方法傳回類型簡短說明
deleteTrigger(trigger)void移除指定的觸發條件，使其不再執行。
getAuthorizationInfo(authMode)AuthorizationInfo取得一個物件，用來判斷使用者是否需要授權這個指令碼使用或 並提供授權對話方塊的網址。
getIdentityToken()String取得 OpenID Connect 識別憑證 如果已授予 openid 範圍，則有效使用者。
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 Connect 識別憑證 如果已授予 openid 範圍，則有效使用者。不包含這個範圍 您必須在資訊清單中將其新增為明確範圍 檔案。納入 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。建議您透過這個方法取得專屬 ID 而不是 getProjectKey()。這個 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

已淘汰的方法