Tworzenie zdarzeń

Wyobraź sobie aplikację, która pomaga użytkownikom znajdować najlepsze szlaki piesze. Dodanie planu wycieczki jako wydarzenia w kalendarzu znacznie ułatwia użytkownikom automatyczne porządkowanie ich. Kalendarz Google pomaga im dzielić się planem i przypomina im o nim, by mogły się bez stresu przygotować. Płynna integracja z usługami Google informuje ich również o tym, kiedy należy wyjść, a Mapy Google wskazują im na czas miejsce spotkania.

Z tego artykułu dowiesz się, jak tworzyć wydarzenia w kalendarzach i dodawać je do kalendarzy użytkowników.

Dodaj wydarzenie

Aby utworzyć zdarzenie, wywołaj metodę events.insert(), podając co najmniej te parametry:

  • calendarId to identyfikator kalendarza, który może być adresem e-mail kalendarza, w którym ma zostać utworzone wydarzenie, albo specjalnym słowem kluczowym 'primary' oznaczającym kalendarz główny zalogowanego użytkownika. Jeśli nie znasz adresu e-mail kalendarza, którego chcesz użyć, możesz go sprawdzić w ustawieniach kalendarza w internetowym interfejsie Kalendarza Google (w sekcji „Adres kalendarza”) lub wyszukać go w wyniku wywołania calendarList.list().
  • event to zdarzenie do utworzenia ze wszystkimi niezbędnymi informacjami, takimi jak początek i koniec. Jedyne 2 wymagane pola to start i end razy. Pełen zestaw pól zdarzenia znajdziesz w dokumentacji event.

Aby tworzyć zdarzenia:

  • Ustaw zakres protokołu OAuth na https://www.googleapis.com/auth/calendar, aby mieć uprawnienia do edycji kalendarza użytkownika.
  • Upewnij się, że uwierzytelniony użytkownik ma uprawnienia do zapisu w kalendarzu przy użyciu podanej przez Ciebie wartości calendarId (np. wywołując calendarList.get() w przypadku elementu calendarId i sprawdzając accessRole).

Dodawanie metadanych zdarzenia

Podczas tworzenia wydarzenia w kalendarzu możesz opcjonalnie dodać metadane wydarzenia. Jeśli zdecydujesz się nie dodawać metadanych podczas tworzenia, możesz zaktualizować wiele pól za pomocą events.update(). Jednak niektóre pola, takie jak identyfikator wydarzenia, można skonfigurować tylko w ramach operacji events.insert().

Lokalizacja

Dodanie adresu w polu lokalizacji pozwala korzystać z takich funkcji jak

„godzina wyjazdu” lub wyświetlanie mapy z trasą dojazdu.

Identyfikator wydarzenia

Podczas tworzenia wydarzenia możesz wygenerować własny identyfikator wydarzenia.

który jest zgodny z naszymi wymaganiami dotyczącymi formatu. Dzięki temu możesz synchronizować elementy w lokalnej bazie danych ze wydarzeniami w Kalendarzu Google. Zapobiega to również duplikowaniu wydarzeń, jeśli operacja zakończy się niepowodzeniem po udanym wykonaniu jej w backendzie Kalendarza. Jeśli nie podasz identyfikatora zdarzenia, serwer go wygeneruje. Więcej informacji znajdziesz w dokumentacji identyfikatora zdarzenia.

Uczestnicy

Wydarzenie, które utworzysz, będzie wyświetlane we wszystkich głównych kalendarzach Google

uczestników z tym samym identyfikatorem wydarzenia. Jeśli w prośbie o wstawienie ustawisz wartość sendNotifications na true, uczestnicy otrzymają też e-maila z powiadomieniem o wydarzeniu. Więcej informacji znajdziesz w przewodniku dotyczącym wydarzeń z wieloma uczestnikami.

Poniższe przykłady pokazują tworzenie zdarzenia i ustawianie jego metadanych:

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

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

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

Dodawanie załączników z Dysku do wydarzeń

