Administra eventos de tiempo dedicado, fuera de la oficina y en la ubicación de trabajo

En esta página, se explica cómo usar la API de Calendario de Google para crear eventos que muestren el estado de los usuarios de Calendario de Google. Los eventos de estado describen dónde se encuentran los usuarios o qué están haciendo, y si están en tiempo dedicado, fuera de la oficina o trabajando en una ubicación determinada.

En el Calendario de Google, los usuarios pueden crear eventos de tiempo dedicado, fuera de la oficina y de ubicación de trabajo para indicar su estado y ubicación personalizados. Estas funciones solo están disponibles en los calendarios principales y para algunos usuarios de Calendario de Google.

Para obtener más detalles, consulta Cómo usar el tiempo dedicado en el Calendario de Google y Cómo activar o desactivar la ubicación de trabajo para los usuarios.

Leer y enumerar eventos de estado del Calendario

Puedes leer y mostrar una lista de los eventos de estado del Calendario en el recurso Events de la API de Calendar.

Para leer un evento de estado, usa el método events.get y especifica la eventId del evento.

Para enumerar los eventos de estado, usa el método events.list y especifica uno o más de los siguientes valores en el campo eventTypes:

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

Luego, en los objetos Event que se muestran, inspecciona que el campo eventType tenga el valor solicitado y consulta el campo correspondiente para obtener detalles sobre el estado que creó el usuario en el Calendario de Google:

• focusTimeProperties
• outOfOfficeProperties
• workingLocationProperties

Cómo suscribirse a los cambios en los eventos de estado

Puedes suscribirte a cambios sobre eventos de estado en el recurso Events de la API de Calendar.

Usa el método events.watch y especifica el calendarId del calendario al que deseas suscribirte y uno o más de los siguientes valores en el campo eventTypes:

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

Crea y actualiza eventos de estado del Calendario

Para crear un evento de estado, crea una instancia del recurso Events con el método events.insert y configura los campos obligatorios para el tipo de evento.

Si actualizas el evento de estado con el método events.update, el evento debe mantener los campos obligatorios.

Crea un evento de tiempo dedicado

Para crear un evento de tiempo dedicado, sigue estos pasos:

• Establece eventType en 'focusTime'.
• Incluye el campo focusTimeProperties.
• Establece el campo transparency en 'opaque'.
• Configura los campos start y end del evento para que sean un evento temporizado (con las horas de inicio y finalización especificadas).
  Los tiempos dedicados no pueden ser eventos de todo el día.

Para conocer los detalles de las funciones, consulta Cómo usar el tiempo dedicado en el Calendario de Google.

Crear fuera de la oficina

Sigue estos pasos para crear un evento fuera de la oficina:

• Establece eventType en 'outOfOffice'.
• Incluye el campo outOfOfficeProperties.
• Establece el campo transparency en 'opaque'.
• Configura los campos start y end del evento para que sean un evento temporizado (con las horas de inicio y finalización especificadas).
  Los eventos fuera de la oficina no pueden ser de todo el día.

Para obtener detalles sobre las funciones, consulta Cómo mostrar que estás fuera de la oficina.

Crear ubicación de trabajo

Para crear un evento de ubicación de trabajo, sigue estos pasos:

• Establece eventType en 'workingLocation'.
• Incluye el campo workingLocationProperties.
• Establece el campo visibility en 'public'.
• Establece el campo transparency en 'transparent'.

• Configura los campos start y end del evento de la siguiente manera:

  • Un evento con límite de tiempo (con las horas de inicio y finalización especificadas)
  • Un evento de todo el día (con las fechas de inicio y finalización especificadas) que abarca exactamente un día.

  Los eventos de ubicación de trabajo que duran todo el día no pueden abarcar varios días, pero los eventos programados sí.

Los siguientes campos son opcionales, pero se recomiendan para obtener la mejor experiencia del usuario cuando se inserta un officeLocation:

• workingLocationProperties.officeLocation.buildingId: Debe coincidir con un buildingId en la base de datos de recursos de la organización. Esto ayuda a los usuarios a beneficiarse de todas las funciones de Calendario, por ejemplo, las sugerencias de salas de reuniones.
• workingLocationProperties.officeLocation.label: Esta es la etiqueta que se muestra en los clientes móviles y en la Web de Calendario. Puedes recuperar los IDs y las etiquetas de compilación con el método resources.buildings.list.

