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

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

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

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

Go

// Refer to the Go quickstart on how to setup the environment:
// https://developers.google.com/workspace/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:"lpage@example.com"},
    &calendar.EventAttendee{Email:"sbrin@example.com"},
  },
}

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/workspace/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("lpage@example.com"),
    new EventAttendee().setEmail("sbrin@example.com"),
};
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/workspace/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': 'lpage@example.com'},
    {'email': 'sbrin@example.com'}
  ],
  '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/workspace/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': 'lpage@example.com'},
    {'email': 'sbrin@example.com'},
  ],
  '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' => 'lpage@example.com'),
    array('email' => 'sbrin@example.com'),
  ),
  '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/workspace/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': 'lpage@example.com'},
    {'email': 'sbrin@example.com'},
  ],
  '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: 'lpage@example.com'
    ),
    Google::Apis::CalendarV3::EventAttendee.new(
      email: 'sbrin@example.com'
    )
  ],
  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 לאירוע כולל שני חלקים:

מקבלים את כתובת ה-URL של הקובץ alternateLink, title ו-mimeType מ משאב הקבצים של Drive API, בדרך כלל באמצעות המתודה files.get().
יוצרים או מעדכנים אירוע עם השדות 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()

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

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

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

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

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

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

בנוסף ל-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,
  sendUpdates: "all",
  conferenceDataVersion: 1
}).execute(function(event) {
  console.log("Conference created for event: %s", event.htmlLink);
});

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

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

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

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

הוספת אירוע

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

Go

Java

JavaScript

Node.js

PHP

Python

Ruby

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

Java

PHP

Python

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

JavaScript

JavaScript

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