Questa pagina è stata tradotta dall'API Cloud Translation.

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

In questa pagina viene spiegato 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 si trovano in un momento di concentrazione, fuori sede o se lavorano da un luogo specifico.

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 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 dello stato nel calendario

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'

Quindi, negli oggetti Event restituiti, verifica 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:

Iscriviti alle modifiche relative agli eventi di stato

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

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

'focusTime'
'outOfOffice'
'workingLocation'

Creare e aggiornare eventi di 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.

Crea 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 siano a tempo (con l'ora di inizio e di fine specificate).
I momenti di concentrazione non possono essere eventi che durano tutto il giorno.

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

Crea 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 siano a tempo (con l'ora di inizio e di fine specificate).
Gli eventi fuori sede non possono essere eventi che durano tutto il giorno.

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

Crea luogo di lavoro

Per creare un evento relativo al 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 l'ora di inizio e di fine specificate).
- Un evento che dura tutto il giorno (con date di inizio e di fine specificate) che dura esattamente un giorno.
Gli eventi relativi al luogo di lavoro che durano tutto il giorno non possono durare più giorni, a differenza degli eventi con orario prestabilito.

I seguenti campi sono facoltativi, ma consigliati per un'esperienza utente ottimale durante l'inserimento di officeLocation:

workingLocationProperties.officeLocation.buildingId: deve corrispondere a un buildingId nel database delle risorse dell'organizzazione. Ciò consente agli utenti di usufruire di tutte le funzionalità di Calendar, ad esempio i suggerimenti sulle sale.
workingLocationProperties.officeLocation.label: si tratta dell'etichetta visualizzata sui client web e per dispositivi mobili di Calendar. Puoi recuperare gli ID edificio e creare etichette utilizzando il metodo resources.buildings.list.

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

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

Come mostrare eventi sovrapposti di luoghi di lavoro

Un utente può avere nel calendario più eventi relativi al luogo di lavoro contemporaneamente che si sovrappongono, il che significa che in un determinato orario potrebbero essere impostati più luoghi di lavoro. Nei casi in cui all'utente può essere mostrata una sola località, questa dovrebbe essere mostrata in modo coerente su più applicazioni. Quando esegui questa operazione, segui queste linee guida per scegliere l'evento da mostrare:

Gli eventi con timestamp 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 dopo 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 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 consente di creare applicazioni aziendali che si integrano 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 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.

Crea e configura lo script

Per creare uno script, vai a 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.
Dopo averla 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

A ogni progetto Google Apps Script è associato un progetto Google Cloud. Lo script può utilizzare il progetto predefinito che Google Apps Script crea automaticamente. Se vuoi utilizzare un progetto Google Cloud personalizzato, segui questi passaggi per aggiornare il progetto associato allo script.

Sul lato sinistro dell'editor, fai clic su Impostazioni progetto .
In Progetto Google Cloud Platform (GCP), fai clic su Cambia progetto.
Inserisci il numero del progetto Google Cloud nel Programma Anteprima per sviluppatori e fai clic su Imposta progetto.
A sinistra, 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 nel calendario principale.

Incolla il codice seguente nell'editor di codice.

primary è una parola chiave per accedere al calendario principale dell'utente che ha eseguito l'accesso. Per recuperare gli eventi in un calendario diverso, imposta il parametro calendarId su un indirizzo email. In questo modo puoi leggere gli eventi di stato sui calendari degli altri utenti a cui hai accesso minimo/occupato. I calendari secondari non possono avere eventi di stato.

/** 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

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. Esamina e consenti ad Apps Script di accedere al tuo calendario.
Puoi esaminare i risultati dell'esecuzione dello script nel log Execution che viene visualizzato nella parte inferiore della finestra.