Gestisci gli eventi di momento di concentrazione, fuori sede e luogo di lavoro

Questa pagina spiega come utilizzare l'API Google Calendar per creare eventi che mostrano lo stato degli utenti di Google Calendar. Gli eventi di stato descrivono dove si trovano gli utenti o cosa stanno facendo, ad esempio se sono in un momento di concentrazione, fuori sede o se lavorano da una determinata posizione.

In Google Calendar, gli utenti possono creare eventi di tempo di concentrazione, fuori sede e luogo di lavoro per indicare il proprio stato e la propria posizione personalizzati. Queste funzionalità sono disponibili solo sui calendari principali e per alcuni utenti di Google Calendar.

Per maggiori dettagli, vedi Utilizzare il tempo di concentrazione in Google Calendar e Attivare o disattivare il luogo di lavoro per gli utenti.

Leggere ed elencare gli eventi di stato di Calendar

Puoi leggere ed elencare gli eventi di stato di Calendar nella risorsa Events dell'API Calendar.

Per leggere un evento di stato, utilizza il metodo events.get, specificando eventId dell'evento.

Per elencare gli eventi di stato, utilizza il metodo events.list, specificando uno o più dei seguenti valori nel campo eventTypes:

  • 'focusTime'
  • 'outOfOffice'
  • 'workingLocation'

Poi, negli oggetti Event restituiti, verifica che il campo eventType abbia il valore richiesto e consulta il campo corrispondente per i dettagli sullo stato creato dall'utente in Google Calendar:

Iscriviti alle modifiche degli eventi di stato

Puoi iscriverti alle modifiche degli eventi di stato nella risorsa Events dell'API Calendar.

Utilizza il metodo events.watch, specificando l'calendarId del calendario a cui abbonarti e uno o più dei seguenti valori nel campo eventTypes:

  • 'focusTime'
  • 'outOfOffice'
  • 'workingLocation'

Creare e aggiornare gli eventi di stato del calendario

Per creare un evento di stato, crea un'istanza della risorsa Events utilizzando il metodo events.insert, impostando i campi obbligatori per il tipo di evento.

Se aggiorni l'evento di stato utilizzando il metodo events.update, l'evento deve mantenere i campi obbligatori.

Creare un momento di concentrazione

Per creare un evento di momento di concentrazione:

  • Imposta eventType su 'focusTime'.
  • Includi il campo focusTimeProperties.
  • Imposta il campo transparency su 'opaque'.
  • Imposta i campi start e end dell'evento in modo che sia un evento a tempo (con orari di inizio e di fine specificati).
    I momenti di concentrazione non possono essere eventi che durano tutto il giorno.

Per informazioni dettagliate sulla funzionalità, vedi Utilizzare il momento di concentrazione in Google Calendar.

Creare un messaggio fuori sede

Per creare un evento fuori sede:

  • Imposta eventType su 'outOfOffice'.
  • Includi il campo outOfOfficeProperties.
  • Imposta il campo transparency su 'opaque'.
  • Imposta i campi start e end dell'evento in modo che sia un evento a tempo (con orari di inizio e di fine specificati).
    Gli eventi fuori sede non possono durare tutto il giorno.

Per informazioni dettagliate sulla funzionalità, vai a Mostrare quando sei fuori sede.

Crea luogo di lavoro

Per creare un evento di luogo di lavoro:

  • Imposta eventType su 'workingLocation'.
  • Includi il campo workingLocationProperties.
  • Imposta il campo visibility su 'public'.
  • Imposta il campo transparency su 'transparent'.

  • Imposta i campi start e end dell'evento in modo che siano:

    • Un evento a tempo (con orari di inizio e di fine specificati).
    • Un evento che dura tutto il giorno (con date di inizio e di fine specificate) che dura esattamente un giorno.

    Gli eventi relativi a un luogo di lavoro che durano tutto il giorno non possono estendersi su più giorni, ma gli eventi a orario possono.

I seguenti campi sono facoltativi, ma consigliati per un'esperienza utente ottimale quando inserisci un officeLocation:

La creazione e l'aggiornamento degli eventi relativi alla sede di lavoro tramite gli endpoint batch non sono supportati.

Per i dettagli della funzionalità, vai a Impostare orario e luogo di lavoro e Attivare o disattivare il luogo di lavoro per gli utenti.

Come mostrare gli eventi relativi a luoghi di lavoro sovrapposti

Un utente può avere più eventi di luogo di lavoro nel calendario contemporaneamente che si sovrappongono, il che significa che in un determinato momento potrebbero essere impostati più luoghi di lavoro. Nei casi in cui è possibile mostrare all'utente una sola posizione, questa deve essere mostrata in modo coerente in più applicazioni. Quando lo fai, segui queste linee guida per scegliere quale evento mostrare:

  • Gli eventi con orario hanno la precedenza sugli eventi che durano tutto il giorno.
  • Gli eventi singoli hanno la precedenza sugli eventi ricorrenti e sulle relative eccezioni.
  • Gli eventi che iniziano più tardi hanno la precedenza su quelli che iniziano prima.
  • Gli eventi con durate più brevi hanno la precedenza su quelli con durate più lunghe.
  • Gli eventi creati più di recente hanno la precedenza su quelli creati in precedenza.
  • Gli eventi parzialmente sovrapposti devono essere visualizzati come due eventi diversi, ciascuno con la propria sede di lavoro.

