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 del Calendario de Google para crear eventos que muestren el estado de los usuarios del Calendario de Google. Los eventos de estado describen dónde se encuentran los usuarios qué están haciendo, por ejemplo, si están en tiempo dedicado, fuera de la oficina o trabajar desde un lugar determinado.

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

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

Leer y enumerar los eventos de estado del Calendario

Puedes leer y enumerar los eventos de estado del Calendario en la Recurso Events del API de Calendar.

Para leer un evento de estado, usa el events.get si especificas la eventId del evento

Para enumerar los eventos de estado, usa el events.list, si se 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 El campo eventType tiene los siguientes elementos: valor solicitado y consulta el campo correspondiente para conocer los detalles estado creado por el usuario en el Calendario de Google:

• focusTimeProperties
• outOfOfficeProperties
• workingLocationProperties

Suscribirse a los cambios en los eventos de estado

Puedes suscribirte a los cambios en los eventos de estado en la Recurso Events del API de Calendar.

Usa el events.watch si especificas la calendarId de las Calendario al cual suscribirse y uno o más de los siguientes valores en la Campo eventTypes:

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

Crea y actualiza eventos de estado del Calendario

Para crear un evento de estado, debes crear una instancia del Events con la events.insert, y se establece la campos obligatorios para el tipo de evento.

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

Crea tiempo dedicado

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

• Establecer eventType como 'focusTime'
• Incluye el focusTimeProperties .
• Establece el elemento transparency. en 'opaque'.
• Establece el start del evento y end campos para que sean un evento con horario (con las horas de inicio y finalización especificadas).
  Los horarios de concentración no pueden ser eventos que duren todo el día.

Para conocer los detalles de la función, consulta Cómo usar el tiempo dedicado en Google Calendario

Crear fuera de la oficina

Para crear un evento fuera de la oficina, sigue estos pasos:

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

Para conocer los detalles de la función, ve a Muestra cuándo te quedaste sin oficina

Crear ubicación de trabajo

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

• Establecer eventType como 'workingLocation'
• Incluye el workingLocationProperties .
• Establece el campo visibility. a 'public'.
• Establece el elemento transparency. en 'transparent'.

• Establece el start del evento y end campos deben ser:

  • Un evento temporizado (con horas de inicio y finalización especificadas).
  • Un evento que dura todo el día (con fechas de inicio y de 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 puedes hacerlo.

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

• workingLocationProperties.officeLocation.buildingId Debe coincidir con un buildingId en el recursos en la base de datos. Esto ayuda a los usuarios a beneficiarse de todas las funciones del Calendario, por ejemplo sugerencias de salas de reuniones.
• workingLocationProperties.officeLocation.label Esta es la etiqueta que se muestra en los clientes web y móviles de Calendario. Tú puede recuperar los IDs y las etiquetas de edificios con el resources.buildings.list .

Crear y actualizar eventos de ubicación de trabajo a través de los extremos por lotes no es no es compatible.

Para conocer los detalles de la función, consulta Cómo configurar tu horario laboral y ubicación y Activar o desactivar la ubicación de trabajo para usuarios

Cómo mostrar eventos de ubicaciones de trabajo que se superponen

Un usuario puede tener varios eventos de ubicación de trabajo en su calendario con el mismo tiempo que se superponen, lo que significa que cualquier momento dado puede tener varias ubicaciones definidas para él. Cuando solo se puede mostrar una ubicación al usuario, se le debe mostrar esa ubicación de forma coherente en varios aplicaciones. Cuando lo hagas, usa las siguientes pautas para elegir qué evento para mostrar:

• Los eventos con tiempo tardan prioridad sobre los eventos que duran todo el día.
• Los eventos únicos tienen prioridad sobre los eventos recurrentes y su 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 los que tienen una duración más larga y las duraciones de videos.
• Los eventos creados más recientemente tienen prioridad sobre los eventos creados recientemente anteriormente.
• Los eventos que se superponen de forma parcial deben mostrarse 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 una nube basada en JavaScript de secuencia de comandos que te permite compilar aplicaciones empresariales que se integran con en Google Workspace. Las secuencias de comandos se desarrollan en un editor de código basado en el navegador. se almacenan y ejecutan en los servidores de Google. Consulta también Google Apps Script guía de inicio rápido para comenzar a usar Apps Script para enviar solicitudes a la API del Calendario de Google

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

Crea y configura la secuencia de comandos

1. Crea una secuencia de comandos desde script.google.com/create.
2. En el panel izquierdo, junto a Servicios, haz clic en Agregar un servicio. add
3. Selecciona API del Calendario de Google y haz clic en Agregar.
4. Una vez habilitada, la API aparecerá en el panel izquierdo. Los métodos disponibles y se pueden mostrar las clases de la API con la palabra clave Calendario en el editor.

Actualiza el proyecto de Google Cloud (opcional)

Cada proyecto de Google Apps Script tiene un proyecto de Google Cloud asociado. Tu puede usar el proyecto predeterminado que Google Apps Script genera automáticamente crea. 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. settings
2. En Proyecto de Google Cloud Platform (GCP), haz clic en Cambiar proyecto.
3. Ingresa el número del proyecto de Google Cloud que se encuentra en el desarrollador Programa de versión preliminar y haz clic en Establecer proyecto.
4. En la parte izquierda, selecciona Editor code para navega nuevamente hasta el 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.

   /** 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 Ejecutar.
2. En la primera ejecución, se te solicita que autorices el acceso. Revisar y permitir Apps Script para acceder a tu calendario.
3. Puedes inspeccionar los resultados de la ejecución de la secuencia de comandos en la Registro de ejecución que aparece en la parte inferior de la ventana.