השירותים המתקדמים ב-Apps Script מאפשרים למפתחים מנוסים להתחבר לממשקי API ציבוריים מסוימים של Google עם פחות הגדרות מאשר שימוש בממשקי ה-HTTP שלהם. שירותים מתקדמים הם בעצם עטיפות דקות של ממשקי ה-API האלה של Google. הם פועלים בדומה לשירותים המובנים של Apps Script – לדוגמה, הם מציעים השלמה אוטומטית, ו-Apps Script מטפל בתהליך ההרשאה באופן אוטומטי. עם זאת, כדי להשתמש בשירות מתקדם בסקריפט, צריך להפעיל אותו.
כדי לראות אילו ממשקי Google API זמינים כשירותים מתקדמים, צריך לחפש את הקטע Advanced Google Services (שירותים מתקדמים של Google) בReference (הפניה). אם אתם רוצים להשתמש ב-Google API שלא זמין כשירות מתקדם, פשוט מתחברים אליו כמו לכל API חיצוני אחר.
שירותים מתקדמים או HTTP?
כל אחד מהשירותים המתקדמים של Google משויך ל-API ציבורי של Google. ב-Apps Script, אפשר לגשת לממשקי ה-API האלה באמצעות שירותים מתקדמים או פשוט לשלוח את בקשות ה-API ישירות באמצעות UrlFetch.
אם משתמשים בשיטה של שירות מתקדם, Apps Script מטפל בתהליך ההרשאה ומציע תמיכה בהשלמה אוטומטית. עם זאת, כדי להשתמש בשירות המתקדם, צריך להפעיל אותו. בנוסף, חלק מהשירותים המתקדמים מספקים רק קבוצת משנה של הפונקציונליות שזמינה ב-API.
אם אתם משתמשים בשיטה UrlFetch כדי לגשת ל-API ישירות, אתם בעצם מתייחסים ל-Google API כאל API חיצוני. בשיטה הזו אפשר להשתמש בכל ההיבטים של ה-API. עם זאת, תצטרכו לטפל בעצמכם בהרשאת ה-API. צריך גם ליצור את הכותרות הנדרשות ולנתח את התגובות של ה-API.
באופן כללי, הכי קל להשתמש בשירות מתקדם כשאפשר, ולהשתמש בשיטה UrlFetch רק אם השירות המתקדם לא מספק את הפונקציונליות שדרושה לכם.
דרישות
כדי להשתמש בשירות מתקדם, צריך לעמוד בדרישות הבאות:
- צריך להפעיל את השירות המתקדם בפרויקט של הסקריפט.
צריך לוודא שממשק ה-API שמתאים לשירות המתקדם מופעל בפרויקט Cloud Platform (GCP) שבו נעשה שימוש בסקריפט.
אם בפרויקט הסקריפט שלכם נעשה שימוש בפרויקט GCP שמוגדר כברירת מחדל שנוצר בתאריך 8 באפריל 2019 או אחריו, ה-API מופעל באופן אוטומטי אחרי שמפעילים את השירות המתקדם ושומרים את פרויקט הסקריפט. אם עדיין לא עשיתם זאת, יכול להיות שתתבקשו גם להסכים לתנאים ולהגבלות של Google Cloud ושל Google APIs.
אם פרויקט הסקריפט שלכם משתמש בפרויקט GCP רגיל או בפרויקט GCP ישן שמוגדר כברירת מחדל, אתם צריכים להפעיל באופן ידני את ה-API המתאים של השירות המתקדם בפרויקט GCP. כדי לבצע את השינוי הזה, צריכה להיות לכם גישת עריכה לפרויקט GCP.
מידע נוסף זמין במאמר בנושא פרויקטים ב-Cloud Platform.
הפעלת שירותים מתקדמים
כדי להשתמש בשירות מתקדם של Google, פועלים לפי ההוראות הבאות:
- פותחים את פרויקט Apps Script.
- בצד ימין, לוחצים על עורך .
- בצד ימין, ליד שירותים, לוחצים על הוספת שירות .
- בוחרים שירות מתקדם של Google ולוחצים על הוספה.
אחרי שמפעילים שירות מתקדם, הוא זמין בהשלמה האוטומטית.
איך נקבעים חתימות של שיטות
בדרך כלל, שירותים מתקדמים משתמשים באותם אובייקטים, שמות שיטות ופרמטרים כמו ממשקי ה-API הציבוריים התואמים, אבל חתימות השיטות מתורגמות לשימוש ב-Apps Script. פונקציית ההשלמה האוטומטית של עורך הסקריפטים בדרך כלל מספקת מספיק מידע כדי להתחיל, אבל הכללים שבהמשך מסבירים איך Apps Script יוצר חתימת שיטה מ-Google API ציבורי.
בקשות ל-Google APIs יכולות לקבל מגוון סוגים שונים של נתונים, כולל פרמטרים של נתיב, פרמטרים של שאילתה, גוף בקשה ו/או קובץ מצורף של העלאת מדיה. חלק מהשירותים המתקדמים יכולים גם לקבל כותרות ספציפיות של בקשות HTTP (לדוגמה, השירות המתקדם של Calendar).
חתימת השיטה המתאימה ב-Google Apps Script כוללת את הארגומנטים הבאים:
- גוף הבקשה (בדרך כלל משאב), כאובייקט JavaScript.
- נתיב או פרמטרים נדרשים, כארגומנטים נפרדים.
- הקובץ המצורף של העלאת המדיה, כארגומנט
Blob - פרמטרים אופציונליים, כאובייקט JavaScript שממפה שמות של פרמטרים לערכים.
- כותרות של בקשת HTTP, כאובייקט JavaScript שממפה שמות של כותרות לערכים של כותרות.
אם בשיטה אין פריטים בקטגוריה מסוימת, החלק הזה בחתימה מושמט.
יש כמה מקרים חריגים שכדאי להכיר:
- בשיטות שמקבלות העלאת מדיה, הפרמטר
uploadTypeמוגדר באופן אוטומטי. - שמות של שיטות שנקראות
deleteב-Google API נקראותremoveב-Apps Script, כיdeleteהיא מילה שמורה ב-JavaScript. - אם שירות מתקדם מוגדר לקבל כותרות של בקשות HTTP, ואתם מגדירים אובייקט JavaScript של כותרות בקשות, אתם צריכים להגדיר גם אובייקט JavaScript של פרמטרים אופציונליים (אובייקט ריק אם אתם לא משתמשים בפרמטרים אופציונליים).
תמיכה בשירותים מתקדמים
שירותים מתקדמים הם רק עטיפות דקות שמאפשרות שימוש בממשקי Google API ב-Apps Script. לכן, כל בעיה שמתגלה במהלך השימוש בהם היא בדרך כלל בעיה ב-API הבסיסי, ולא ב-Apps Script עצמו.
אם נתקלתם בבעיה במהלך השימוש בשירות מתקדם, צריך לדווח עליה באמצעות הוראות התמיכה של ה-API הבסיסי. קישורים להנחיות התמיכה האלה מופיעים בכל מדריך לשירות מתקדם בקטע Reference של Apps Script.