יצירת אירועים

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

במאמר הזה נסביר איך ליצור אירועים ביומן ולהוסיף אותם ליומני המשתמשים.

הוספת אירוע

כדי ליצור אירוע, צריך להפעיל את השיטה events.insert() ולציין לפחות את הפרמטרים הבאים:

• calendarId הוא מזהה היומן, והוא יכול להיות כתובת האימייל של היומן שבו רוצים ליצור את האירוע או מילת מפתח מיוחדת 'primary' שבה יופעל היומן הראשי של המשתמש שמחובר לחשבון. אם אתם לא יודעים מהי כתובת האימייל של היומן שבו אתם רוצים להשתמש, תוכלו לבדוק אותה בהגדרות של היומן בממשק המשתמש באינטרנט של יומן Google (בקטע 'כתובת היומן') או לחפש אותה בתוצאה של הקריאה calendarList.list().
• event הוא האירוע שיצרתם עם כל הפרטים הנדרשים, כמו התחלה וסיום. שני השדות היחידים שצריך למלא הם השעות start ו-end. בחומר העזר בנושא event מפורטת הקבוצה המלאה של שדות האירוע.
  מציינים אירועים מתוזמנים באמצעות השדות start.dateTime ו-end.dateTime. באירועים של יום שלם, צריך להשתמש במקום זאת ב-start.date וב-end.date.

כדי ליצור אירועים, צריך:

• מגדירים את היקף הרשאת ה-OAuth ל-https://www.googleapis.com/auth/calendar כדי שתהיה לכם גישה לעריכת היומן של המשתמש.
• מוודאים שלמשתמש המאומת יש הרשאת כתיבה ביומן באמצעות calendarId שסיפקתם (לדוגמה, על ידי קריאה ל-calendarList.get() עבור calendarId ובדיקה של accessRole).

הוספת מטא-נתונים של אירועים

אפשר להוסיף מטא-נתונים של אירועים כשיוצרים אירועים ביומן. אם בוחרים לא להוסיף מטא-נתונים במהלך היצירה, אפשר לעדכן שדות רבים באמצעות הפונקציה events.update(). עם זאת, שדות מסוימים, כמו מזהה האירוע, אפשר להגדיר רק במהלך פעולה של events.insert().

מיקום

הוספת כתובת לשדה המיקום מאפשרת תכונות כמו

'זמן לצאת' או הצגת מפה עם המסלול.

מזהה אירוע

כשיוצרים אירוע, אפשר ליצור מזהה אירוע משלכם

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

משתתפים

האירוע שתיצרו יופיע בכל היומנים הראשיים ביומן Google של

המשתתפים שכללתם עם אותו מזהה אירוע. אם תגדירו את הערך של sendNotifications ל-true בבקשת ההוספה, המשתתפים יקבלו גם התראה באימייל על האירוע. מידע נוסף זמין במדריך בנושא אירועים עם מספר משתתפים.

בדוגמאות הבאות מוסבר איך יוצרים אירוע ומגדירים את המטא-נתונים שלו:

Go

// Refer to the Go quickstart on how to setup the environment:
// https://developers.google.com/calendar/quickstart/go
// Change the scope to calendar.CalendarScope and delete any stored credentials.

event := &calendar.Event{
  Summary: "Google I/O 2015",
  Location: "800 Howard St., San Francisco, CA 94103",
  Description: "A chance to hear more about Google's developer products.",
  Start: &calendar.EventDateTime{
    DateTime: "2015-05-28T09:00:00-07:00",
    TimeZone: "America/Los_Angeles",
  },
  End: &calendar.EventDateTime{
    DateTime: "2015-05-28T17:00:00-07:00",
    TimeZone: "America/Los_Angeles",
  },
  Recurrence: []string{"RRULE:FREQ=DAILY;COUNT=2"},
  Attendees: []*calendar.EventAttendee{
    &calendar.EventAttendee{Email:"[e-mail]"},
    &calendar.EventAttendee{Email:"[e-mail]"},
  },
}

calendarId := "primary"
event, err = srv.Events.Insert(calendarId, event).Do()
if err != nil {
  log.Fatalf("Unable to create event. %v\n", err)
}
fmt.Printf("Event created: %s\n", event.HtmlLink)

Java

// Refer to the Java quickstart on how to setup the environment:
// https://developers.google.com/calendar/quickstart/java
// Change the scope to CalendarScopes.CALENDAR and delete any stored
// credentials.

Event event = new Event()
    .setSummary("Google I/O 2015")
    .setLocation("800 Howard St., San Francisco, CA 94103")
    .setDescription("A chance to hear more about Google's developer products.");