No se admite la creación ni la actualización de eventos de ubicación de trabajo a través de los extremos del lote.

Si quieres conocer los detalles de la función, consulta Cómo configurar tu horario laboral y ubicación y Cómo activar o desactivar la ubicación de trabajo para los usuarios.

Cómo mostrar eventos de ubicación de trabajo superpuestos

Un usuario puede tener varios eventos de ubicación de trabajo en su calendario al mismo tiempo que se superponen, por lo que un momento determinado podría tener varias ubicaciones de trabajo configuradas. Cuando solo se puede mostrar una ubicación al usuario, se le debe mostrar esa ubicación de manera coherente en varias aplicaciones. Cuando lo hagas, usa los siguientes lineamientos para elegir qué evento mostrar:

• Los eventos programados tienen prioridad sobre los eventos de todo el día.
• Los eventos únicos tienen prioridad sobre los eventos recurrentes y sus excepciones.
• Los eventos que comienzan más tarde tienen prioridad sobre los que comienzan antes.
• Los eventos con duraciones más cortas tienen prioridad sobre aquellos con duraciones más largas.
• Los eventos creados más recientemente tienen prioridad sobre los que se crearon antes.
• Los eventos parcialmente superpuestos se deben mostrar como dos eventos diferentes, cada uno con su propia ubicación de trabajo.

Crea eventos de estado en Google Apps Script

Google Apps Script es un lenguaje de secuencias de comandos en la nube basado en JavaScript que te permite compilar aplicaciones empresariales que se integran en Google Workspace. Las secuencias de comandos se desarrollan en un editor de código basado en el navegador y se almacenan y ejecutan en los servidores de Google. Consulta también la guía de inicio rápido de Google Apps Script para comenzar a usar Apps Script a fin de enviar solicitudes a la API del Calendario de Google.

En las siguientes instrucciones, se describe cómo administrar eventos de estado con la API del Calendario de Google como un servicio avanzado de Google Apps Script. Para obtener una lista completa de los recursos y métodos de la API del Calendario de Google, consulta la documentación de referencia.

Crea y configura la secuencia de comandos

1. Para crear una secuencia de comandos, ve a script.google.com/create.
2. En el panel izquierdo, junto a Servicios, haz clic en Agregar un servicio. .
3. Selecciona API del Calendario de Google y haz clic en Agregar.
4. Una vez habilitada, la API aparece en el panel izquierdo. Se pueden enumerar los métodos y las clases disponibles en la API con la palabra clave del Calendario en el editor.

(Opcional) Actualiza el proyecto de Google Cloud

Cada proyecto de Google Apps Script tiene un proyecto de Google Cloud asociado. La secuencia de comandos puede usar el proyecto predeterminado que Google Apps Script crea automáticamente. Si quieres usar un proyecto personalizado de Google Cloud, sigue estos pasos para actualizar el proyecto asociado con tu secuencia de comandos.

1. En el lado izquierdo del editor, haz clic en Configuración del proyecto .
2. En Proyecto de Google Cloud Platform (GCP), haz clic en Cambiar proyecto.
3. Ingresa el número del proyecto de Google Cloud que está en el Programa de Versión preliminar para desarrolladores y haz clic en Establecer proyecto.
4. En el lado izquierdo, selecciona Editor para volver al editor de código.

Agrega código a la secuencia de comandos

En la siguiente muestra de código, se indica cómo crear, leer y enumerar eventos de estado en tu calendario principal.

1. Pega lo siguiente en el editor de código.

   primary es una palabra clave para acceder al calendario principal del usuario que accedió. Para recuperar eventos en un calendario diferente, configura el parámetro calendarId como una dirección de correo electrónico. Esto te permite leer los eventos de estado en los calendarios de otros usuarios a los que tengas, como mínimo, el acceso disponible/ocupado. Los calendarios secundarios no pueden tener eventos de estado.

   /** 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}`;
   }
   

Ejecuta la muestra de código

1. Arriba del editor de código, selecciona la función que quieres ejecutar en el menú desplegable y haz clic en Run.
2. En la primera ejecución, se te solicita que autorices el acceso. Revisa y permite que Apps Script acceda a tu calendario.
3. Puedes revisar los resultados de la ejecución de la secuencia de comandos en el Registro de ejecución que aparece en la parte inferior de la ventana.