Creare eventi di stato 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 gestire gli eventi di stato 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

  1. Crea uno script andando su script.google.com/create.
  2. Nel riquadro a sinistra, accanto a Servizi, fai clic su Aggiungi un servizio .
  3. Seleziona API Google Calendar e fai clic su Aggiungi.
  4. 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, segui questi passaggi per aggiornare il progetto associato al tuo script.

  1. Sul lato sinistro dell'editor, fai clic su Impostazioni progetto .
  2. In Progetto Google Cloud (GCP), fai clic su Cambia progetto.
  3. Inserisci il numero di progetto del progetto Google Cloud che fa parte del programma Developer Preview e fai clic su Imposta progetto.
  4. Sul lato sinistro, seleziona Editor per tornare all'editor di codice.

Aggiungere codice allo script

Il seguente esempio di codice mostra come creare, leggere ed elencare gli eventi di stato nel tuo calendario principale.

  1. Incolla il seguente codice nell'editor di codice.

    /** Creates a focus time event. */
function createFocusTime() {
  const event = {
    start: { dateTime: '2023-11-14T10:00:00+01:00' },
    end: { dateTime: '2023-11-14T12:00:00+01:00' },
    eventType: 'focusTime',
    focusTimeProperties: {
      chatStatus: 'doNotDisturb',
      autoDeclineMode: 'declineOnlyNewConflictingInvitations',
      declineMessage: 'Declined because I am in focus time.',
    }
  }
  createEvent(event);
}

/** Creates an out of office event. */
function createOutOfOffice() {
  const event = {
    start: { dateTime: '2023-11-15T10:00:00+01:00' },
    end: { dateTime: '2023-11-15T18:00:00+01:00' },
    eventType: 'outOfOffice',
    outOfOfficeProperties: {
      autoDeclineMode: 'declineOnlyNewConflictingInvitations',
      declineMessage: 'Declined because I am on vacation.',
    }
  }
  createEvent(event);
}

/** Creates a working location event. */
function createWorkingLocation() {
  const event = {
    start: { date: "2023-06-01" },
    end: { date: "2023-06-02" },
    eventType: "workingLocation",
    visibility: "public",
    transparency: "transparent",
    workingLocationProperties: {
      type: 'customLocation',
      customLocation: { label: "a custom location" },
    }
  }
  createEvent(event);
}

/**
  * Creates a Calendar event.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/insert
  */
function createEvent(event) {
  const calendarId = 'primary';

  try {
    var response = Calendar.Events.insert(event, calendarId);
    var event = (response.eventType === 'workingLocation') ? parseWorkingLocation(response) : response;
    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() {
  const calendarId = 'primary';

  // Replace with a valid eventId.
  const eventId = "sample-event-id";

  try {
    var response = Calendar.Events.get(calendarId, eventId);
    var event = (response.eventType === 'workingLocation') ? parseWorkingLocation(response) : response;
    console.log(event);
  } catch (exception) {
    console.log(exception.message);
  }
}

/** Lists focus time events. */
function listFocusTimes() {
  listEvents('focusTime');
}

/** Lists out of office events. */
function listOutOfOffices() {
  listEvents('outOfOffice');
}

/** Lists working location events. */
function listWorkingLocations() {
  listEvents('workingLocation');
}

/**
  * Lists events with the given event type.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events/list
  */
function listEvents(eventType = 'default') {
  const calendarId = 'primary'

  // Query parameters for the list request.
  const optionalArgs = {
    eventTypes: [eventType],
    showDeleted: false,
    singleEvents: true,
    timeMax: '2023-04-01T00:00:00+01:00',
    timeMin: '2023-03-27T00:00:00+01:00',
  }
  try {
    var response = Calendar.Events.list(calendarId, optionalArgs);
    response.items.forEach(event =>
      console.log(eventType === 'workingLocation' ? parseWorkingLocation(event) : event));
  } catch (exception) {
    console.log(exception.message);
  }
}

/**
  * Parses working location properties of an event into a string.
  * See https://developers.google.com/workspace/calendar/api/v3/reference/events#resource
  */
function parseWorkingLocation(event) {
  if (event.eventType != "workingLocation") {
    throw new Error("'" + event.summary + "' is not a working location event.");
  }

  var location = 'No Location';
  const workingLocation = event.workingLocationProperties;
  if (workingLocation) {
    if (workingLocation.type === 'homeOffice') {
      location = 'Home';
    }
    if (workingLocation.type === 'officeLocation') {
      location = workingLocation.officeLocation.label;
    }
    if (workingLocation.type === 'customLocation') {
      location = workingLocation.customLocation.label;
    }
  }
  return `${event.start.date}: ${location}`;
}

Esegui l'esempio di codice

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