השירותים המתקדמים ב-Apps Script מאפשרים למפתחים מנוסים להתחבר לממשקי API ציבוריים מסוימים של Google, שנדרשים להם פחות הגדרה, מאשר באמצעות ממשקי ה-HTTP שלהם. שירותים מתקדמים הם למעשה wrappers דלים סביב ממשקי ה-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 אין פריטים בקטגוריה מסוימת, החלק הזה של החתימה יושמט.
יש כמה מקרים חריגים מיוחדים שחשוב לשים לב אליהם:
- ב-methods שמקבלות העלאת מדיה, הפרמטר
uploadTypeמוגדר באופן אוטומטי. - שיטות בשם
deleteב-Google API נקראותremoveב-Apps Script, כיdeleteהיא מילה שמורה ב-JavaScript. - אם שירות מתקדם מוגדר לקבל כותרות של בקשות HTTP ואתם מגדירים אובייקט JavaScript עם כותרות של בקשות, צריך להגדיר גם את אובייקט ה-JavaScript של הפרמטרים האופציונליים (לאובייקט ריק אם לא משתמשים בפרמטרים אופציונליים).
תמיכה בשירותים מתקדמים
שירותים מתקדמים הם רק רכיבי wrapper דלים שמאפשרים את השימוש ב-Google API בתוך Apps Script. לכן, כל בעיה שנתקלתם בה במהלך השימוש בהם היא בדרך כלל בעיה ב-API הבסיסי, ולא ב-Apps Script עצמו.
אם נתקלים בבעיה במהלך שימוש בשירות מתקדם, צריך לדווח עליה באמצעות ההוראות לתמיכה של ה-API הרלוונטי. הקישורים להוראות התמיכה האלה מופיעים בכל מדריך שירות מתקדם, בקטע חומר העזר בנושא סקריפט של Apps.