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 è impostato, verrà utilizzato il tipo 'default'.
eventTypes può essere specificato in una chiamata Events:list per elencare gli 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à la sottoscrizione 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 Creare eventi per iniziare a lavorare con 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 sulla data di nascita vengono sincronizzate con Google Calendar quando gli utenti aggiungono una persona e includono la sua data di nascita e altre date importanti in Contatti Google. Anche il compleanno degli utenti viene sincronizzato con Google Calendar dal loro 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, esamina il campo birthdayProperties per ulteriori dettagli su questo evento speciale. birthdayProperties ha i seguenti campi:

type: tipo di questo evento speciale, che si tratti di un compleanno, un anniversario o un'altra data significativa.
customTypeName: Etichetta specificata dall'utente per questo evento speciale. Questo campo viene compilato se type è impostato su 'custom'.
contact: Il nome della risorsa del contatto a cui è collegato questo evento speciale, se presente. Questo 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 di un giorno che dura 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 colorId, summary e reminders degli eventi di compleanno utilizzando i metodi update e patch. I campi start e end possono essere aggiornati per modificare la data dell'evento. In questo caso, i nuovi valori devono definire un evento che dura esattamente un giorno. I dettagli dell'orario di un evento di compleanno non possono essere aggiornati se l'evento è collegato a un contact o se il suo 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. Allo stesso modo, gli utenti possono modificare la propria data di nascita nel profilo dell'Account Google e sincronizzarla con Google Calendar.

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

L'API supporta l'operazione import per gli eventi di compleanno; tuttavia, l'evento verrà importato come evento predefinito. In altre parole, il 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 ricevere aggiornamenti sugli eventi di compleanno. Se non viene specificato alcun tipo, verranno sottoscritti 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 leggere gli 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 da Gmail verranno elencati insieme a tutti gli altri tipi di eventi.

L'API supporta il metodo watch per iscriversi alle modifiche degli eventi di Gmail su Google Calendar. Se non viene specificato alcun tipo, verranno sottoscritti tutti i tipi di eventi, incluso 'fromGmail'.

Gli eventi da 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.

Momento di concentrazione, 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 di tempo di concentrazione, fuori sede e sede di lavoro.

Esplorare i tipi di eventi in Google Apps Script

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

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

Creare e configurare lo script

Crea uno script andando 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 a 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 sul lato sinistro per tornare all'editor di codice.

Aggiungere codice allo script

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

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/workspace/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/workspace/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/workspace/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: l'indirizzo email del calendario da 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.
Nella prima esecuzione, ti viene chiesto di autorizzare l'accesso. Controlla 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.