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 – אסימון הזהות אם הוא זמין, אחרת null.

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

חזרה

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

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

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

אפשר להשתמש בשיטה הזו כדי לקרוא לממשקי Google API ש-Apps Script לא תומך בהם ישירות. מעבירים את הטוקן שמוחזר בכותרת Authorization של בקשת HTTP באמצעות UrlFetchApp.fetch(url, params).

const url = 'https://www.googleapis.com/drive/v3/files';
const method = 'GET';
const headers = {
  Authorization: 'Bearer ' + ScriptApp.getOAuthToken(),
};
const response = UrlFetchApp.fetch(url, {
  method,
  headers,
});

חזרה

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

מקפיצה את הודעות השגיאה (Throws)

‫Error – אם הביטול נכשל

יוצר builder לאסימון מצב שאפשר להשתמש בו ב-callback 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();

לפני שיוצרים טריגר, צריך לוודא שלפונקציה המשויכת יש את כל הרשאות ה-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',
]);

פרמטרים