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 בסקריפט מספיקים כדי להעניק הרשאה ל-Google API אחר שבדרך כלל נדרש תהליך 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 – כשביטול התוקף נכשל

יצירת בונה לאסימון מצב שאפשר להשתמש בו ב-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 – אובייקט המשמש להמשך תהליך היצירה של אסימון המצב.

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

// Creates an edit trigger for a spreadsheet identified by ID.
ScriptApp.newTrigger('myFunction')
    .forSpreadsheet('1234567890abcdefghijklmnopqrstuvwxyz_a1b2c3')
    .onEdit()
    .create();

פרמטרים

חזרה

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',
]);

פרמטרים