Questa pagina è stata tradotta dall'API Cloud Translation.

Tipi di evento

Questa pagina spiega la proprietà eventType e le specifiche dei tipi di eventi disponibili nell'API Google Calendar.

Google Calendar consente agli utenti di creare eventi generici, nonché eventi progettati per casi d'uso specifici e con proprietà personalizzate.

Il tipo di evento può essere rilevato nei seguenti punti dell'API:

Tutti gli eventi vengono restituiti con un eventType.
eventType deve essere impostato durante la creazione o l'aggiornamento di una risorsa evento. Se non viene impostato, verrà utilizzato il tipo 'default'.
eventTypes può essere specificato in una chiamata Events:list per elencare eventi di tipi specifici. Se non viene specificato alcun tipo, verranno restituiti tutti i tipi di eventi.
eventTypes può essere specificato in una chiamata Events:watch per iscriversi agli aggiornamenti sugli eventi di tipi specifici. Se non viene specificato alcun tipo, la richiesta comporterà l'iscrizione a tutti i tipi di eventi.

Evento predefinito

Gli eventi con tipo di evento default vengono creati e utilizzati come una delle risorse principali dell'API Google Calendar. Supportano un'ampia gamma di proprietà che possono essere utilizzate per personalizzare ulteriormente l'evento.

Consulta la sezione Creare eventi per iniziare a utilizzare gli eventi di Google Calendar.

Compleanno

I compleanni sono eventi speciali che durano tutto il giorno e si ripetono ogni anno.

Gli utenti possono creare manualmente eventi di compleanno su Google Calendar. Inoltre, le informazioni sul compleanno vengono sincronizzate con Google Calendar quando gli utenti aggiungono una persona e includono il suo compleanno e altre date importanti in Contatti Google. Anche il compleanno dell'utente viene sincronizzato con Google Calendar dal suo profilo dell'Account Google.

L'API Google Calendar supporta i metodi get, instances e list per la lettura degli eventi di compleanno. eventTypes può essere impostato su 'birthday' per elencare solo gli eventi di compleanno. Se non viene specificato alcun tipo, i compleanni verranno elencati insieme a tutti gli altri tipi di eventi.

Negli oggetti Event restituiti, controlla il campo birthdayProperties per ulteriori dettagli su questo evento speciale. birthdayProperties contiene i seguenti campi:

type: il tipo di questo evento speciale, che si tratti di un compleanno, di un anniversario o di un'altra data significativa.
customTypeName: etichetta specificata dall'utente per questo evento speciale. Viene compilato se type è impostato su 'custom'.
contact: nome della risorsa del contatto a cui è collegato questo evento speciale, se presente. Ha il formato 'people/c12345' e può essere utilizzato per recuperare i dettagli di contatto dall'API People.

L'API consente di creare eventi di compleanno utilizzando il metodo insert con le seguenti specifiche:

eventType è impostato su 'birthday'.
I campi start e end devono definire un evento per l'intera giornata che si estenda per esattamente un giorno.
Il valore del campo visibility deve essere 'private'.
Il valore del campo transparency deve essere 'transparent'.
Deve avere una ricorrenza annuale, il che significa che il campo recurrence deve essere 'RRULE:FREQ=YEARLY'. Gli eventi di compleanno che cadono il 29 febbraio devono avere la seguente regola di ricorrenza: 'RRULE:FREQ=YEARLY;BYMONTH=2;BYMONTHDAY=-1'.
Può avere un colorId, summary e reminders.
Può avere birthdayProperties. Se specificato, type deve essere 'birthday' e sia customTypeName che contact devono essere vuoti.
Non può avere altre proprietà evento.

L'API consente di aggiornare i valori colorId, summary e reminders degli eventi di compleanno utilizzando i metodi update e patch. I campi start e end possono essere aggiornati anche per cambiare la data dell'evento. In questo caso, i nuovi valori devono definire un evento tutto il giorno che si estenda per esattamente un giorno. I dettagli relativi alla data e all'ora di un evento di compleanno non possono essere aggiornati se l'evento è collegato a un contact o se il relativo type è 'self'.

