השירותים המתקדמים ב-Apps Script מאפשרים למפתחים מנוסים להתחבר לממשקי API ציבוריים מסוימים של Google, שנדרשים להם פחות הגדרה, מאשר באמצעות ממשקי ה-HTTP שלהם. שירותים מתקדמים הם למעשה חבילות דקות שמקיפות את ממשקי ה-API של Google. הם פועלים כמו השירותים המובנים של Apps Script – לדוגמה, הם מציעים השלמה אוטומטית, ו-Apps Script מטפל באופן אוטומטי בתהליך ההרשאה. עם זאת, צריך להפעיל שירות מתקדם כדי שתוכלו להשתמש בו בסקריפט.
כדי לראות אילו ממשקי Google API זמינים כשירותים מתקדמים, אפשר לעיין בקטע Advanced Google Services בחומר העזרה. אם אתם רוצים להשתמש ב-Google API שלא זמין כשירות מתקדם, פשוט מתחברים אליו כמו לכל API חיצוני אחר.
שירותים מתקדמים או HTTP?
כל אחד מהשירותים המתקדמים של Google משויך ל-Google API ציבורי.
ב-Apps Script, אפשר לגשת לממשקי ה-API האלה דרך שירותים מתקדמים או פשוט לשלוח את בקשות ה-API ישירות באמצעות UrlFetch.
אם משתמשים בשיטת השירות המתקדמת, Apps Script מטפל בתהליך ההרשאה ומציע תמיכה בהשלמה אוטומטית. אבל כדי להשתמש בו צריך להפעיל את השירות המתקדם. בנוסף, חלק מהשירותים המתקדמים מספקים רק קבוצת משנה של הפונקציונליות שזמינה ב-API.
אם אתם משתמשים ב-method 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 (לדוגמה, השירות המתקדם של יומן Google).
חתימה של השיטה המתאימה ב-Google Apps Script כוללת את הארגומנטים הבאים:
- גוף הבקשה (בדרך כלל משאב), כאובייקט JavaScript.
- נתיב או פרמטרים נדרשים, כארגומנטים נפרדים.
- הקובץ המצורף להעלאת המדיה, כארגומנטים של
Blob. - פרמטרים אופציונליים, כאובייקט JavaScript שממפה שמות של פרמטרים לערכים.
- כותרות של בקשות HTTP, כאובייקט JavaScript שממפה שמות של כותרות לערכי כותרות.
אם אין ל-method פריטים בקטגוריה מסוימת, החלק הזה של החתימה יושמט.
חשוב לדעת שיש כמה חריגים מיוחדים:
- בשיטות שמקבלות העלאת מדיה, הפרמטר
uploadTypeמוגדר באופן אוטומטי. - שיטות שנקראות
deleteב-Google API נקראותremoveב-Apps Script, כיdeleteהיא מילה שמורה ב-JavaScript. - אם שירות מתקדם מוגדר לקבל כותרות של בקשות HTTP, ואתם מגדירים אובייקט JavaScript של כותרות הבקשה, עליכם להגדיר גם את אובייקט ה-JavaScript של הפרמטרים האופציונליים (לאובייקט ריק אם אתם לא משתמשים בפרמטרים אופציונליים).
תמיכה בשירותים מתקדמים
שירותים מתקדמים הם רק חבילות דקות שמאפשרות להשתמש בממשקי Google API ב-Apps Script. לכן, כל בעיה שנתקלים בה במהלך השימוש בהם היא בדרך כלל בעיה ב-API הבסיסי, ולא ב-Apps Script עצמו.
אם נתקלת בבעיה במהלך השימוש בשירות מתקדם, עליך לדווח עליה לפי הוראות התמיכה של ממשק ה-API הבסיסי. קישורים להנחיות התמיכה האלה מופיעים בכל מדריך שירות מתקדם בקטע Reference ב-Apps Script.