Buscar horas posibles para una reunión en el Calendario de Outlook
Buscar un horario y un lugar comunes para reunirse en un área profesional o académica a menudo conlleva sobrecargas. Las aplicaciones de Microsoft Graph pueden usar findMeetingTimes para identificar las posibles horas de reunión que satisfagan la hora, la ubicación y otras restricciones.
La acción findMeetingTimes permite especificar condiciones como el intervalo de fecha y hora de la reunión, la duración, los asistentes opcionales o necesarios y la naturaleza de la actividad (activityDomain). La acción tiene en cuenta las programaciones de trabajo normales y el estado de disponibilidad de los asistentes y organizadores, y sugiere tiempos adecuados para los participantes y el tipo de actividad. Por ejemplo, las sugerencias para una actividad relacionada con el trabajo siempre se producen durante las horas de trabajo del organizador y los asistentes, y las sugerencias donde los asistentes necesarios están disponibles se ordenan más arriba en la lista sugerida.
En Microsoft 365, las horas de trabajo y las zonas horarias se pueden configurar por buzón. La acción findMeetingTimes controla las variaciones de zona horaria entre el organizador y los asistentes. De forma predeterminada, findMeetingTimes devuelve sugerencias en UTC. Puede usar el siguiente encabezado de solicitud para que findMeetingTimes devuelva sugerencias expresadas en una zona horaria específica.
Prefer: outlook.timezone="{time-zone-string}}"
Es posible especificar un porcentaje (minimumAttendeePercentage) para un cuórum y hacer que findMeetingTimes devuelva sugerencias solo si está disponible un número mínimo de asistentes, lo que es especialmente útil para reuniones de mayor tamaño.
Si findMeetingTimes no puede sugerir ninguna hora de reunión, indica un motivo específico (emptySuggestionsReason), como el organizador o un asistente necesario que no está disponible. Basándose en este valor, se pueden ajustar mejor los parámetros y llamar otra vez a findMeetingTimes.
Nota:
La acción findMeetingTimesestá actualmente disponible para los buzones profesionales o educativos de Microsoft 365, pero no para los buzones personales, outlook.com.
Ejemplo
En el ejemplo siguiente se muestra cómo usar findMeetingTimes para devolver las horas posibles para que dos usuarios se reúnan durante un par de horas, teniendo en cuenta las programaciones de disponibilidad y trabajo de los usuarios y el asistente que se encuentra fuera durante parte del tiempo. Dado que solo hay dos usuarios para esta reunión, las sugerencias requieren una asistencia del 100 %. A continuación se muestra la programación de disponibilidad de los usuarios.
Calendario del organizador
Calendario de los asistentes
El ejemplo realiza dos llamadas a findMeetingTimes:
- La primera llamada se examina en el intervalo de fechas del 18 al 20 de abril. Dado que el asistente está fuera de la oficina del 18 al 19 de abril y no hay tiempo disponible habitualmente el 20 de abril, la primera llamada no devuelve sugerencias con el motivo (emptySuggestionsReason) de que los asistentes no están disponibles.
- La segunda llamada busca la disponibilidad el 21 de abril y devuelve una sugerencia de las 14 a las 16 horas.
Las dos llamadas a findMeetingTimes incluyen los parámetros siguientes. Todos los parámetros de findMeetingTimes son opcionales .
-
asistentes: uno de los asistentes, Naiara Padilla, se establece como
requiredde la propiedad type - locationConstraint: no se requiere ninguna sugerencia de ubicación
- timeConstraint: la primera llamada se busca en el rango de fechas o intervalo horario del 18 de abril a las 9 horas al 20 de abril a las 17 horas; después de que la primera llamada falla al sugerir horarios, la segunda llamada considera el 21 de abril de 9 a 17 horas
- meetingDuration: dos horas
- returnSuggestionReasons: en este ejemplo se requiere un motivo para cada sugerencia
- minimumAttendeePercentage: 100 %, dado que el asistente debe poder asistir en cualquier horario sugerido
Primera solicitud
Busque un intervalo de tiempo libre de dos horas para ambos usuarios entre el 18 y el 20 de abril.
POST https://graph.microsoft.com/v1.0/me/findMeetingTimes
Prefer: outlook.timezone="Pacific Standard Time"
Content-type: application/json
{
"attendees": [
{
"type": "required",
"emailAddress": {
"name": "Samantha Booth",
"address": "samanthab@contoso.com"
}
}
],
"locationConstraint": {
"isRequired": false,
"suggestLocation": false,
"locations": [
{
"resolveAvailability": false,
"displayName": "Conf room Hood"
}
]
},
"timeConstraint": {
"activityDomain":"work",
"timeslots": [
{
"start": {
"dateTime": "2017-04-18T09:00:00",
"timeZone": "Pacific Standard Time"
},
"end": {
"dateTime": "2017-04-20T17:00:00",
"timeZone": "Pacific Standard Time"
}
}
]
},
"meetingDuration": "PT2H",
"returnSuggestionReasons": true,
"minimumAttendeePercentage": 100
}
Primera respuesta
No hay ningún intervalo de tiempo de dos horas en el horario laboral del 18 al 20 de abril en el que ambos usuarios estén disponibles.
HTTP/1.1 200 OK
Content-type: application/json
Preference-Applied: outlook.timezone="Pacific Standard Time"
Content-Length: 184
{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.meetingTimeSuggestionsResult",
"emptySuggestionsReason":"AttendeesUnavailable",
"meetingTimeSuggestions":[
]
}
Segunda solicitud
Busque un intervalo de tiempo de dos horas el 21 de abril.
POST https://graph.microsoft.com/v1.0/me/findMeetingTimes
Prefer: outlook.timezone="Pacific Standard Time"
Content-type: application/json
{
"attendees": [
{
"type": "required",
"emailAddress": {
"name": "Samantha Booth",
"address": "samanthab@contoso.com"
}
}
],
"locationConstraint": {
"isRequired": false,
"suggestLocation": false,
"locations": [
{
"resolveAvailability": false,
"displayName": "Conf room Hood"
}
]
},
"timeConstraint": {
"activityDomain":"work",
"timeslots": [
{
"start": {
"dateTime": "2017-04-21T09:00:00",
"timeZone": "Pacific Standard Time"
},
"end": {
"dateTime": "2017-04-21T17:00:00",
"timeZone": "Pacific Standard Time"
}
}
]
},
"meetingDuration": "PT2H",
"returnSuggestionReasons": true,
"minimumAttendeePercentage": 100
}
Segunda respuesta
La segunda solicitud findMeetingTimes sugiere el 21 de abril de las 14 a las 16 horas para que ambos usuarios se reúnan.
HTTP/1.1 200 OK
Content-type: application/json
Preference-Applied: outlook.timezone="Pacific Standard Time"
Content-Length: 714
{
"@odata.context":"https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.meetingTimeSuggestionsResult",
"emptySuggestionsReason":"",
"meetingTimeSuggestions":[
{
"confidence":100.0,
"organizerAvailability":"free",
"suggestionReason":"Suggested because it is one of the nearest times when all attendees are available.",
"meetingTimeSlot":{
"start":{
"dateTime":"2017-04-21T14:00:00.0000000",
"timeZone":"Pacific Standard Time"
},
"end":{
"dateTime":"2017-04-21T16:00:00.0000000",
"timeZone":"Pacific Standard Time"
}
},
"attendeeAvailability":[
{
"availability":"free",
"attendee":{
"type":"required",
"emailAddress":{
"address":"samanthab@contoso.com"
}
}
}
],
"locations":[
{
"displayName":"Conf room Hood"
}
]
}
]
}
Siguientes pasos
Hay ocasiones en las que no todos los asistentes pueden asistir a una reunión. Puede hacer que findMeetingTimes sugiera una hora si la confianza para la asistencia alcanza un porcentaje determinado, especificando el parámetro opcional minimumAttendeePercentage . Obtenga más información sobre la confianza de una sugerencia de reunión y otros parámetros, y aplíquelos según corresponda para reuniones de tamaños más grandes.
Después de recibir sugerencias de tiempo de reunión, es posible que desee:
Obtenga más información sobre la integración con el Calendario de Outlook.