דף זה תורגם על ידי Cloud Translation API.

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

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

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

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

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

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

שיטה א': שימוש בכלי העריכה

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

שיטה ב': שימוש בקובץ המניפסט

כדי להפעיל שירותים מתקדמים, צריך לערוך את קובץ המניפסט. לדוגמה, כדי להפעיל את השירות המתקדם Google Drive, מוסיפים את השדה enabledAdvancedServices לאובייקט dependencies:

{
  "timeZone": "America/Denver",
  "dependencies": {
    "enabledAdvancedServices": [
      {
        "userSymbol": "Drive",
        "version": "v3",
        "serviceId": "drive"
      }
    ]
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8"
}

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

שלב 2: הפעלת Google Cloud API (פרויקטים רגילים ב-Google Cloud בלבד)

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

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

פותחים את פרויקט Cloud שמשויך לסקריפט ב** מסוף Google Cloud**.
בחלק העליון של המסוף, לוחצים על סרגל החיפוש ומקלידים חלק מהשם של ה-API (למשל, Calendar). לאחר מכן לוחצים על השם כשרואים אותו.
לוחצים על Enable API.
סוגרים את Google Cloud Console וחוזרים לכלי לעריכת סקריפטים.

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

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

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

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

גוף הבקשה (בדרך כלל משאב), כאובייקט JavaScript.
נתיב או פרמטרים נדרשים, כארגומנטים נפרדים. אם השיטה דורשת כמה פרמטרים של נתיב, הם מופיעים בסדר שבו הם מפורטים בכתובת ה-URL של נקודת הקצה של ה-API.
הקובץ המצורף להעלאת המדיה, כארגומנט Blob
פרמטרים אופציונליים (בדרך כלל פרמטרים של שאילתה), כאובייקט JavaScript שממפה שמות של פרמטרים לערכים.
כותרות של בקשת HTTP, כאובייקט JavaScript שממפה שמות של כותרות לערכים של כותרות.

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

יש כמה מקרים חריגים שחשוב להכיר:

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

דוגמה: Calendar.Events.insert

נניח שאתם רוצים ליצור אירוע ביומן. בתיעוד של Google Calendar API מוצגת המבנה של בקשת ה-HTTP המתאימה:

פועל HTTP: POST
כתובת ה-URL של הבקשה: https://www.googleapis.com/calendar/v3/calendars/{calendarId}/events
גוף הבקשה: משאב Event.
פרמטרים של שאילתה: sendUpdates,‏ supportsAttachments וכו'.

ב-Apps Script, חתימת השיטה נקבעת על ידי שינוי הסדר של הקלט הזה:

‫Body: משאב האירוע (אובייקט JavaScript).
נתיב: calendarId (מחרוזת).
פרמטרים אופציונליים: פרמטרים של שאילתה (אובייקט JavaScript).

הקריאה למתודה שמתקבלת נראית כך:

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: {
    dateTime: '2026-01-01T12:00:00-05:00'
  },
  end: {
    dateTime: '2026-01-01T13:00:00-05:00'
  }
};
const calendarId = 'primary';
const optionalArgs = {
  sendUpdates: 'all'
};

Calendar.Events.insert(event, calendarId, optionalArgs);

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

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

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

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

בטבלה הבאה מוצגת השוואה בין שתי השיטות:

תכונה	שירות מתקדם	‫UrlFetch ‏ (HTTP)
הרשאה	הטיפול מתבצע באופן אוטומטי	נדרש טיפול ידני
השלמה אוטומטית	זמין	לא זמין
היקף הפונקציונליות	יכול להיות שזו קבוצת משנה של ה-API	גישה מלאה לכל התכונות של API
מורכבות	קל יותר	מורכב יותר (נדרשת בנייה של כותרות וניתוח של תגובות)

השוואת קוד

דוגמאות הקוד מראות את ההבדל ברמת המורכבות בין יצירת אירוע ביומן באמצעות השירות המתקדם לבין יצירת אירוע ביומן באמצעות UrlFetchApp.

שירות מתקדם:

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: { dateTime: '2026-01-01T12:00:00-05:00' },
  end: { dateTime: '2026-01-01T13:00:00-05:00' }
};

const optionalArgs = {
  sendUpdates: 'all'
};

Calendar.Events.insert(event, 'primary', optionalArgs);

‫UrlFetch (HTTP):

const event = {
  summary: 'Lunch',
  location: 'Deli',
  start: { dateTime: '2026-01-01T12:00:00-05:00' },
  end: { dateTime: '2026-01-01T13:00:00-05:00' }
};
const url = 'https://www.googleapis.com/calendar/v3/calendars/primary/events?sendUpdates=all';
const options = {
  method: 'post',
  contentType: 'application/json',
  headers: {
    Authorization: `Bearer ${ScriptApp.getOAuthToken()}`
  },
  payload: JSON.stringify(event)
};

UrlFetchApp.fetch(url, options);

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

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

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

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