Creazione eventi

Immagina un'app che aiuti gli utenti a trovare i migliori percorsi di trekking. Aggiungendo il piano di trekking come evento del calendario, gli utenti ricevono un grande aiuto per rimanere organizzati automaticamente. Google Calendar li aiuta a condividere il piano e invia loro promemoria in modo che possano prepararsi senza stress. Inoltre, grazie all'integrazione perfetta dei prodotti Google, Google Now invia loro un ping per ricordare l'orario di partenza e Google Maps li indirizza al punto di incontro in tempo.

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

Aggiungi un evento

Per creare un evento, chiama il events.insert() metodo fornendo al meno questi parametri:

• calendarId è l'identificatore del calendario e può essere l'indirizzo email del calendario su 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 che vuoi utilizzare, puoi controllarlo nelle impostazioni del calendario dell'interfaccia utente web di Google Calendar (nella sezione "Indirizzo del calendario") oppure puoi cercarlo nel risultato della calendarList.list() chiamata.
• event è l'evento da creare con tutti i dettagli necessari, come l'inizio e la fine. Gli unici due campi obbligatori sono gli orari di start e end. Per l'insieme completo dei campi degli eventi, consulta il riferimento event.
  Specifica gli eventi programmati utilizzando i campi start.dateTime e end.dateTime. Per gli eventi di un'intera giornata, utilizza invece start.date e end.date.

Per creare correttamente gli eventi, devi:

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

Aggiungi metadati degli eventi

Puoi aggiungere facoltativamente i metadati degli eventi quando crei un evento del calendario. Se scegli di non aggiungere metadati durante la creazione, puoi aggiornare molti campi utilizzando events.update(); tuttavia, alcuni campi, come l'ID evento, possono essere impostati solo durante un'operazione events.insert().

Località

L'aggiunta di un indirizzo nel campo della località attiva funzionalità come "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. In questo modo, puoi mantenere sincronizzate le entità nel tuo database locale con gli eventi in Google Calendar. Inoltre, impedisce la creazione di eventi duplicati se l'operazione non riesce a un certo punto dopo l'esecuzione corretta nel backend di Calendar. Se non viene fornito alcun ID evento, il server ne genera uno per te. Per ulteriori informazioni, consulta il riferimento all'ID evento.

Partecipanti

L'evento che crei viene visualizzato in tutti i calendari Google principali dei partecipanti che hai incluso con lo stesso ID evento. Se imposti sendUpdates su "all" o "externalOnly" nella richiesta di inserimento, i partecipanti corrispondenti ricevono una notifica via email per l'evento. Per saperne di più, consulta Eventi con più partecipanti.

Gli esempi seguenti mostrano come creare un evento e impostarne i metadati:

Vai

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

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

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': '[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}"

Aggiungi allegati di Drive agli eventi

Puoi allegare file di Google Drive come appunti sulla riunione in Documenti, budget in Fogli, presentazioni in Presentazioni o qualsiasi altro file di Google Drive pertinente ai tuoi eventi del calendario. Puoi aggiungere l' allegato quando crei un evento con events.insert() o in un secondo momento nell'ambito di un aggiornamento, ad esempio con events.patch()

L'allegato di un file di Google Drive a un evento è composto da due parti:

1. Recupera l'URL alternateLink, title e mimeType del file 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 allegato:

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: prima di abilitare il parametro supportsAttachments per le modifiche degli eventi quando aggiungi il supporto degli allegati all'app esistente che archivia gli eventi localmente, devi eseguire una sincronizzazione completa di tutti gli eventi. Se non esegui prima una sincronizzazione, potresti rimuovere inavvertitamente gli allegati esistenti dagli eventi degli utenti.

Aggiungi conferenze video e audio agli eventi

Puoi associare gli eventi alle Hangouts e Google Meet per consentire agli utenti di incontrarsi da remoto tramite una chiamata o una videochiamata.

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

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

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

Puoi scoprire quale tipo di conferenza è supportato per un determinato calendario di un utente esaminando il conferenceProperties.allowedConferenceSolutionTypes nelle raccolte calendars e calendarList. Puoi anche scoprire se l'utente preferisce che Hangouts venga creato per tutti i nuovi eventi creati controllando l'impostazione autoAddHangouts nella settings raccolta.

Oltre a type, conferenceSolution fornisce anche i campi name e iconUri che puoi utilizzare per rappresentare la soluzione per le 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 una string casuale. Le conferenze vengono create in modo asincrono, ma puoi sempre controllare lo stato della tua richiesta per informare gli utenti di ciò che sta accadendo.

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

La risposta immediata a questa chiamata potrebbe non contenere ancora completamente compilato conferenceData; questo è indicato da un codice di stato pending nel campo dello stato. Il codice di stato diventa success dopo che le informazioni sulla conferenza sono state compilate. Il campo entryPoints contiene informazioni sugli URI video e audio che gli utenti possono utilizzare per connettersi via telefono.

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

La copia è utile in determinate situazioni. Ad esempio, supponiamo che tu stia sviluppando un'applicazione di reclutamento che configura 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: prima di abilitare il supporto dei dati delle conferenze (impostando il parametro della richiesta conferenceDataVersion su 1 per le modifiche degli eventi) quando aggiungi il supporto delle conferenze all'app esistente che archivia gli eventi localmente, devi eseguire una sincronizzazione completa di tutti gli eventi. Se non esegui prima una sincronizzazione, potresti rimuovere inavvertitamente le conferenze esistenti dagli eventi degli utenti.