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

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

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

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

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

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

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

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

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

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