DateTime startDateTime = new DateTime("2015-05-28T09:00:00-07:00");
EventDateTime start = new EventDateTime()
    .setDateTime(startDateTime)
    .setTimeZone("America/Los_Angeles");
event.setStart(start);

DateTime endDateTime = new DateTime("2015-05-28T17:00:00-07:00");
EventDateTime end = new EventDateTime()
    .setDateTime(endDateTime)
    .setTimeZone("America/Los_Angeles");
event.setEnd(end);

String[] recurrence = new String[] {"RRULE:FREQ=DAILY;COUNT=2"};
event.setRecurrence(Arrays.asList(recurrence));

EventAttendee[] attendees = new EventAttendee[] {
    new EventAttendee().setEmail("[e-mail]"),
    new EventAttendee().setEmail("[e-mail]"),
};
event.setAttendees(Arrays.asList(attendees));

EventReminder[] reminderOverrides = new EventReminder[] {
    new EventReminder().setMethod("email").setMinutes(24 * 60),
    new EventReminder().setMethod("popup").setMinutes(10),
};
Event.Reminders reminders = new Event.Reminders()
    .setUseDefault(false)
    .setOverrides(Arrays.asList(reminderOverrides));
event.setReminders(reminders);

String calendarId = "primary";
event = service.events().insert(calendarId, event).execute();
System.out.printf("Event created: %s\n", event.getHtmlLink());

JavaScript

// Refer to the JavaScript quickstart on how to setup the environment:
// https://developers.google.com/calendar/quickstart/js
// Change the scope to 'https://www.googleapis.com/auth/calendar' and delete any
// stored credentials.

const event = {
  'summary': 'Google I/O 2015',
  'location': '800 Howard St., San Francisco, CA 94103',
  'description': 'A chance to hear more about Google\'s developer products.',
  'start': {
    'dateTime': '2015-05-28T09:00:00-07:00',
    'timeZone': 'America/Los_Angeles'
  },
  'end': {
    'dateTime': '2015-05-28T17:00:00-07:00',
    'timeZone': 'America/Los_Angeles'
  },
  'recurrence': [
    'RRULE:FREQ=DAILY;COUNT=2'
  ],
  'attendees': [
    {'email': '[e-mail]'},
    {'email': '[e-mail]'}
  ],
  'reminders': {
    'useDefault': false,
    'overrides': [
      {'method': 'email', 'minutes': 24 * 60},
      {'method': 'popup', 'minutes': 10}
    ]
  }
};

const request = gapi.client.calendar.events.insert({
  'calendarId': 'primary',
  'resource': event
});

request.execute(function(event) {
  appendPre('Event created: ' + event.htmlLink);
});

Node.js

// Refer to the Node.js quickstart on how to setup the environment:
// https://developers.google.com/calendar/quickstart/node
// Change the scope to 'https://www.googleapis.com/auth/calendar' and delete any
// stored credentials.

const event = {
  'summary': 'Google I/O 2015',
  'location': '800 Howard St., San Francisco, CA 94103',
  'description': 'A chance to hear more about Google\'s developer products.',
  'start': {
    'dateTime': '2015-05-28T09:00:00-07:00',
    'timeZone': 'America/Los_Angeles',
  },
  'end': {
    'dateTime': '2015-05-28T17:00:00-07:00',
    'timeZone': 'America/Los_Angeles',
  },
  'recurrence': [
    'RRULE:FREQ=DAILY;COUNT=2'
  ],
  'attendees': [
    {'email': '[e-mail]'},
    {'email': '[e-mail]'},
  ],
  'reminders': {
    'useDefault': false,
    'overrides': [
      {'method': 'email', 'minutes': 24 * 60},
      {'method': 'popup', 'minutes': 10},
    ],
  },
};

calendar.events.insert({
  auth: auth,
  calendarId: 'primary',
  resource: event,
}, function(err, event) {
  if (err) {
    console.log('There was an error contacting the Calendar service: ' + err);
    return;
  }
  console.log('Event created: %s', event.htmlLink);
});

PHP

$event = new Google_Service_Calendar_Event(array(
  'summary' => 'Google I/O 2015',
  'location' => '800 Howard St., San Francisco, CA 94103',
  'description' => 'A chance to hear more about Google\'s developer products.',
  'start' => array(
    'dateTime' => '2015-05-28T09:00:00-07:00',
    'timeZone' => 'America/Los_Angeles',
  ),
  'end' => array(
    'dateTime' => '2015-05-28T17:00:00-07:00',
    'timeZone' => 'America/Los_Angeles',
  ),
  'recurrence' => array(
    'RRULE:FREQ=DAILY;COUNT=2'
  ),
  'attendees' => array(
    array('email' => '[e-mail]'),
    array('email' => '[e-mail]'),
  ),
  'reminders' => array(
    'useDefault' => FALSE,
    'overrides' => array(
      array('method' => 'email', 'minutes' => 24 * 60),
      array('method' => 'popup', 'minutes' => 10),
    ),
  ),
));

