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

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

מיקום

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

"time to left" (זמן לצאת) או הצגת מפה עם המסלול.

מזהה אירוע

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

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

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

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

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