דף זה תורגם על ידי 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`	הפונקציה מחזירה אובייקט כדי לקבוע אם המשתמש צריך לאשר לסקריפט הזה להשתמש בשירות אחד או יותר, וכדי לספק את כתובת ה-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.
var triggers = ScriptApp.getProjectTriggers();
for (var 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 Web Token (JWT) מקודד, וצריך לפענח אותו כדי לחלץ ממנו מידע. בדוגמאות הבאות מוסבר איך לפענח את האסימון ולחלץ את מזהה פרופיל Google של המשתמש האפקטיבי.

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

הפונקציה מחזירה ערך 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.
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());

פרמטרים

שם	תיאור	התיאור
`document`	`Document`	קובץ Google Docs שעשוי להכיל גורמים מפעילים שניתנים להתקנה.

החזרות

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

פרמטרים

שם	תיאור	התיאור
`form`	`Form`	קובץ Google Forms שעשוי להכיל טריגרים שניתנים להתקנה.

החזרות

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

פרמטרים

שם	תיאור	התיאור
`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.
  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 מועבר ישירות לנקודת הקצה של ההרשאה (לא כחלק מכתובת ה-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