‫Google משתמשת בטכנולוגיית AI כדי לתרגם תוכן לשפה המועדפת עליך. בתרגומים כאלו עשויות להיות שגיאות.

סוגי אירועים

בדף הזה מוסבר על המאפיין eventType ועל המפרטים של סוגי האירועים שזמינים ביומן Google API.

יומן Google מאפשר למשתמשים ליצור אירועים כלליים, וגם אירועים שמיועדים לתרחישי שימוש ספציפיים עם מאפיינים מותאמים אישית.

אפשר לראות את סוג האירוע במקומות הבאים ב-API:

כל האירועים מחזירים eventType.
מגדירים את eventType כשיוצרים או מעדכנים משאב אירוע. אם לא מוגדר, ה-API משתמש ב-'default'.
מציינים eventTypes בשיחה events.list כדי לרשום אירועים מסוגים ספציפיים. אם לא מציינים סוג, ה-API מחזיר את כל סוגי האירועים.
מציינים eventTypes בשיחה עם events.watch כדי להירשם לעדכונים על אירועים מסוגים ספציפיים. אם לא מציינים סוג, הבקשה נרשמת לכל סוגי האירועים.

אירוע ברירת מחדל

אירועים עם סוג האירוע default נוצרים ומשמשים כאחד המשאבים העיקריים של Calendar API. הם תומכים במגוון רחב של מאפיינים כדי להתאים אישית את האירוע.

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

יום הולדת

ימי הולדת הם אירועים מיוחדים שנמשכים יום שלם וחוזרים מדי שנה.

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

‫Calendar API תומך ב-methods‏ events.get,‏ events.instances ו-events.list לקריאת אירועי יום הולדת. אפשר להגדיר את eventTypes לערך 'birthday' כדי להציג רק אירועים של ימי הולדת. אם לא מציינים סוג, התשובה תכלול ימי הולדת לצד כל סוגי האירועים האחרים.

כדי לקבל פרטים נוספים על האירוע המיוחד הזה, בודקים את השדה birthdayProperties באובייקטים Event שמוחזרים. ‫birthdayProperties כולל את השדות הבאים:

‫type: סוג האירוע המיוחד, למשל יום הולדת, יום נישואין או תאריך משמעותי אחר.
‫customTypeName: תווית שמוגדרת על ידי המשתמש לאירוע המיוחד הזה. השדה הזה יאוכלס אם הערך של type הוא 'custom'.
‫contact: שם המשאב של איש הקשר שאליו מקושר האירוע המיוחד הזה, אם יש כזה. הפורמט הוא 'people/c12345' ואפשר להשתמש בו כדי לאחזר פרטים של אנשי קשר מ-People API.

ה-API מאפשר ליצור אירועים של ימי הולדת באמצעות השיטה events.insert עם המפרט הבא:

הערך של eventType מוגדר כ-'birthday'.
בשדות start ו-end צריך להגדיר אירוע של יום שלם שנמשך בדיוק יום אחד.
הערך של השדה visibility חייב להיות 'private'.
הערך של השדה transparency חייב להיות 'transparent'.
המינוי צריך להיות חוזר מדי שנה, כלומר השדה recurrence צריך להיות 'RRULE:FREQ=YEARLY'. אירועי יום הולדת שחלים ב-29 בפברואר צריכים לכלול את כלל החזרה הבא: 'RRULE:FREQ=YEARLY;BYMONTH=2;BYMONTHDAY=-1'.
יכול להיות colorId,‏ summary ו-reminders.
יכול להיות birthdayProperties. אם מציינים את type, הערך שלו חייב להיות 'birthday', והשדות customTypeName ו-contact חייבים להיות ריקים.
לא יכולים להיות מאפיינים אחרים של האירוע.

ה-API מאפשר לעדכן את colorId,‏ summary ו-reminders של אירועי יום הולדת באמצעות ה-methods‏ events.update ו-events.patch. אפשר גם לעדכן את השדות start וend כדי לשנות את תאריך האירוע. במקרה כזה, הערכים החדשים צריכים להגדיר אירוע שנמשך יום שלם, בדיוק יום אחד. אי אפשר לעדכן את פרטי התזמון של אירוע יום הולדת אם האירוע מקושר לcontact, או אם type שלו הוא 'self'.

‫Calendar API לא מאפשר ליצור אירועים של ימי הולדת עם birthdayProperties מותאם אישית או לעדכן את המאפיינים האלה. אפשר לערוך תאריכים חשובים באמצעות People API, והשינויים מסתנכרנים עם היומן. באופן דומה, משתמשים יכולים לערוך את תאריך הלידה שלהם בפרופיל בחשבון Google, והוא מסתנכרן עם היומן.

בקשות שמנסות ליצור או לעדכן תאריך לידה בדרך לא נתמכת נכשלות. במקרה כזה, צריך לבדוק את הודעת השגיאה כדי לזהות את הבעיה.

ה-API תומך בפעולה events.import לאירועי יום הולדת, אבל האירוע מיובא כאירוע ברירת מחדל. במילים אחרות, הערך של eventType יהיה 'default'.

ממשק ה-API תומך בשיטה events.watch כדי להירשם לשינויים באירועי יום הולדת ביומן. אפשר להגדיר את eventTypes לערך 'birthday' כדי להירשם לעדכונים על אירועי ימי הולדת. אם לא מציינים סוג, הבקשה נרשמת לכל סוגי האירועים, כולל ימי הולדת.

אפשר למחוק אירועים של ימי הולדת באמצעות השיטה events.delete של Calendar API. מחיקת אירוע יום הולדת מהיומן לא משפיעה על הנתונים באנשי הקשר בחשבון Google או בפרופיל בחשבון Google.

