Создать события

Представьте себе приложение, которое помогает пользователям находить лучшие маршруты для пеших прогулок. Добавив план похода в календарь, пользователи автоматически получают значительную помощь в организации своего времени. 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" , соответствующие участники получат уведомление по электронной почте о вашем мероприятии. Подробнее см. в разделе «Мероприятия с несколькими участниками» .

В следующих примерах демонстрируется создание события и настройка его метаданных:

Идти

// 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:"[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)

Ява

// 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("[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/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': '[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/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': '[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);

Питон

# 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': '[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'))

Руби

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}"

Добавляйте вложения Диска к событиям

Вы можете прикреплять файлы Google Диска , например, заметки о встречах в Документах, бюджеты в Таблицах, презентации в Презентациях или любые другие соответствующие файлы Google Диска, к мероприятиям в вашем календаре. Вы можете добавить вложение при создании мероприятия с помощью events.insert() или позже, в рамках обновления, например, с помощью events.patch()

Прикрепление файла Google Диска к событию состоит из двух этапов:

1. Получите URL-адрес, title и mimeType alternateLink из ресурса Drive API Files , обычно с помощью метода files.get() .
2. Создайте или обновите событие с полями attachments , заданными в теле запроса, и параметром supportsAttachments , имеющим значение true .

В следующем примере кода показано, как обновить существующее событие для добавления вложения:

Ява

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
  ));
}

Питон

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

Немедленный ответ на этот вызов может ещё не содержать полностью заполненных conferenceData ; на это указывает код статуса pending в поле статуса . После заполнения информации о конференции код статуса меняется на success . Поле entryPoints содержит информацию о том, какие URI видео и телефона доступны вашим пользователям для подключения.

Если вы хотите запланировать несколько событий в календаре с одинаковыми данными о конференции, вы можете скопировать все conferenceData из одного события в другое.

Копирование полезно в определённых ситуациях. Например, предположим, что вы разрабатываете приложение для рекрутинга, которое организует отдельные мероприятия для кандидата и интервьюера. Вы хотите защитить личность интервьюера, но при этом убедиться, что все участники подключаются к одной и той же конференц-связи.

Важно: При добавлении поддержки конференций в существующее приложение, хранящее события локально, необходимо выполнить полную синхронизацию всех мероприятий, прежде чем включать поддержку данных конференций (установив параметр запроса conferenceDataVersion равным 1 для изменения событий). Если вы не выполните предварительную синхронизацию, вы можете случайно удалить существующие конференции из событий пользователей.