שירותי Google מתקדמים

השירותים המתקדמים ב-Apps Script מאפשרים למפתחים מנוסים להתחבר לממשקי Google API ציבוריים מסוימים עם תהליך הגדרה קצר יותר מאשר באמצעות ממשקי ה-HTTP שלהם. שירותים מתקדמים הם למעשה רכיבי wrapper של Google APIs. הם פועלים בדומה לשירותים המובנים של Apps Script. לדוגמה, הם מציעים השלמה אוטומטית, ו-Apps Script מטפל באופן אוטומטי בתהליך ההרשאה. עם זאת, צריך להפעיל שירות מתקדם כדי להשתמש בו בסקריפט.

כדי לבדוק אילו ממשקי Google API זמינים כשירותים מתקדמים, תוכלו לחפש את הקטע שירותים מתקדמים של Google בחומר העזר. אם אתם רוצים להשתמש ב-Google API שלא זמין בתור שירות מתקדם, עליכם להתחבר אליו כמו לכל API חיצוני אחר.

שירותים מתקדמים או HTTP?

כל אחד מהשירותים המתקדמים של Google משויך ל-Google API ציבורי. אפשר לגשת לממשקי ה-API האלה ב-Apps Script דרך שירותים מתקדמים, או פשוט לשלוח את בקשות ה-API ישירות באמצעות UrlFetch.

אם אתם משתמשים בשיטת השירות המתקדמת, Apps Script מטפל בתהליך ההרשאה ומציע תמיכה בהשלמה אוטומטית. עם זאת, עליכם להפעיל את השירות המתקדם כדי שתוכלו להשתמש בו. בנוסף, חלק מהשירותים המתקדמים מספקים רק חלק מהפונקציות שזמינות ב-API.

אם אתם משתמשים בשיטה UrlFetch כדי לגשת ישירות ל-API, אתם למעשה מתייחסים ל-Google API כממשק API חיצוני. כך אפשר להשתמש בכל ההיבטים של ה-API. עם זאת, אתם נדרשים לטפל בעצמכם בהרשאה ל-API. בנוסף, תצטרכו ליצור כותרות נדרשות ולנתח את תגובות ה-API.

באופן כללי, עדיף להשתמש בשירות מתקדם כשאפשר, ולהשתמש בשיטה UrlFetch רק כשהשירות המתקדם לא מאפשר את הפונקציונליות הנדרשת.

דרישות

כדי להשתמש בשירות מתקדם, עליכם לעמוד בדרישות הבאות:

1. עליכם להפעיל את השירות המתקדם בפרויקט הסקריפט.

2. עליכם לוודא שה-API שתואם לשירות המתקדם מופעל בפרויקט Cloud Platform (GCP) שבו הסקריפט משתמש.

   אם בפרויקט הסקריפט שלכם נעשה שימוש בפרויקט ברירת מחדל של GCP שנוצר ב-8 באפריל 2019 או לאחר מכן, ה-API יופעל באופן אוטומטי אחרי שתפעילו את השירות המתקדם ותשמרו את פרויקט הסקריפט. אם עדיין לא עשיתם זאת, ייתכן שתתבקשו להסכים גם לתנאים ולהגבלות של Google Cloud ושל Google APIs.

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

למידע נוסף, תוכלו לקרוא את המאמר פרויקטים ב-Cloud Platform.

הפעלת שירותים מתקדמים

כדי להשתמש בשירות מתקדם של Google, פועלים לפי ההוראות הבאות:

1. פותחים את פרויקט Apps Script.
2. מימין, לוחצים על עורך .
3. מימין, ליד Services, לוחצים על Add a service (הוספת שירות) .
4. בוחרים שירות Google מתקדם ולוחצים על הוספה.

הערה: אם אתם משתמשים בפרויקט GCP רגיל (או בפרויקט ישן יותר של GCP שנוצר לפני 8 באפריל 2019), עליכם גם להפעיל באופן ידני את ה-API המתאים לשירות המתקדם. מבצעים את הפעולות הבאות כדי להפעיל את ה-API:

1. פותחים את פרויקט GCP שמשויך לסקריפט במסוף Google Cloud.
2. בחלק העליון של המסוף, לוחצים על סרגל החיפוש, מקלידים חלק מהשם של ה-API (למשל, 'יומן'), ולוחצים על השם כשהוא מופיע.
3. במסך הבא, לוחצים על Enable API (הפעלת API).
4. סוגרים את מסוף Google Cloud וחוזרים אל עורך הסקריפטים. לוחצים על אישור בתיבת הדו-שיח.

אחרי שמפעילים שירות מתקדם, הוא זמין בהשלמה האוטומטית.

איך נקבעות החתימות של השיטות

בשירותים מתקדמים בדרך כלל נעשה שימוש באותם אובייקטים, שמות שיטות ופרמטרים כמו ממשקי ה-API הציבוריים התואמים, אם כי חתימות השיטה מתורגמות לשימוש ב-Apps Script. בדרך כלל, פונקציית ההשלמה האוטומטית של עורך הסקריפטים מספקת מספיק מידע כדי להתחיל, אבל הכללים שבהמשך מסבירים איך Apps Script יוצר חתימת שיטה מ-Google API ציבורי.

בקשות ל-Google APIs יכולות לקבל מגוון סוגים שונים של נתונים, כולל פרמטרים של נתיב, פרמטרים של שאילתות, גוף הבקשה ו/או קובץ מצורף של מדיה. חלק מהשירותים המתקדמים יכולים גם לקבל כותרות ספציפיות של בקשות HTTP (לדוגמה, השירות המתקדם של יומן Google).

חתימת השיטה המתאימה ב-Google Apps Script כוללת את הארגומנטים הבאים:

1. גוף הבקשה (בדרך כלל משאב) כאובייקט JavaScript.
2. נתיב או פרמטרים נדרשים, כארגומנטים בודדים.
3. הקובץ המצורף להעלאת המדיה, כארגומנט Blob.
4. פרמטרים אופציונליים, כאובייקט JavaScript שממפה שמות של פרמטרים לערכים.
5. כותרות של בקשות HTTP, כאובייקט JavaScript שממפה שמות של כותרות לערכי כותרות.

אם לשיטה אין פריטים בקטגוריה מסוימת, החלק הזה בחתימה יושמט.

יש כמה חריגים מיוחדים שצריך לשים לב אליהם:

• בשיטות שמקבלות העלאת מדיה, הפרמטר uploadType מוגדר באופן אוטומטי.
• שיטות שנקראות delete ב-Google API נקראות remove ב-Apps Script, כי delete היא מילה שמורה ב-JavaScript.
• אם שירות מתקדם מוגדר לקבל כותרות של בקשות HTTP ומגדירים אובייקט JavaScript לכותרות של בקשות, צריך להגדיר גם את אובייקט JavaScript של הפרמטרים האופציונליים (לאובייקט ריק אם לא משתמשים בפרמטרים אופציונליים).

תמיכה בשירותים מתקדמים

שירותים מתקדמים הם רק רכיבי wrapper שמאפשרים להשתמש בממשקי Google API בתוך Apps Script. לכן, כל בעיה שנתקלת בה במהלך השימוש היא בדרך כלל בעיה ב-API הבסיסי ולא ב-Apps Script עצמו.

אם נתקלתם בבעיה במהלך השימוש בשירות המתקדם, עליכם לדווח עליה באמצעות הוראות התמיכה ל-API הבסיסי. קישורים להוראות התמיכה האלה מופיעים בכל מדריך שירות מתקדם בקטע הפניה של Apps Script.