אי אפשר לשנות את המארגן של אירוע יום הולדת באמצעות השיטות events.move או events.update.

אירועים מ-Gmail

אירועים שנוצרו אוטומטית מ-Gmail הם מסוג האירוע 'fromGmail'.

‫Calendar API לא מאפשר ליצור את סוג האירוע הזה באמצעות השיטה events.insert.

ממשק ה-API מאפשר לעדכן את המאפיינים המורחבים colorId,‏ reminders,‏ visibility,‏ transparency,‏ status,‏ attendees,‏ private ו-shared באמצעות השיטות events.update ו-events.patch.

ה-API תומך בשיטות events.get ו-events.list לקריאת אירועים מ-Gmail. אפשר להגדיר את eventTypes לערך 'fromGmail' כדי להציג רק אירועים שנוצרו מ-Gmail. אם לא מציינים סוג, האירועים מ-Gmail מופיעים לצד כל סוגי האירועים האחרים.

ה-API תומך בשיטה events.watch למינוי לשינויים באירועים מ-Gmail ביומן. אם לא מציינים סוג, הבקשה נרשמת לכל סוגי האירועים, כולל 'fromGmail'.

אתם יכולים למחוק אירועים מ-Gmail באמצעות השיטה events.delete של Calendar API.

אי אפשר לשנות את המארגן של אירוע מ-Gmail באמצעות השיטות events.move או events.update.

זמן לעצמי, לא בעבודה ומיקום עבודה

אתם יכולים להשתמש ב-Calendar API כדי ליצור ולנהל אירועים שבהם מוצג הסטטוס של משתמשי היומן.

התכונות האלה זמינות רק ביומנים הראשיים, ולחלק מהמשתמשים ביומן. מידע נוסף זמין במאמר ניהול אירועים של זמן לעצמי, לא בעבודה ומיקום עבודה.

סוגי אירועים ב-Apps Script

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

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

יצירה והגדרה של הסקריפט

כדי ליצור סקריפט, עוברים אל script.google.com/create.
בחלונית הימנית, ליד שירותים, לוחצים על סמל הוספת שירות .
בוחרים באפשרות Calendar API ולוחצים על הוספה.
אחרי שמפעילים את ה-API, הוא מופיע בחלונית הימנית. כדי לראות את רשימת השיטות והמחלקות שזמינות ב-API, מקלידים Calendar בעורך.

(אופציונלי) עדכון הפרויקט ב-Cloud

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

הוספת קוד לסקריפט

בדוגמת הקוד הבאה אפשר לראות איך לרשום, לקרוא וליצור אירועים עם ערכים שונים של eventType.

מדביקים את הקוד הבא בעורך הקוד.

const CALENDAR_ID = 'CALENDAR_ID' || 'primary';

/** Lists default events. */
function listDefaultEvents() {
  listEvents('default');
}

/** Lists birthday events. */
function listBirthdays() {
  listEvents('birthday');
}

/** Lists events from Gmail. */
function listEventsFromGmail() {
  listEvents('fromGmail');
}

/**
  * Lists events with the given event type. If no type is specified, lists all events.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/list
  */
function listEvents(eventType = undefined) {
  // Query parameters for the list request.
  const optionalArgs = {
    eventTypes: eventType ? [eventType] : undefined,
    singleEvents: true,
    timeMax: '2024-07-30T00:00:00+01:00',
    timeMin: '2024-07-29T00:00:00+01:00',
  }
  try {
    var response = Calendar.Events.list(CALENDAR_ID, optionalArgs);
    response.items.forEach(event => console.log(event));
  } catch (exception) {
    console.log(exception.message);
  }
}

/**
  * Reads the event with the given eventId.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/get
  */
function readEvent() {
  try {
    var response = Calendar.Events.get(CALENDAR_ID, 'EVENT_ID');
    console.log(response);
  } catch (exception) {
    console.log(exception.message);
  }
}

/** Creates a default event. */
function createDefaultEvent() {
  const event = {
    start: { dateTime: '2024-07-30T10:30:00+01:00'},
    end: { dateTime: '2024-07-30T12:30:00+01:00'},
    description: 'Created from Apps Script.',
    eventType: 'default',
    summary: 'Sample event',
  }
  createEvent(event);
}

/** Creates a birthday event. */
function createBirthday() {
  const event = {
    start: { date: '2024-01-29' },
    end: { date: '2024-01-30' },
    eventType: 'birthday',
    recurrence: ["RRULE:FREQ=YEARLY"],
    summary: "My friend's birthday",
    transparency: "transparent",
    visibility: "private",
  }
  createEvent(event);
}

/**
  * Creates a Calendar event.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/insert
  */
function createEvent(event) {

  try {
    var response = Calendar.Events.insert(event, CALENDAR_ID);
    console.log(response);
  } catch (exception) {
    console.log(exception.message);
  }
}

מחליפים את מה שכתוב בשדות הבאים:

CALENDAR_ID: כתובת האימייל של היומן שממנו יאוחזרו אירועים ובו ייווצרו אירועים. הקבוע הזה מוגדר בהתחלה לערך 'primary', שהוא מילת מפתח לגישה ליומן הראשי של המשתמש המחובר. שינוי הערך הזה מאפשר לכם לקרוא אירועים ביומנים של משתמשים אחרים שיש לכם גישה אליהם.
‫EVENT_ID: מזהה האירוע. אפשר להתקשר אל events.list כדי לאחזר מזהי אירועים.

הרצת דוגמת הקוד

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