$calendarId = 'primary';
$event = $service->events->insert($calendarId, $event);
printf('Event created: %s\n', $event->htmlLink);

Python

# Refer to the Python quickstart on how to setup the environment:
# https://developers.google.com/calendar/quickstart/python
# Change the scope to 'https://www.googleapis.com/auth/calendar' and delete any
# stored credentials.

event = {
  'summary': 'Google I/O 2015',
  'location': '800 Howard St., San Francisco, CA 94103',
  'description': 'A chance to hear more about Google\'s developer products.',
  'start': {
    'dateTime': '2015-05-28T09:00:00-07:00',
    'timeZone': 'America/Los_Angeles',
  },
  'end': {
    'dateTime': '2015-05-28T17:00:00-07:00',
    'timeZone': 'America/Los_Angeles',
  },
  'recurrence': [
    'RRULE:FREQ=DAILY;COUNT=2'
  ],
  'attendees': [
    {'email': '[e-mail]'},
    {'email': '[e-mail]'},
  ],
  'reminders': {
    'useDefault': False,
    'overrides': [
      {'method': 'email', 'minutes': 24 * 60},
      {'method': 'popup', 'minutes': 10},
    ],
  },
}

event = service.events().insert(calendarId='primary', body=event).execute()
print 'Event created: %s' % (event.get('htmlLink'))

Ruby

event = Google::Apis::CalendarV3::Event.new(
  summary: 'Google I/O 2015',
  location: '800 Howard St., San Francisco, CA 94103',
  description: 'A chance to hear more about Google\'s developer products.',
  start: Google::Apis::CalendarV3::EventDateTime.new(
    date_time: '2015-05-28T09:00:00-07:00',
    time_zone: 'America/Los_Angeles'
  ),
  end: Google::Apis::CalendarV3::EventDateTime.new(
    date_time: '2015-05-28T17:00:00-07:00',
    time_zone: 'America/Los_Angeles'
  ),
  recurrence: [
    'RRULE:FREQ=DAILY;COUNT=2'
  ],
  attendees: [
    Google::Apis::CalendarV3::EventAttendee.new(
      email: '[e-mail]'
    ),
    Google::Apis::CalendarV3::EventAttendee.new(
      email: '[e-mail]'
    )
  ],
  reminders: Google::Apis::CalendarV3::Event::Reminders.new(
    use_default: false,
    overrides: [
      Google::Apis::CalendarV3::EventReminder.new(
        reminder_method: 'email',
        minutes: 24 * 60
      ),
      Google::Apis::CalendarV3::EventReminder.new(
        reminder_method: 'popup',
        minutes: 10
      )
    ]
  )
)

result = client.insert_event('primary', event)
puts "Event created: #{result.html_link}"

הוספת קבצים מ-Drive לאירועים

אתם יכולים לצרף לאירועים ביומן קבצים מ-Google Drive, כמו פתקים של פגישות ב-Docs, תקציבים ב-Sheets, מצגות ב-Slides או כל קובץ רלוונטי אחר מ-Google Drive. אפשר להוסיף את הקובץ כשיוצרים אירוע באמצעות events.insert(), או מאוחר יותר כחלק מעדכון, למשל באמצעות events.patch().

יש שני חלקים לצרוף קובץ מ-Google Drive לאירוע:

1. מקבלים את כתובות ה-URL של הקובץ alternateLink,‏ title ו-mimeType מ משאב הקבצים של Drive API, בדרך כלל באמצעות השיטה files.get().
2. יוצרים או מעדכנים אירוע עם השדות attachments שמוגדרים בגוף הבקשה, והפרמטר supportsAttachments מוגדר לערך true.

דוגמת הקוד הבאה מראה איך לעדכן אירוע קיים כדי להוסיף לו קובץ מצורף:

Java

