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

השירותים המתקדמים ב-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.

אם משתמשים בשיטה 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 ולוחצים על הוספה.

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

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

בדרך כלל, בשירותים המתקדמים נעשה שימוש באותם אובייקטים, שמות שיטות ופרמטרים כמו ב-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 של הפרמטרים האופציונליים (לאובייקט ריק אם אתם לא משתמשים בפרמטרים אופציונליים).

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

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

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