Obtener la programación de disponibilidad de los usuarios y recursos del calendario de Outlook

  • Artículo

En el trabajo o la escuela, es común querer ver cuándo un usuario está libre para una reunión o mirar la disponibilidad de un equipo, sala o equipamiento durante un período de tiempo.

Con la acción getSchedule podrá obtener la información de disponibilidad de una o más entidades (usuarios, listas de distribución o recursos) durante un período de tiempo específico.

Ejemplo

Un ejemplo sencillo es buscar la programación de disponibilidad de un compañero de trabajo, Miguel, un día concreto, de 9:00 a 18:00 CET:

POST https://graph.microsoft.com/v1.0/me/calendar/getschedule
Prefer: outlook.timezone="Pacific Standard Time"
Content-Type: application/json

{
    "Schedules": ["AlexW@contoso.com"],
    "StartTime": {
        "dateTime": "2018-08-06T09:00:00",
        "timeZone": "Pacific Standard Time"
    },
    "EndTime": {
        "dateTime": "2018-08-06T18:00:00",
        "timeZone": "Pacific Standard Time"
    },
    "availabilityViewInterval": "15"
}

getSchedule devuelve dos elementos de programación que coinciden con los eventos existentes en el calendario predeterminado de Miguel, que muestra las horas de inicio y finalización de cada evento y el estado de disponibilidad. Puede suponer que Miguel está disponible durante el tiempo restante en ese intervalo de fecha y hora.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.scheduleInformation)",
    "value":[
        {
            "scheduleId":"AlexW@contoso.com",
            "availabilityView":"111111002222222200000000000000000000",
            "scheduleItems":[
                {
                    "status":"Tentative",
                    "start":{
                        "dateTime":"2018-08-06T09:00:00.0000000",
                        "timeZone":"Pacific Standard Time"
                    },
                    "end":{
                        "dateTime":"2018-08-06T10:30:00.0000000",
                        "timeZone":"Pacific Standard Time"
                    }
                },
                {
                    "status":"Busy",
                    "start":{
                        "dateTime":"2018-08-06T11:00:00.0000000",
                        "timeZone":"Pacific Standard Time"
                    },
                    "end":{
                        "dateTime":"2018-08-06T13:00:00.0000000",
                        "timeZone":"Pacific Standard Time"
                    }
                }
            ],
            "workingHours":{
                "daysOfWeek":[
                    "monday",
                    "tuesday",
                    "wednesday",
                    "thursday",
                    "friday"
                ],
                "startTime":"08:00:00.0000000",
                "endTime":"17:00:00.0000000",
                "timeZone":{
                    "@odata.type":"#microsoft.graph.customTimeZone",
                    "bias":480,
                    "name":"Customized Time Zone",
                    "standardOffset":{
                        "time":"02:00:00.0000000",
                        "dayOccurrence":1,
                        "dayOfWeek":"sunday",
                        "month":11,
                        "year":0
                    },
                    "daylightOffset":{
                        "daylightBias":-60,
                        "time":"02:00:00.0000000",
                        "dayOccurrence":2,
                        "dayOfWeek":"sunday",
                        "month":3,
                        "year":0
                    }
                }
            }
        }
    ]
}

Aparte de la programación de disponibilidad y las horas de trabajo de Miguel, getSchedule también devuelve availabilityView, que es una vista combinada de la disponibilidad de Miguel para ese día. La vista combinada es una cadena formada por franjas temporales relativas a ese día, donde cada intervalo de tiempo indica la disponibilidad de Miguel mediante la convención siguiente:

  • 0= disponible
  • 1= provisional
  • 2= ocupado
  • 3= fuera de la oficina
  • 4= trabajando en otro sitio.

De forma predeterminada, cada intervalo de tiempo es de 30 minutos. Este ejemplo usa la propiedad availabilityViewInterval para personalizar el intervalo de tiempo y que sea de 15 minutos.

