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 località.

In Google Calendar, gli utenti possono creare eventi di momento 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 momento di concentrazione in Google Calendar e Attivare o disattivare il luogo di lavoro per gli utenti.

Leggere ed elencare gli eventi di stato nel calendario

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

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

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

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

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

Iscriversi alle modifiche degli eventi di stato

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

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

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

Creare e aggiornare gli eventi di stato nel calendario

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

Se aggiorni l'evento di stato utilizzando events.update metodo, 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 focusTimeProperties campo.
  • Imposta il transparency campo su 'opaque'.
  • Imposta i campi start e end dell'evento in modo che siano un evento con orario (con orari di inizio e di fine specificati).
    I momenti di concentrazione non possono essere eventi che durano tutto il giorno.

Per i dettagli sulle funzionalità, vedi Utilizzare il momento di concentrazione in Google Calendar

Creare un evento fuori sede

Per creare un evento fuori sede:

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

Per i dettagli sulle funzionalità, vedi Mostrare quando sei fuori sede

Creare un evento di luogo di lavoro

Per creare un evento di luogo di lavoro:

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

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

    • Un evento con orario (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 di luogo di lavoro che durano tutto il giorno non possono durare più giorni, ma gli eventi con orario sì.

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

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

Per i dettagli sulle funzionalità, vedi Impostare orario di lavoro e luogo di lavoro e Attivare o disattivare il luogo di lavoro per gli utenti

Come mostrare gli eventi di luogo di lavoro sovrapposti

Un utente può avere più eventi di luogo di lavoro nel proprio calendario contemporaneamente, che si sovrappongono, il che significa che in un determinato momento potrebbero essere impostati più luoghi di lavoro. Nelle circostanze in cui all'utente può essere mostrata una sola località, questa deve essere mostrata in modo coerente in più applicazioni. Quando esegui questa operazione, utilizza le seguenti 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 sugli eventi 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 sugli eventi creati in precedenza.
  • Gli eventi parzialmente sovrapposti devono essere mostrati come due eventi diversi, ognuno con il proprio luogo 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 integrate con Google Workspace. Gli script vengono sviluppati in un editor di codice basato su browser, 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 delle risorse e dei metodi dell'API Google Calendar, consulta la documentazione di riferimento.

Creare e configurare lo script

  1. Crea uno script andando alla pagina 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) Aggiornare 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 allo script.

  1. A sinistra dell'editor, fai clic su Impostazioni progetto .
  2. In Progetto Google Cloud Platform (Google Cloud), fai clic su Cambia progetto.
  3. Inserisci il numero del progetto Google Cloud che fa parte del Programma Anteprima per sviluppatori e fai clic su Imposta progetto.
  4. A sinistra, 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 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}`;
}

Eseguire 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. Alla 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.