דף זה תורגם על ידי Cloud Translation API.

Class ScriptApp

גישה לטריגרים ולפרסום של סקריפטים, וניהול שלהם. הכיתה הזו מאפשרת למשתמשים ליצור טריגרים של סקריפטים ולשלוט בפרסום הסקריפט כשירות.

מאפיינים

נכס	סוג	תיאור
`AuthMode`	`AuthMode`	ספירה שמזהה את הקטגוריות של השירותים המורשים ש-Apps Script יכול להריץ באמצעות פונקציה מופעלת.
`AuthorizationStatus`	`AuthorizationStatus`	ספירה שמציינת את סטטוס ההרשאה של סקריפט.
`EventType`	`EventType`	ספירה שמציינת את סוג האירוע שהופעל.
`InstallationSource`	`InstallationSource`	ספירה שמציינת איך הסקריפט הותקן אצל המשתמש בתור תוסף.
`TriggerSource`	`TriggerSource`	ספירה שמציינת את המקור של האירוע שגורם להפעלת הטריגר.
`WeekDay`	`Weekday`	Enumeration שמייצג את ימי השבוע.

Methods

שיטה	סוג הערך המוחזר	תיאור קצר
`deleteTrigger(trigger)`	`void`	הסרת הטריגר כך שהוא לא יפעל יותר.
`getAuthorizationInfo(authMode)`	`AuthorizationInfo`	הפונקציה מקבלת אובייקט שמשמש לקביעת הצורך של המשתמש לאשר את הסקריפט הזה לשימוש בשירות אחד או יותר, ולמסירת כתובת ה-URL של תיבת הדו-שיח של ההרשאה.
`getIdentityToken()`	`String`	הפונקציה מקבלת אסימון זהות של OpenID Connect עבור המשתמש האפקטיבי, אם היקף ההרשאה `openid` הוענק.
`getInstallationSource()`	`InstallationSource`	הפונקציה מחזירה ערך enum שמציין איך הסקריפט הותקן כתוסף למשתמש הנוכחי (לדוגמה, אם המשתמש התקין אותו באופן אישי דרך חנות האינטרנט של Chrome, או אם אדמין דומיין התקין אותו לכל המשתמשים).
`getOAuthToken()`	`String`	הפונקציה מקבלת את אסימון הגישה מסוג OAuth 2.0 של המשתמש בפועל.
`getProjectTriggers()`	`Trigger[]`	הפונקציה מקבלת את כל הגורמים המפעילים שניתן להתקין שמשויכים לפרויקט הנוכחי ולמשתמש הנוכחי.
`getScriptId()`	`String`	הפונקציה מקבלת את המזהה הייחודי של פרויקט הסקריפט.
`getService()`	`Service`	הפונקציה מקבלת אובייקט שמשמש לבקרת פרסום הסקריפט כאפליקציית אינטרנט.
`getUserTriggers(document)`	`Trigger[]`	הפונקציה מקבלת את כל הטריגרים שניתן להתקין שבבעלות המשתמש הזה במסמך הנתון, עבור הסקריפט או התוסף האלה בלבד.
`getUserTriggers(form)`	`Trigger[]`	הפונקציה מקבלת את כל הטריגרים שניתן להתקין שבבעלות המשתמש הזה בטופס הנתון, עבור הסקריפט או התוסף האלה בלבד.
`getUserTriggers(spreadsheet)`	`Trigger[]`	הפונקציה מקבלת את כל הטריגרים שניתן להתקין שבבעלות המשתמש הזה בגיליון האלקטרוני הנתון, עבור הסקריפט או התוסף האלה בלבד.
`invalidateAuth()`	`void`	מבטלת את ההרשאה של המשתמש בפועל להריץ את הסקריפט הנוכחי.
`newStateToken()`	`StateTokenBuilder`	יצירת בונה לאסימון מצב שאפשר להשתמש בו ב-API של קריאה חוזרת (כמו תהליך OAuth).
`newTrigger(functionName)`	`TriggerBuilder`	התחלת התהליך של יצירת טריגר שניתן להתקנה, שמפעיל פונקציה נתונה כשהוא מופעל.

שיטות שהוצאו משימוש

שיטה	סוג הערך המוחזר	תיאור קצר
`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)`

