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 fanno, ad esempio se si trovano in un momento di concentrazione, fuori sede o se lavorano da una determinata località.

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

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

Leggere ed elencare gli eventi relativi allo stato nel calendario

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

Per leggere un evento di stato, utilizza il metodo events.get, specificando il 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'

Quindi, negli oggetti Event restituiti, controlla che il campo eventType contenga il valore richiesto e fai riferimento al campo corrispondente per i dettagli sullo stato creato dall'utente in Google Calendar:

Iscriversi alle modifiche degli eventi di stato

Puoi iscriverti per modifiche agli eventi di stato nella risorsa Events dell'API Calendar.

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

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

Creare e aggiornare eventi relativi allo stato nel 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 come evento a tempo (con ore di inizio e di fine specificate).
    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'assenza

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 come evento a tempo (con ore di inizio e di fine specificate).
    Gli eventi fuori sede non possono durare tutto il giorno.

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

Creare il luogo di lavoro

Per creare un evento relativo alla sede 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 su:

    • Un evento a tempo (con ore di inizio e di fine specificate);
    • Un evento che dura tutto il giorno (con date di inizio e di fine specificate) che si estende per esattamente un giorno.

    Gli eventi relativi ai luoghi di lavoro che durano tutto il giorno non possono durare più giorni, ma possono farlo gli eventi con orario.

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

La creazione e l'aggiornamento degli eventi del luogo di lavoro tramite gli endpoint batch non sono supportati.

Per i dettagli sulle 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 alla località di lavoro in sovrapposizione

Un utente può avere più eventi relativi al luogo di lavoro nel proprio calendario contemporaneamente e che si sovrappongono, il che significa che per un determinato momento possono essere impostati più luoghi di lavoro. Quando è possibile mostrare all'utente una sola località, questa deve essere mostrata in modo coerente in più applicazioni. A questo scopo, segui queste linee guida per scegliere quale evento mostrare:

  • Gli eventi con orario hanno la precedenza sugli eventi giornalieri.
  • Gli eventi singoli hanno la precedenza sugli eventi ricorrenti e sulle relative eccezioni.
  • Gli eventi che iniziano in un secondo momento 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 di recente hanno la precedenza su quelli creati in precedenza.
  • Gli eventi parzialmente sovrapposti devono essere mostrati 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 consente di creare applicazioni aziendali integrate con Google Workspace. Gli script sono 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 istruzioni riportate di seguito descrivono come gestire gli eventi di stato 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

  1. Per creare uno script, vai all'indirizzo 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 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, svolgi i seguenti passaggi per aggiornare il progetto associato allo script.

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

Aggiungi codice allo script

Il seguente esempio di codice mostra come creare, leggere ed elencare gli eventi di stato sul 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/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/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/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/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. Esamina 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.