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

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