הפונקציה מקבלת אובייקט שמשמש לקביעת הצורך של המשתמש לאשר את הסקריפט הזה לשימוש בשירות אחד או יותר, ולמסירת כתובת ה-URL של תיבת הדו-שיח של ההרשאה. אם הסקריפט יפורסם בתור תוסף שמשתמש בטריגרים שניתן להתקנה, אפשר להשתמש במידע הזה כדי לשלוט בגישה לקטעי קוד שהמשתמש לא קיבל את ההרשאה הנדרשת לגביהם. לחלופין, התוסף יכול לבקש מהמשתמש לפתוח את כתובת ה-URL של תיבת הדו-שיח של ההרשאה כדי לפתור את הבעיה.

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

פרמטרים

שם	סוג	תיאור
`authMode`	`AuthMode`	מצב ההרשאה שאליו מתייחסים פרטי ההרשאה המבוקשים. ברוב המקרים, הערך של `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.

אסימון המזהה המוחזר הוא אסימון אינטרנט מסוג JSON‏ (JWT) מקודד, וצריך לבצע פענוח כדי לחלץ ממנו מידע. בדוגמאות הבאות מוסבר איך לפענח את האסימון ולחלץ את מזהה פרופיל Google של המשתמש בפועל.

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

הפונקציה מחזירה ערך enum שמציין איך הסקריפט הותקן כתוסף למשתמש הנוכחי (לדוגמה, אם המשתמש התקין אותו באופן אישי דרך חנות האינטרנט של Chrome, או אם אדמין דומיין התקין אותו לכל המשתמשים).

חזרה

InstallationSource – מקור ההתקנה.

`getOAuthToken()`

הפונקציה מקבלת את אסימון הגישה מסוג OAuth 2.0 של המשתמש בפועל. אם היקפי ההרשאות של OAuth בסקריפט מספיקים כדי להעניק הרשאה ל-Google API אחר שבדרך כלל נדרש תהליך OAuth משלו (כמו 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()`

הפונקציה מקבלת את המזהה הייחודי של פרויקט הסקריפט. זוהי השיטה המועדפת לקבלת המזהה הייחודי של פרויקט הסקריפט, בניגוד ל-getProjectKey(). אפשר להשתמש במזהה הזה בכל המקומות שבהם מפתח הפרויקט סופק בעבר.

חזרה

String – המזהה של פרויקט הסקריפט.

`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 Docs שעשוי להכיל טריגרים שניתן להתקין.

חזרה

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 Forms שעשוי להכיל טריגרים שניתן להתקין.

חזרה

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 Sheets שעשוי להכיל טריגרים שניתן להתקין.

חזרה

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 מועבר ישירות לנקודת הקצה להרשאה (לא כחלק מכתובת ה-URL להודעת החזרה), ולאחר מכן נקודת הקצה להרשאה מעבירה אותו כחלק מכתובת ה-URL להודעת החזרה.

לדוגמה:

הסקריפט מפנה את המשתמש לכתובת ה-URL לאישור ב-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();

פרמטרים

שם	סוג	תיאור
`functionName`	`String`	הפונקציה שתופעל כשהטריגר יופעל. אפשר להשתמש בפונקציות מספריות כלולות, כמו `Library.libFunction1`.

חזרה

TriggerBuilder – אובייקט שמשמש להמשך תהליך היצירה של הטריגר.

אישור

סקריפטים שמשתמשים בשיטה הזו דורשים הרשאה עם אחד או יותר מהיקפי הגישה הבאים:

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

שיטות שהוצאו משימוש

`getProjectKey()`

התכונה הוצאה משימוש. במקום זאת, יש להשתמש ב-getScriptId().

הפונקציה מקבלת את מפתח הפרויקט של הסקריפט הנוכחי. מפתח הפרויקט הוא מזהה ייחודי לסקריפטים, והוא משמש ליצירת כתובת ה-URL להודעת החזרה (callback) שנעשה בה שימוש בשילוב עם newStateToken().

כשמפעילים את הפונקציה בספרייה, היא מחזירה את מפתח הפרויקט של הסקריפט החיצוני ביותר שמתבצע.

חזרה

String – מפתח הפרויקט של הסקריפט הנוכחי.

`getScriptTriggers()`

הוצא משימוש. הפונקציה הזו הוצאה משימוש ואין להשתמש בה בסקריפטים חדשים.

הפונקציה מקבלת את כל הגורמים המפעילים שניתן להתקין שמשויכים לפרויקט הנוכחי ולמשתמש הנוכחי.

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

חזרה

Trigger[] – מערך של הגורמים המפעילים של המשתמש הנוכחי שמשויכים לפרויקט הזה.

אישור

סקריפטים שמשתמשים בשיטה הזו דורשים הרשאה עם אחד או יותר מהיקפי הגישה הבאים:

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