Do wydarzeń w kalendarzu możesz dołączać pliki z Dysku Google, np. notatki ze spotkań w Dokumentach, budżety w Arkuszach, prezentacje w Prezentacjach i inne odpowiednie pliki na Dysku Google. Załącznik możesz dodać podczas tworzenia wydarzenia za pomocą narzędzia events.insert() lub później w ramach aktualizacji, np. przy użyciu events.patch().

Dwie etapy dołączania pliku z Dysku Google do wydarzenia to:

  1. Pobierz adres URL pliku alternateLink, title i mimeType z zasobu Pliki interfejsu Drive API. Zwykle odbywa się to za pomocą metody files.get().
  2. Utwórz lub zaktualizuj zdarzenie, podając pola attachments w treści żądania, a parametr supportsAttachments ustawiony na true.

Poniższy przykładowy kod pokazuje, jak zaktualizować istniejące zdarzenie, aby dodać załącznik:

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()

Dodawanie rozmów wideo i rozmów telefonicznych do wydarzeń

Wydarzenia możesz powiązać z rozmowami w Hangouts i Google Meet, aby użytkownicy mogli odbywać spotkania zdalne przez telefon lub rozmowę wideo.

Pola conferenceData można używać do odczytywania, kopiowania i usuwania szczegółów istniejących rozmów wideo. Można w nim też prosić o wygenerowanie nowych rozmów wideo. Aby umożliwić tworzenie i modyfikowanie szczegółów rozmowy wideo, ustaw parametr żądania conferenceDataVersion na 1.

Obecnie obsługiwane są 3 typy właściwości conferenceData, które są oznaczone tagiem conferenceData.conferenceSolution.key.type:

  1. Hangouts dla klientów indywidualnych (eventHangout)
  2. Klasyczna wersja Hangouts dla Google Workspace użytkowników (wycofana; eventNamedHangout)
  3. Google Meet (hangoutsMeet)

Aby dowiedzieć się, który typ rozmowy wideo jest obsługiwany w danych kalendarzach danego użytkownika, przejrzyj conferenceProperties.allowedConferenceSolutionTypes w kolekcjach calendars i calendarList. Możesz też sprawdzić, czy użytkownik woli tworzyć Hangouts dla wszystkich nowo utworzonych wydarzeń. W tym celu sprawdź ustawienie autoAddHangouts w kolekcji settings.

Oprócz pola type conferenceSolution udostępnia też pola name i iconUri, które umożliwiają zaprezentowanie rozwiązania do obsługi konferencji w sposób przedstawiony poniżej:

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

Możesz utworzyć nową konferencję dla wydarzenia, przypisując createRequest do nowo wygenerowanego elementu requestId, który może być losowym elementem string. Konferencje są tworzone asynchronicznie, ale zawsze możesz sprawdzić stan prośby, aby poinformować użytkowników, co się dzieje.

Aby na przykład poprosić o wygenerowanie rozmowy wideo dla istniejącego wydarzenia:

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

Szybka odpowiedź na to wywołanie może jeszcze nie zawierać w pełni wypełnionego pola conferenceData. Wskazuje na to kod stanu pending w polu stan. Po uzupełnieniu informacji o konferencji kod stanu zmieni się na success. Pole entryPoints zawiera informacje o identyfikatorach URI filmów i numerów telefonów, pod którymi użytkownicy mogą dołączać przez telefon.

Jeśli chcesz zaplanować wiele wydarzeń w Kalendarzu z tymi samymi szczegółami rozmowy wideo, możesz skopiować cały conferenceData z jednego wydarzenia do drugiego.

Kopiowanie jest przydatne w niektórych sytuacjach. Załóżmy na przykład, że opracowujesz aplikację rekrutacyjną, w której są konfigurowane osobne wydarzenia dla kandydata i osoby przeprowadzającej rozmowę. Chcesz chronić tożsamość osoby prowadzącej rozmowę, ale chcesz mieć pewność, że wszyscy uczestnicy będą uczestniczyć w tym samym połączeniu konferencyjnym.