L'API Google Calendar non consente di creare eventi di compleanno con birthdayProperties personalizzati o di aggiornare queste proprietà. Le date importanti possono essere modificate con l'API People e le modifiche vengono sincronizzate con Google Calendar. Analogamente, gli utenti possono modificare la propria data di nascita nel profilo del proprio Account Google, che viene sincronizzata con Google Calendar.

Le richieste che tentano di creare o aggiornare una data di nascita in un modo non supportato non andranno a buon fine. In questo caso, controlla il messaggio di errore per identificare il problema.

L'API supporta l'operazione import per gli eventi di compleanno, ma l'evento verrà importato come evento predefinito. In altre parole, eventType sarà 'default'.

L'API supporta il metodo watch per iscriversi alle modifiche agli eventi di compleanno su Google Calendar. eventTypes può essere impostato su 'birthday' per iscriversi agli aggiornamenti sugli eventi di compleanno. Se non viene specificato alcun tipo, verrà sottoscritto l'abbonamento a tutti i tipi di eventi, inclusi i compleanni.

Gli eventi di compleanno possono essere eliminati utilizzando il metodo delete dell' API Google Calendar. L'eliminazione di un evento di compleanno da Google Calendar non influisce sui dati di Contatti Google o del profilo dell'Account Google.

La modifica dell'organizzatore di un evento di compleanno utilizzando i metodi move o update non è supportata.

Eventi da Gmail

Gli eventi generati automaticamente da Gmail hanno il tipo di evento 'fromGmail'.

L'API Google Calendar non consente di creare questo tipo di evento utilizzando il metodo insert.

L'API consente di aggiornare le proprietà estese colorId, reminders, visibility, transparency, status, attendees, private e shared utilizzando i metodi update e patch.

L'API supporta i metodi get e list per la lettura degli eventi da Gmail. eventTypes può essere impostato su 'fromGmail' per elencare solo gli eventi generati da Gmail. Se non viene specificato alcun tipo, gli eventi di Gmail verranno elencati insieme a tutti gli altri tipi di eventi.

L'API supporta il metodo watch per iscriversi alle modifiche degli eventi da Gmail su Google Calendar. Se non viene specificato alcun tipo, verrà sottoscritto l'abbonamento a tutti i tipi di eventi, incluso 'fromGmail'.

Gli eventi di Gmail possono essere eliminati utilizzando il metodo delete dell' API Google Calendar.

La modifica dell'organizzatore di un evento da Gmail utilizzando i metodi move o update non è supportata.

Tempo di concentrazione, avviso fuori sede e luogo di lavoro

L'API Google Calendar può essere utilizzata per creare e gestire eventi che mostrano lo stato degli utenti di Google Calendar.

Queste funzionalità sono disponibili solo nei calendari principali e per alcuni utenti di Google Calendar. Per saperne di più, consulta Gestire gli eventi relativi al tempo di concentrazione, allo stato fuori sede e alla posizione di lavoro.

Esplorare i tipi di eventi in Google Apps Script

Google Apps Script è un linguaggio di scripting cloud basato su JavaScript che consente di creare applicazioni aziendali integrate con Google Workspace. Gli script vengono sviluppati in un editor di codice basato su browser e memorizzati ed eseguiti sui server di Google. Consulta anche la guida introduttiva di Google Apps Script per iniziare a utilizzare Apps Script per inviare richieste all'API Google Calendar.

Le istruzioni riportate di seguito descrivono come leggere e gestire gli eventi utilizzando l'API Google Calendar come servizio avanzato in Google Apps Script. Per un elenco completo delle risorse e dei metodi dell'API Google Calendar, consulta la documentazione di riferimento.

Crea e configura lo script

Per creare uno script, vai su script.google.com/create.
Nel riquadro a sinistra, accanto a Servizi, fai clic su Aggiungi un servizio .
Seleziona API Google Calendar e fai clic su Aggiungi.
Una volta abilitata, l'API viene visualizzata nel riquadro di sinistra. I metodi e le classi disponibili nell'API possono essere elencati utilizzando la parola chiave Calendar nell'editor.

