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

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

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

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

כל אחד מהשירותים המתקדמים של Google משויך ל-Google API ציבורי. ב-Apps Script, אפשר לגשת לממשקי ה-API האלה דרך שירותים מתקדמים או לשלוח את בקשות ה-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 ולוחצים על הוספה.

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

1. פותחים את פרויקט GCP שמשויך לסקריפט ב מסוף Google Cloud:
2. בחלק העליון של המסוף, לוחצים על סרגל החיפוש ומקלידים חלק מהשם של ל-API (למשל, 'יומן'), ולוחצים על השם כשהוא מופיע.
3. במסך הבא לוחצים על Enable 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 לאובייקט ריק, אם לא משתמשים פרמטרים אופציונליים).

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

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

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