public static void addAttachment(Calendar calendarService, Drive driveService, String calendarId,
    String eventId, String fileId) throws IOException {
  File file = driveService.files().get(fileId).execute();
  Event event = calendarService.events().get(calendarId, eventId).execute();

  List<EventAttachment> attachments = event.getAttachments();
  if (attachments == null) {
    attachments = new ArrayList<EventAttachment>();
  }
  attachments.add(new EventAttachment()
      .setFileUrl(file.getAlternateLink())
      .setMimeType(file.getMimeType())
      .setTitle(file.getTitle()));

  Event changes = new Event()
      .setAttachments(attachments);
  calendarService.events().patch(calendarId, eventId, changes)
      .setSupportsAttachments(true)
      .execute();
}

PHP

function addAttachment($calendarService, $driveService, $calendarId, $eventId, $fileId) {
  $file = $driveService->files->get($fileId);
  $event = $calendarService->events->get($calendarId, $eventId);
  $attachments = $event->attachments;

  $attachments[] = array(
    'fileUrl' => $file->alternateLink,
    'mimeType' => $file->mimeType,
    'title' => $file->title
  );
  $changes = new Google_Service_Calendar_Event(array(
    'attachments' => $attachments
  ));

  $calendarService->events->patch($calendarId, $eventId, $changes, array(
    'supportsAttachments' => TRUE
  ));
}

Python

def add_attachment(calendarService, driveService, calendarId, eventId, fileId):
    file = driveService.files().get(fileId=fileId).execute()
    event = calendarService.events().get(calendarId=calendarId,
                                         eventId=eventId).execute()

    attachments = event.get('attachments', [])
    attachments.append({
        'fileUrl': file['alternateLink'],
        'mimeType': file['mimeType'],
        'title': file['title']
    })

    changes = {
        'attachments': attachments
    }
    calendarService.events().patch(calendarId=calendarId, eventId=eventId,
                                   body=changes,
                                   supportsAttachments=True).execute()

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

הוספת שיחות ועידה בווידאו ובטלפון לאירועים

אתם יכולים לשייך אירועים לשיחות ועידה ב-Hangouts וב-Google Meet כדי לאפשר למשתמשים לקיים פגישות מרחוק באמצעות שיחת טלפון או שיחת וידאו.

אפשר להשתמש בשדה conferenceData כדי לקרוא, להעתיק ולמחוק פרטים של כנסים קיימים, וגם כדי לבקש יצירת כנסים חדשים. כדי לאפשר יצירה ושינוי של פרטי הועידה, מגדירים את הפרמטר conferenceDataVersion בבקשה לערך 1.

יש כרגע תמיכה בשלושה סוגים של conferenceData, כפי שמצוין ב-conferenceData.conferenceSolution.key.type:

1. Hangouts לצרכנים (eventHangout)
2. הגרסה הקלאסית של Hangouts למשתמשים Google Workspace (הוצאה משימוש; eventNamedHangout)
3. Google Meet‏ (hangoutsMeet)

כדי לבדוק אילו סוגי כנסים נתמכים ביומן של משתמש מסוים, אפשר לעיין בערך conferenceProperties.allowedConferenceSolutionTypes באוספים calendars ו-calendarList. אפשר גם לבדוק אם המשתמש מעדיף שייווצרו שיחות Hangouts לכל האירועים החדשים שייווצרו על ידו. לשם כך, בודקים את ההגדרה autoAddHangouts באוסף settings.

בנוסף ל-type, השדה conferenceSolution מספק גם את השדות name ו-iconUri, שבהם אפשר להשתמש כדי לייצג את פתרון הווידאו, כפי שמתואר בהמשך:

JavaScript

const solution = event.conferenceData.conferenceSolution;

const content = document.getElementById("content");
const text = document.createTextNode("Join " + solution.name);
const icon = document.createElement("img");
icon.src = solution.iconUri;

content.appendChild(icon);
content.appendChild(text);

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

לדוגמה, כדי לבקש יצירת כנס לאירוע קיים:

JavaScript

const eventPatch = {
  conferenceData: {
    createRequest: {requestId: "7qxalsvy0e"}
  }
};

gapi.client.calendar.events.patch({
  calendarId: "primary",
  eventId: "7cbh8rpc10lrc0ckih9tafss99",
  resource: eventPatch,
  sendNotifications: true,
  conferenceDataVersion: 1
}).execute(function(event) {
  console.log("Conference created for event: %s", event.htmlLink);
});

יכול להיות שהתגובה המיידית לשיחה הזו עדיין לא תכלול את השדה conferenceData שמאוכלס במלואו. במקרה כזה, יופיע קוד הסטטוס pending בשדה status. קוד הסטטוס ישתנה ל-success אחרי שפרטי הכנס יאוכלסו. השדה entryPoints מכיל מידע על מזהי URI של וידאו וטלפון שזמינים למשתמשים כדי להתקשר.

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

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

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