¿En qué se diferencian getSchedule y findMeetingTimes?

La acción findMeetingTimes se parece a getSchedule en que ambas leen el estado de disponibilidad y el horario de trabajo de los usuarios y recursos especificados. Las diferencias entre las dos acciones son más obvias.

Aplicación

findMeetingTimes usa determinadas lógicas empresariales para sugerir horas de reunión y ubicaciones, como por ejemplo:

  • Asistencia obligatoria u opcional de cada entidad.
  • La naturaleza de la actividad solicitada para la hora del día.
  • La asistencia mínima necesaria para establecer el quorum de una reunión.

Es adecuado para los escenarios que dependen de la optimización de la reserva de citas.

getSchedule simplemente devuelve el estado de disponibilidad de los eventos existentes en cada uno de los calendarios solicitados durante un período de tiempo específico y asume que el tiempo restante está libre. Tendría que recurrir a más lógicas empresariales para hacer mejor uso de estos datos y completar el escenario.

Compatibilidad solo para la aplicación

findmeetingtimes solo admite escenarios delegados que requieren que un usuario haya iniciado sesión en la aplicación. La aplicación solo puede leer eventos en los calendarios a los que tenga acceso el usuario que haya iniciado sesión. Esto puede incluir los calendarios que otros usuarios hayan delegado o compartido con el usuario que ha iniciado sesión.

getSchedule admite tanto escenarios delegados como los que son solo para la aplicación. En los segundos, un administrador consiente que la aplicación tenga acceso a todos los calendarios sin que un usuario haya iniciado sesión.

Permisos

Los permisos con menos privilegios necesarios para findmeetingtimes es Calendars.Read.Shared.

Los permisos con menos privilegios necesarios para getSchedule son Calendars.Read.

Soporte de versión

findmeetingtimes y getSchedule están disponibles de forma general y son adecuados para su uso en aplicaciones de producción.

Datos de eventos devueltos

Los permisos con menos privilegios necesarios para getSchedule para una aplicación para obtener información de disponibilidad son Calendars.Read. Según el escenario de la aplicación, esto lo puede aprobar el administrador o el usuario que hayan iniciado sesión.

Aunque el permiso consentido permite a una aplicación usar getSchedule en calendarios de usuario solicitados a través de Outlook, el usuario solicitado controla qué datos del evento devuelve getSchedule, en caso de que devuelva alguno.

Por ejemplo, getSchedule puede devolver el estado de disponibilidad y las horas de trabajo de los usuarios solicitados o también puede devolver las propiedades asunto, ubicación y isPrivate de un evento, siempre que:

  • el evento esté marcado con el nivel de confidencialidad bajo, normal o personal, y se den una o más de las condiciones siguientes:

    • la configuración del calendario del usuario solicitado permite al usuario que haya iniciado sesión ver las líneas de asunto y ubicaciones
    • el calendario del usuario solicitado se comparte con el usuario que ha iniciado sesión;

Estas condiciones se aplican tanto si el usuario que ha iniciado sesión es un administrador de la organización como si no lo es. El usuario solicitado tiene control sobre los datos de evento devueltos.

Representación de zona horaria

De forma predeterminada, las horas de inicio y finalización de los elementos devueltos de programación se representan en UTC. Puede usar un encabezado Prefer para especificar la zona horaria correspondiente a la aplicación. Por ejemplo:

Prefer: outlook.timezone="Pacific Standard Time"

Límites y condiciones de error

Tenga en cuenta los siguientes límites y condiciones de error:

  • getSchedule admite la búsqueda de información de disponibilidad para un máximo de 20 entidades a la vez. Este límite se aplica el número de usuarios identificados de forma individual o como miembros de una lista de distribución, así como al número de recursos.
  • El período de tiempo para buscar debe ser inferior a 62 días.
  • Si getSchedule no puede identificar un usuario o recurso específico, devuelve un elemento de programación única e indica el error.

Contenido relacionado