google.script.run
הוא ממשק API אסינכרוני של JavaScript בצד הלקוח שזמין ב-
דפי שירות HTML שיכולים לקרוא ל-Apps Script בצד השרת
למשימות ספציפיות. לבצע פעולות בתיבות דו-שיח או בסרגלי צד ב-Google Docs, ב-Sheets או ב-Forms מצד הלקוח
את הקוד, יש להשתמש ב-google.script.host
. מידע נוסף זמין במאמר
מדריך לתקשורת עם פונקציות שרת
בשירות HTML.
שיטות
שיטה | סוג הערך המוחזר | תיאור קצר |
---|---|---|
myFunction(...) (כל פונקציה בצד השרת) |
void |
מפעיל את פונקציית Apps Script בצד השרת עם השם המתאים. |
withFailureHandler(function) |
google.script.run |
מגדירה פונקציית קריאה חוזרת שתרוץ אם הפונקציה בצד השרת גורמת לחריגה. |
withSuccessHandler(function) |
google.script.run |
מגדירה פונקציית קריאה חוזרת שתרוץ אם הפונקציה בצד השרת חוזרת בהצלחה. |
withUserObject(object) |
google.script.run |
מגדיר אובייקט שיועבר כפרמטר שני לרכיבי ה-handler של הצלחה וכשלים. |
מסמכי תיעוד מפורטים
myFunction(...)
(כל פונקציה בצד השרת)
מפעיל את פונקציית Apps Script בצד השרת עם השם המתאים.
Code.gs
function doGet() { return HtmlService.createHtmlOutputFromFile('Index'); } function doSomething() { Logger.log('I was called!'); }
Index.html
<!DOCTYPE html> <html> <head> <base target="_top"> <script> google.script.run.doSomething(); </script> </head> <body> </body> </html>
פרמטרים
שם | סוג | תיאור |
---|---|---|
... | רוב הסוגים הם משפטיים, אבל לא Date , Function ,
או רכיב DOM שאינו form ; הצגת התיאור | פרמטרים משפטיים הם JavaScript
רכיבים בסיסיים כמו Number , Boolean , String או
null , וגם אובייקטים ומערכים של JavaScript שמורכבים מפרימיטיבים,
אובייקטים ומערכים. גם רכיב form בדף הוא חוקי כפרמטר, אבל
הוא חייב להיות הפרמטר היחיד של הפונקציה. הבקשות ייכשלו אם תנסו להעביר
Date , Function , רכיב DOM מלבד form או רכיב אחר
סוג אסור, כולל סוגים אסורים בתוך אובייקטים או מערכים. אובייקטים שיוצרים מעגלי
גם ההפניות ייכשלו, ושדות לא מוגדרים בתוך מערכים יהפכו ל-null . שימו לב
אובייקט שמועבר לשרת הופך לעותק של המקור. אם פונקציית שרת מקבלת
ומשנה את המאפיינים שלו, המאפיינים של הלקוח לא מושפעים. |
חזרה
void
- השיטה הזו אסינכרונית ולא חוזרת ישירות. עם זאת,
הפונקציה בצד השרת יכולה להחזיר ערך ללקוח כפרמטר שמועבר
מטפל להצלחה; כמו כן, סוגי ההחזרות כפופים
הגבלות זהות לאלה של סוגי הפרמטרים, מלבד העובדה שהרכיב form
אינו חוקי
סוג החזרה
withFailureHandler(function)
מגדירה פונקציית קריאה חוזרת שתרוץ אם הפונקציה בצד השרת גורמת לחריגה.
Error
מועבר לפונקציה כארגומנט הראשון,
אובייקט user (אם יש) מועבר כארגומנט שני. ללא
מטפל בכשלים, הכשלים נרשמים בלוח JavaScript. כדי לשנות את זה, צריך להפעיל
withFailureHandler(null)
או לספק handler של כשל שלא עושה דבר.
Code.gs
function doGet() { return HtmlService.createHtmlOutputFromFile('Index'); } function getUnreadEmails() { // 'got' instead of 'get' will throw an error. return GmailApp.gotInboxUnreadCount(); }
Index.html
<!DOCTYPE html> <html> <head> <base target="_top"> <script> function onFailure(error) { var div = document.getElementById('output'); div.innerHTML = "ERROR: " + error.message; } google.script.run.withFailureHandler(onFailure) .getUnreadEmails(); </script> </head> <body> <div id="output"></div> </body> </html>
פרמטרים
שם | סוג | תיאור |
---|---|---|
function | Function | פונקציית קריאה חוזרת בצד הלקוח
הרצה אם הפונקציה בצד השרת גורמת לחריגה. ה
Error
מועבר לפונקציה כארגומנט הראשון,
user object (אם יש) מועבר כארגומנט שני |
חזרה
google.script.run
— 'הרצת הסקריפטים' הזה, לשרשורים
withSuccessHandler(function)
מגדירה פונקציית קריאה חוזרת שתרוץ אם הפונקציה בצד השרת חוזרת בהצלחה. המיקום של המוחזר מועבר לפונקציה כארגומנט הראשון, user object (אם קיים) מועבר כארגומנט שני.
Code.gs
function doGet() { return HtmlService.createHtmlOutputFromFile('Index'); } function getUnreadEmails() { return GmailApp.getInboxUnreadCount(); }
Index.html
<!DOCTYPE html> <html> <head> <base target="_top"> <script> function onSuccess(numUnread) { var div = document.getElementById('output'); div.innerHTML = 'You have ' + numUnread + ' unread messages in your Gmail inbox.'; } google.script.run.withSuccessHandler(onSuccess) .getUnreadEmails(); </script> </head> <body> <div id="output"></div> </body> </html>
פרמטרים
שם | סוג | תיאור |
---|---|---|
function | Function | פונקציית קריאה חוזרת בצד הלקוח הרצה אם הפונקציה בצד השרת חוזרת בהצלחה; הערך המוחזר של השרת מועבר כארגומנט הראשון, וגם האובייקט user (אם יש כזה). מועבר כארגומנט שני |
חזרה
google.script.run
— 'הרצת הסקריפטים' הזה, לשרשורים
withUserObject(object)
מגדיר אובייקט שיועבר כפרמטר שני לרכיבי ה-handler של הצלחה וכשלים. "המשתמש הזה
object" - בלי להתבלבל עם
המחלקה User
— מאפשרת לבצע את הקריאה החוזרת (callback)
מגיבות להקשר שבו הלקוח יצר קשר עם השרת. כי אובייקטים של משתמשים
לא נשלחים לשרת, הם אינם כפופים למגבלות על פרמטרים והחזרות
לערכים של קריאות שרת. עם זאת, האובייקטים של המשתמש לא יכולים להיות אובייקטים
שנוצר באמצעות האופרטור new
.
Code.gs
function doGet() { return HtmlService.createHtmlOutputFromFile('Index'); } function getEmail() { return Session.getActiveUser().getEmail(); }
Index.html
<!DOCTYPE html> <html> <head> <base target="_top"> <script> function updateButton(email, button) { button.value = 'Clicked by ' + email; } </script> </head> <body> <input type="button" value="Not Clicked" onclick="google.script.run .withSuccessHandler(updateButton) .withUserObject(this) .getEmail()" /> <input type="button" value="Not Clicked" onclick="google.script.run .withSuccessHandler(updateButton) .withUserObject(this) .getEmail()" /> </body> </html>
פרמטרים
שם | סוג | תיאור |
---|---|---|
object | Object | אובייקט להעברה כפרמטר שני
למטפלים בהצלחות ובכשלים. מכיוון שאובייקטים של משתמשים לא נשלחים לשרת, הם לא
בכפוף למגבלות על פרמטרים וערכי החזרה עבור
קריאות שרת. עם זאת, אי אפשר ליצור אובייקטים של משתמשים
באמצעות האופרטור new |
חזרה
google.script.run
— 'הרצת הסקריפטים' הזה, לשרשורים