דף זה תורגם על ידי 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 תומך ב-methods‏ 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 באמצעות ה-methods‏ 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.
בחלונית הימנית, ליד שירותים, לוחצים על סמל הוספת השירות .
בוחרים באפשרות Google Calendar API ולוחצים על הוספה.
אחרי ההפעלה, ה-API יופיע בחלונית הימנית. אפשר להשתמש במילת המפתח Calendar בעורך כדי לראות את השיטות והמחלקות שזמינות ב-API.

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

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