Creare eventi

Immagina un'app che aiuta gli utenti a trovare i migliori percorsi escursionistici. Aggiungendo il piano dell'escursionismo come evento di calendario, gli utenti ricevono molto aiuto per organizzarsi in modo automatico. Google Calendar li aiuta a condividere il piano e lo ricorda perché possono prepararsi senza stress. Inoltre, grazie all'integrazione perfetta dei prodotti Google, Google Now avvisa in tempo reale sull'orario di partenza e Google Maps li indirizza in tempo al punto di incontro.

Questo articolo spiega come creare eventi di calendario e aggiungerli ai calendari degli utenti.

Aggiungi un evento

Per creare un evento, chiama il metodo events.insert() che fornisce almeno questi parametri:

• calendarId è l'identificatore del calendario e può essere l'indirizzo email del calendario in cui creare l'evento o una parola chiave speciale 'primary' che utilizzerà il calendario principale dell'utente che ha eseguito l'accesso. Se non conosci l'indirizzo email del calendario da utilizzare, puoi controllarlo nelle impostazioni del calendario dell'interfaccia utente web di Google Calendar (nella sezione "Indirizzo calendario") oppure nel risultato della chiamata a calendarList.list().
• event è l'evento da creare con tutti i dettagli necessari come inizio e fine. Gli unici due campi obbligatori sono il valore start e end volte. Consulta la documentazione di riferimento event per l'insieme completo dei campi evento.
  Specifica gli eventi a tempo utilizzando i campi start.dateTime e end.dateTime. Per gli eventi che durano tutto il giorno, usa invece start.date e end.date.

Per creare correttamente eventi, devi:

• Imposta l'ambito OAuth su https://www.googleapis.com/auth/calendar in modo da avere accesso in modifica al calendario dell'utente.
• Assicurati che l'utente autenticato abbia accesso in scrittura al calendario con il calendarId che hai fornito (ad esempio chiamando calendarList.get() per calendarId e controllando accessRole).

Aggiungi metadati dell'evento

Se vuoi, puoi aggiungere i metadati degli eventi quando crei un evento nel calendario. Se scegli di non aggiungere metadati durante la creazione, puoi aggiornare molti campi utilizzando events.update(). Tuttavia, alcuni campi, ad esempio l'ID evento, possono essere impostati solo durante un'operazione events.insert().

Località

L'aggiunta di un indirizzo nel campo della località abilita funzionalità quali

"al momento della partenza" o la visualizzazione di una mappa con le indicazioni stradali.

ID evento

Quando crei un evento, puoi scegliere di generare il tuo ID evento

conforme ai nostri requisiti di formato. Ciò consente di mantenere sincronizzate le entità nel database locale con gli eventi di Google Calendar. Impedisce inoltre la creazione di eventi duplicati se l'operazione non riesce a un certo punto dopo la sua esecuzione nel backend di Calendar. Se non viene fornito alcun ID evento, il server ne genera uno. Consulta il riferimento su ID evento per ulteriori informazioni.

Partecipanti

L'evento che crei viene visualizzato in tutti i calendari Google principali di

i partecipanti che hai incluso con lo stesso ID evento. Se imposti sendNotifications su true nella richiesta di inserimento, i partecipanti riceveranno anche una notifica via email per l'evento. Per ulteriori informazioni, consulta la guida relativa agli eventi con più partecipanti.

I seguenti esempi mostrano la creazione di un evento e l'impostazione dei relativi metadati:

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

Aggiungere allegati di Drive agli eventi

Puoi allegare agli eventi del calendario file di Google Drive, ad esempio note sulla riunione in Documenti, budget in Fogli, presentazioni in Presentazioni o qualsiasi altro file di Google Drive pertinente. Puoi aggiungere l'allegato quando crei un evento con events.insert() o versioni successive come parte di un aggiornamento, ad esempio con events.patch()

Le due parti per allegare un file di Google Drive a un evento sono:

1. Recupera l'URL alternateLink del file, title e mimeType dalla risorsa File dell'API Drive, in genere con il metodo files.get().
2. Crea o aggiorna un evento con i campi attachments impostati nel corpo della richiesta e il parametro supportsAttachments impostato su true.

Il seguente esempio di codice mostra come aggiornare un evento esistente per aggiungere un collegamento:

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

Importante: devi eseguire una sincronizzazione completa di tutti gli eventi prima di attivare il parametro supportsAttachments per le modifiche degli eventi quando aggiungi il supporto per gli allegati nell'app esistente che archivia gli eventi localmente. Se non esegui prima una sincronizzazione, potresti inavvertitamente rimuovere gli allegati esistenti dagli eventi dell'utente.

Aggiungere videoconferenze e conferenze telefoniche agli eventi

Puoi associare eventi alle conferenze di Hangouts e Google Meet per consentire agli utenti di incontrarsi da remoto con una telefonata o una videochiamata.

Il campo conferenceData può essere utilizzato per leggere, copiare e cancellare i dettagli delle conferenze esistenti e anche per richiedere la generazione di nuove conferenze. Per consentire la creazione e la modifica dei dettagli delle conferenze, imposta il parametro di richiesta conferenceDataVersion su 1.

Attualmente sono supportati tre tipi di conferenceData, come indicato in conferenceData.conferenceSolution.key.type:

1. Hangouts per i consumatori (eventHangout)
2. Versione classica di Hangouts per gli utenti Google Workspace (deprecata; eventNamedHangout)
3. Google Meet (hangoutsMeet)

Puoi scoprire quale tipo di conferenza è supportato per ogni calendario di un utente osservando conferenceProperties.allowedConferenceSolutionTypes nelle raccolte calendars e calendarList. Puoi anche scoprire se l'utente preferisce che gli Hangout vengano creati per tutti i nuovi eventi selezionando l'impostazione autoAddHangouts nella raccolta settings.

Oltre a type, conferenceSolution fornisce anche i campi name e iconUri che puoi utilizzare per rappresentare la soluzione per conferenze, come mostrato di seguito:

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

Puoi creare una nuova conferenza per un evento fornendo un createRequest con un requestId appena generato, che può essere un string casuale. Le conferenze vengono create in modo asincrono, ma puoi sempre controllare lo stato della tua richiesta per comunicare agli utenti cosa sta succedendo.

Ad esempio, per richiedere la generazione di una conferenza per un evento esistente:

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

La risposta immediata a questa chiamata potrebbe non contenere ancora il valore conferenceData completamente compilato. Ciò è indicato da un codice di stato pending nel campo status. Il codice di stato diventa success dopo aver inserito le informazioni sulla conferenza. Il campo entryPoints contiene informazioni sugli URI video e telefonici disponibili per consentire agli utenti di connettersi via telefono.

Se vuoi pianificare più eventi di Calendar con gli stessi dettagli della conferenza, puoi copiare l'intero conferenceData da un evento all'altro.

La copia è utile in determinate situazioni. Ad esempio, supponiamo che tu stia sviluppando una candidatura che prevede l'organizzazione di eventi separati per il candidato e l'intervistatore. Vuoi proteggere l'identità dell'intervistatore, ma vuoi anche assicurarti che tutti i partecipanti partecipino alla stessa audioconferenza.

Importante: devi eseguire una sincronizzazione completa di tutti gli eventi prima di attivare il supporto dei dati relativi alle conferenze (impostando il parametro di richiesta conferenceDataVersion su 1 per le modifiche degli eventi) quando aggiungi il supporto per le conferenze nell'app esistente che archivia gli eventi localmente. Se prima non esegui una sincronizzazione, potresti inavvertitamente rimuovere le conferenze esistenti dagli eventi degli utenti.