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

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

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

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

פרמטרים

חזרה

‫AuthorizationInfo – אובייקט שיכול לספק מידע על סטטוס ההרשאה של המשתמש.

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

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

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 — אובייקט שמספק מידע על סטטוס ההרשאה של המשתמש וכתובת URL להרשאה במקרה שחסרות הסכמות מסוימות.

מקבל אסימון זהות של 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}`);

חזרה

‫String – אסימון הזהות אם הוא זמין, אחרת null.

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

חזרה

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

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

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

חזרה

‫String – ייצוג מחרוזת של אסימון OAuth 2.0.

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

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

חזרה

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

אישור

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

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

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

חזרה

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

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

// 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 – אם הביטול נכשל

יוצר builder לאסימון מצב שאפשר להשתמש בו ב-API של קריאה חוזרת (callback) (כמו תהליך 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 – אובייקט שמשמש להמשך תהליך יצירת טוקן המצב.

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

// 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

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

השיטה הזו פועלת רק כשמשתמשים מריצים את הסקריפט מממשק שמאפשר הסכמה פרטנית, למשל מתוך סביבת הפיתוח המשולבת (IDE) של Apps Script. כשהסקריפט מופעל בלי הסכמות חסרות מפלטפורמה לא נתמכת, כמו תוסף ל-Google Workspace, הסקריפט מציג בקשת הרשאה בתחילת ההפעלה כדי לבקש את כל ההיקפים.

ScriptApp.requireAllScopes(ScriptApp.AuthMode.FULL);

פרמטרים

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

השיטה הזו פועלת רק כשמשתמשים מריצים את הסקריפט מממשק שמאפשר הסכמה פרטנית, למשל מתוך סביבת הפיתוח המשולבת (IDE) של Apps Script. כשהסקריפט מופעל בלי הסכמות חסרות מפלטפורמה לא נתמכת, כמו תוסף ל-Google Workspace, הסקריפט מציג בקשת הרשאה בתחילת ההפעלה כדי לבקש את כל ההיקפים.

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

פרמטרים