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

סוגי אירועים.

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

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

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

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

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

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

במאמר יצירת אירועים מוסבר איך מתחילים לעבוד עם אירועים ביומן Google.

יום הולדת

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

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

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

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

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

ה-API מאפשר ליצור אירועי יום הולדת באמצעות השיטה 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 של אירועי יום הולדת באמצעות השיטות update ו-patch. אפשר גם לעדכן את השדות start ו-end כדי לשנות את תאריך האירוע. במקרה כזה, הערכים החדשים צריכים להגדיר אירוע של יום שלם שנמשך יום אחד בדיוק. אי אפשר לעדכן את פרטי התזמון של אירוע יום הולדת אם האירוע מקושר לcontact, או אם הערך של type הוא 'self'.

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

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

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

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

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

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

אירועים מ-Gmail

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

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

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

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

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

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

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

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

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

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

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

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

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

יצירת הסקריפט והגדרתו

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

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

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

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

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