(Facoltativo) Aggiorna il progetto Google Cloud

Ogni progetto Google Apps Script ha un progetto Google Cloud associato. Lo script può utilizzare il progetto predefinito creato automaticamente da Google Apps Script. Se vuoi utilizzare un progetto Google Cloud personalizzato, consulta Passare a un progetto Cloud standard diverso. Dopo aver impostato il progetto Google Cloud, seleziona Editor a sinistra per tornare all'editor di codice.

Aggiungi codice allo script

Il seguente esempio di codice mostra come elencare, leggere e creare eventi con valori eventType diversi.

Incolla il seguente codice nell'editor di codice.

const CALENDAR_ID = 'CALENDAR_ID' || 'primary';

/** Lists default events. */
function listDefaultEvents() {
  listEvents('default');
}

/** Lists birthday events. */
function listBirthdays() {
  listEvents('birthday');
}

/** Lists events from Gmail. */
function listEventsFromGmail() {
  listEvents('fromGmail');
}

/**
  * Lists events with the given event type. If no type is specified, lists all events.
  * See https://developers.google.com/calendar/api/v3/reference/events/list
  */
function listEvents(eventType = undefined) {
  // Query parameters for the list request.
  const optionalArgs = {
    eventTypes: eventType ? [eventType] : undefined,
    singleEvents: true,
    timeMax: '2024-07-30T00:00:00+01:00',
    timeMin: '2024-07-29T00:00:00+01:00',
  }
  try {
    var response = Calendar.Events.list(CALENDAR_ID, optionalArgs);
    response.items.forEach(event => console.log(event));
  } catch (exception) {
    console.log(exception.message);
  }
}

/**
  * Reads the event with the given eventId.
  * See https://developers.google.com/calendar/api/v3/reference/events/get
  */
function readEvent() {
  try {
    var response = Calendar.Events.get(CALENDAR_ID, 'EVENT_ID');
    console.log(response);
  } catch (exception) {
    console.log(exception.message);
  }
}

/** Creates a default event. */
function createDefaultEvent() {
  const event = {
    start: { dateTime: '2024-07-30T10:30:00+01:00'},
    end: { dateTime: '2024-07-30T12:30:00+01:00'},
    description: 'Created from Apps Script.',
    eventType: 'default',
    summary: 'Sample event',
  }
  createEvent(event);
}

/** Creates a birthday event. */
function createBirthday() {
  const event = {
    start: { date: '2024-01-29' },
    end: { date: '2024-01-30' },
    eventType: 'birthday',
    recurrence: ["RRULE:FREQ=YEARLY"],
    summary: "My friend's birthday",
    transparency: "transparent",
    visibility: "private",
  }
  createEvent(event);
}

/**
  * Creates a Calendar event.
  * See https://developers.google.com/calendar/api/v3/reference/events/insert
  */
function createEvent(event) {

  try {
    var response = Calendar.Events.insert(event, CALENDAR_ID);
    console.log(response);
  } catch (exception) {
    console.log(exception.message);
  }
}

Sostituisci quanto segue:

CALENDAR_ID: indirizzo email del calendario su cui recuperare e creare eventi. Questa costante è inizialmente impostata su 'primary', che è una parola chiave per accedere al calendario principale dell' utente che ha eseguito l'accesso. La modifica di questo valore ti consente di leggere gli eventi nei calendari di altri utenti a cui hai accesso.
EVENT_ID: l'ID dell'evento. Puoi chiamare Events:list per recuperare gli ID evento.

Esegui l'esempio di codice

Sopra l'editor di codice, seleziona la funzione da eseguire dal menu a discesa e fai clic su Esegui.
Alla prima esecuzione, ti viene chiesto di autorizzare l'accesso. Esamina e consenti ad Apps Script di accedere al tuo calendario.
Puoi esaminare i risultati dell'esecuzione dello script nel log di esecuzione visualizzato nella parte inferiore della finestra.