Obtener la programación de disponibilidad de usuarios y recursosGet free/busy schedule of users and resources

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.In a work or school setting, a common scenario is to see when a user is free for meeting, or to browse the availability of a team, room, or equipment for a time period.

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.The getSchedule action lets you get the availability information of one or more entities - users, distribution lists, or resources - for a specific period of time.

EjemploExample

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:A simple example is to find the free/busy schedule of a coworker, Alex, on a specific day, from 9am to 6pm, Pacific Standard Time:

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

{        
    "Schedules": ["AlexW@contoso.OnMicrosoft.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.getSchedule returns two schedule items that match existing events in Alex' default calendar, showing the start and end times of each event and its free/busy status. Puede suponer que Miguel está disponible durante el tiempo restante en ese intervalo de fecha y hora.You can assume Alex is free for the remaining time in that date/time range.

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.OnMicrosoft.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.Apart from the free/busy schedule and working hours of Alex, getSchedule also returns availabilityView, which is a merged view of Alex' availability for that day. 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:The merged view is a string that consists of time slots covering that day, with each time slot indicating Alex' availability using the following convention:

  • 0= disponible0= free
  • 1= provisional1= tentative
  • 2= ocupado2= busy
  • 3= fuera de la oficina3= out of office
  • 4= trabajando en otro sitio.4= working elsewhere.

De forma predeterminada, cada intervalo de tiempo es de 30 minutos.By default, the length of each time slot is 30 minutes. Este ejemplo usa la propiedad availabilityViewInterval para personalizar el intervalo de tiempo y que sea de 15 minutos.This example uses the availabilityViewInterval property to customize the time slot to be 15 minutes.

¿En qué se diferencian getSchedule y findMeetingTimes?How does getSchedule compare with 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.The findMeetingTimes action is similar to getSchedule in that both read the free/busy status and working hours of specified users and resources. Las diferencias entre las dos acciones son más obvias.The two actions differ in a few major ways.

AplicaciónApplication

findMeetingTimes usa determinadas lógicas empresariales para sugerir horas de reunión y ubicaciones, como por ejemplo:findMeetingTimes applies certain business logic to suggest meeting times and locations, such as:

  • Asistencia obligatoria u opcional de cada entidad.Optional or mandatory attendance of each entity
  • La naturaleza de la actividad solicitada para la hora del día.The nature of the requested activity for the time of the day
  • La asistencia mínima necesaria para establecer el quorum de una reunión.The minimum attendance required for a quorum for a meeting

Es adecuado para los escenarios que dependen de la optimización de la reserva de citas.It is appropriate for scenarios that depend on streamlining appointment booking.

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.getSchedule simply returns the free/busy status of existing events in each of the requested calendars for a given time period, and assumes the remaining time in that time period to be free. Tendría que recurrir a más lógicas empresariales para hacer mejor uso de estos datos y completar el escenario.You would then apply further business logic to make use of this data to complete your scenario.

Compatibilidad solo para la aplicaciónApp-only support

findmeetingtimes solo admite escenarios delegados que requieren que un usuario haya iniciado sesión en la aplicación.findmeetingtimes supports only delegated scenarios which require a user to have signed in to the app. La aplicación solo puede leer eventos en los calendarios a los que tenga acceso el usuario que haya iniciado sesión.The app can read events in only the calendars that the signed-in user can access. Esto puede incluir los calendarios que otros usuarios hayan delegado o compartido con el usuario que ha iniciado sesión.This can include calendars that other users have delegated or shared with the signed-in user.

getSchedule admite tanto escenarios delegados como los que son solo para la aplicación.getSchedule supports both delegated and app-only scenarios. En los segundos, un administrador consiente que la aplicación tenga acceso a todos los calendarios sin que un usuario haya iniciado sesión.In the latter, an administrator consents the app to access all calendars without a signed-in user.

PermisosPermissions

Los permisos con menos privilegios necesarios para findmeetingtimes es Calendars.Read.Shared.The least privileged permissions required by findmeetingtimes is Calendars.Read.Shared.

Los permisos con menos privilegios necesarios para getSchedule son Calendars.Read.The least privileged permission required by getSchedule is Calendars.Read.

Soporte de versiónVersion support

findmeetingtimes y getSchedule están disponibles de forma general y son adecuados para su uso en aplicaciones de producción.findmeetingtimes and getSchedule are both generally available and appropriate for use in production apps.

Datos de eventos devueltosEvent data returned

Los permisos con menos privilegios necesarios para getSchedule para una aplicación para obtener información de disponibilidad son Calendars.Read.The least privileged permission required by getSchedule for an app to get free/busy information is Calendars.Read. Según el escenario de la aplicación, esto lo puede aprobar el administrador o el usuario que hayan iniciado sesión.Depending on your app scenario, this can be consented by the signed-in user or administrator.

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.While the consented permission lets an app use getSchedule on the requested users' calendars, through Outlook, the requested user controls which event data, if any, that getSchedule returns.

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:For example, getSchedule can return the free/busy status and working hours of the requested users, or it can also return the subject, location, and isPrivate properties of an event, provided that:

  • el evento esté marcado con el nivel de confidencialidad bajo, normal o personal, y se den una o más de las condiciones siguientes:The event is marked with low sensitivity level - normal or personal - AND one or more of the following conditions apply:

    • la configuración del calendario del usuario solicitado permite al usuario que haya iniciado sesión ver las líneas de asunto y ubicacionesThe requested user’s calendar settings allow the signed-in user to view subject lines and locations
    • el calendario del usuario solicitado se comparte con el usuario que ha iniciado sesión;The requested user’s calendar is shared with the signed-in user

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.These conditions apply regardless of whether the signed-in user is an administrator in the organization. El usuario solicitado tiene control sobre los datos de evento devueltos.The requested user has control over the event data returned.

Representación de zona horariaTime zone representation

De forma predeterminada, las horas de inicio y finalización de los elementos devueltos de programación se representan en UTC.By default, the start and end times of the returned schedule items are represented in UTC. Puede usar un encabezado Prefer para especificar la zona horaria correspondiente a la aplicación.You can use a Prefer header to specify a time zone appropriate for your app. Por ejemplo:As an example:

Prefer: outlook.timezone="Pacific Standard Time"

Límites y condiciones de errorLimits and error conditions

Tenga en cuenta los siguientes límites y condiciones de error:Be aware of the following limits and error condition:

  • getSchedule admite la búsqueda de información de disponibilidad para un máximo de 20 entidades a la vez.getSchedule can support looking up free/busy information for up to 20 entities at once. 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.This limit applies to the number of users identified individually or as members of a distribution list, and to the number of resources as well.
  • El período de tiempo para buscar debe ser menos de 42 días.The time period to look up must be less than 42 days.
  • Si getSchedule no puede identificar un usuario o recurso específico, devuelve un elemento de programación única e indica el error.If getSchedule cannot identify a specified user or resource, it returns a single schedule item and indicates the error.

Vea tambiénSee also