user: findMeetingTimesuser: findMeetingTimes

Sugiera las horas y ubicaciones de las reuniones en función de la disponibilidad del organizador y los asistentes, y especifique como parámetros las restricciones de tiempo o de ubicación.Suggest meeting times and locations based on organizer and attendee availability, and time or location constraints specified as parameters.

Si findMeetingTimes no puede devolver sugerencias de reunión, la respuesta podría indicar un motivo en la propiedad emptySuggestionsReason. Basándose en este valor, se pueden ajustar mejor los parámetros y llamar otra vez a findMeetingTimes.If findMeetingTimes cannot return any meeting suggestions, the response would indicate a reason in the emptySuggestionsReason property. Based on this value, you can better adjust the parameters and call findMeetingTimes again.

El algoritmo para recomendar las horas y las ubicaciones de las reuniones se somete a ajustes periódicamente.The algorithm used to suggest meeting times and locations undergoes fine-tuning from time to time. En escenarios como los entornos de prueba en los que los parámetros de entrada y los datos del calendario siguen siendo estáticos, cuente con que los resultados sugeridos pueden diferir con el tiempo.In scenarios like test environments where the input parameters and calendar data remain static, expect that the suggested results may differ over time.

PermisosPermissions

Se requiere uno de los siguientes permisos para llamar a esta API. Para obtener más información, incluido cómo elegir permisos, vea Permisos.One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Tipo de permisoPermission type Permisos (de menos a más privilegiados)Permissions (from least to most privileged)
Delegado (cuenta profesional o educativa)Delegated (work or school account) Calendars.Read.Shared, Calendars.ReadWrite.SharedCalendars.Read.Shared, Calendars.ReadWrite.Shared
Delegado (cuenta personal de Microsoft)Delegated (personal Microsoft account) No admitida.Not supported.
AplicaciónApplication No admitida.Not supported.

Solicitud HTTPHTTP request

POST /me/findMeetingTimes
POST /users/{id|userPrincipalName}/findMeetingTimes

Encabezados de solicitudRequest headers

NombreName ValorValue
AuthorizationAuthorization {token} de portador. Obligatorio.Bearer {token}. Required.
Prefer: outlook.timezonePrefer: outlook.timezone Una cadena que representa una zona horaria concreta para la respuesta, por ejemplo, "Hora estándar del Pacífico". Opcional. Se utiliza la hora UTC si no se especifica este encabezado.A string representing a specific time zone for the response, for example, "Pacific Standard Time". Optional. UTC is used if this header is not specified.

Cuerpo de solicitudRequest body

Todos los parámetros admitidos se enumeran a continuación. Dependiendo de su escenario, especifique un objeto JSON para cada uno de los parámetros necesarios en el cuerpo de la solicitud.All the supported parameters are listed below. Depending on your scenario, specify a JSON object for each of the necessary parameters in the request body.

ParámetroParameter TipoType DescripciónDescription
attendeesattendees Colección attendeeBaseattendeeBase collection Una colección de los asistentes o los recursos de la reunión. Puesto que findMeetingTimes supone que cualquier asistente que sea una persona siempre es necesario, especifique required para una persona y resource para un recurso en la propiedad tipo correspondiente. Una colección vacía hace que findMeetingTimes busque intervalos de tiempo libres solo para el organizador. Opcional.A collection of attendees or resources for the meeting. Since findMeetingTimes assumes that any attendee who is a person is always required, specify required for a person and resource for a resource in the corresponding type property. An empty collection causes findMeetingTimes to look for free time slots for only the organizer. Optional.
isOrganizerOptionalisOrganizerOptional Edm.BooleanEdm.Boolean Especificar True si no es preciso que el organizador asista. El valor predeterminado es false. Opcional.Specify True if the organizer doesn't necessarily have to attend. The default is false. Optional.
locationConstraintlocationConstraint locationConstraintlocationConstraint Los requisitos del organizador sobre la ubicación de la reunión, por ejemplo si se requiere una sugerencia para una ubicación de la reunión o si hay ubicaciones específicas en las que únicamente pueda tener lugar la reunión. Opcional.The organizer's requirements about the meeting location, such as whether a suggestion for a meeting location is required, or there are specific locations only where the meeting can take place. Optional.
maxCandidatesmaxCandidates Edm.Int32Edm.Int32 El número máximo de sugerencias de hora de la reunión que se va a devolver. Opcional.The maximum number of meeting time suggestions to be returned. Optional.
meetingDurationmeetingDuration Edm.DurationEdm.Duration La duración de la reunión en formato ISO8601. Por ejemplo, 1 hora se indica como "PT1H", donde "P" es el designador de duración, "T" es el designador de tiempo y "H" es el designador de hora. Use M para indicar los minutos de la duración; por ejemplo, 2 horas y 30 minutos sería "PT2H30M". Si no se especifica ninguna duración de la reunión, findMeetingTimes usa el valor predeterminado de 30 minutos. Opcional.The length of the meeting, denoted in ISO8601 format. For example, 1 hour is denoted as 'PT1H', where 'P' is the duration designator, 'T' is the time designator, and 'H' is the hour designator. Use M to indicate minutes for the duration; for example, 2 hours and 30 minutes would be 'PT2H30M'. If no meeting duration is specified, findMeetingTimes uses the default of 30 minutes. Optional.
minimumAttendeePercentageminimumAttendeePercentage Edm.DoubleEdm.Double La confianza mínima necesaria para que se devuelva un intervalo de tiempo en la respuesta. Es un valor de porcentaje (%) comprendido entre 0 y 100. Opcional.The minimum required confidence for a time slot to be returned in the response. It is a % value ranging from 0 to 100. Optional.
returnSuggestionReasonsreturnSuggestionReasons Edm.BooleanEdm.Boolean Especifique True para devolver un motivo para cada sugerencia de la reunión en la propiedad suggestionReason. El valor predeterminado es false para no devolver esa propiedad. Opcional.Specify True to return a reason for each meeting suggestion in the suggestionReason property. The default is false to not return that property. Optional.
timeConstrainttimeConstraint timeConstrainttimeConstraint Las restricciones de tiempo para una reunión, que pueden incluir la naturaleza de la reunión (propiedad activityDomain) y posibles periodos de tiempo de la reunión (propiedad timeSlots). findMeetingTimes asume activityDomain como work si no especifica este parámetro. Opcional.Any time restrictions for a meeting, which can include the nature of the meeting (activityDomain property) and possible meeting time periods (timeSlots property). findMeetingTimes assumes activityDomain as work if you don't specify this parameter. Optional.

En la tabla siguiente se describen las restricciones de activityDomain que puede especificar hasta ahora en el parámetro timeConstraint.The following table describes the activityDomain restrictions you can further specify in the timeConstraint parameter.

valor de activityDomainactivityDomain value Sugerencias de horas para reunionesSuggestions for meeting times
trabajowork Las sugerencias se encuentran dentro de la jornada laboral del usuario, que está definida en su configuración de calendario y tanto el administrador como el propio usuario pueden personalizar. Las horas de trabajo por defecto son de lunes a viernes, de 8 a.m. a 5 p.m. en la zona horaria establecida para el buzón. Este es el valor predeterminado si no se especifica activityDomain.Suggestions are within the user's work hours which are defined in the user’s calendar configuration and can be customized by the user or administrator. The default work hours are Monday to Friday, 8am to 5pm in the time zone set for the mailbox. This is the default value if no activityDomain is specified.
personalpersonal Las sugerencias se encuentran dentro de la jornada laboral del usuario y en sábado y domingo. El valor predeterminado es del lunes al domingo, de 8 a.m. a 5 p.m., en la configuración de zona horaria para el buzón.Suggestions are within the user's work hours, and Saturday and Sunday. The default is Monday to Sunday, 8am to 5pm, in the time zone setting for the mailbox.
sin restriccionesunrestricted Las sugerencias pueden pertenecer a cualquier hora del día, todos los días de la semana.Suggestions can be from all hours of a day, all days of a week.
desconocidounknown No utilice este valor, pues quedará obsoleto en el futuro. Actualmente se comporta igual que work. Cambie cualquier código existente para usar work, personal o unrestricted según corresponda.Do not use this value as it will be deprecated in the future. Currently behaves the same as work. Change any existing code to use work, personal or unrestricted as appropriate.

Basándose en los parámetros especificados, findMeetingTimes comprueba el estado de disponibilidad en los calendarios principales del organizador y los asistentes. La acción calcula la mejor hora de la reunión posible y devuelve cualquier sugerencia de reunión.Based on the specified parameters,findMeetingTimes checks the free/busy status in the primary calendars of the organizer and attendees. The action calculates the best possible meeting times, and returns any meeting suggestions.

RespuestaResponse

Si es correcto, este método devuelve un código de respuesta 200 OK y un objeto meetingTimeSuggestionsResult en el cuerpo de la respuesta.If successful, this method returns 200 OK response code and a meetingTimeSuggestionsResult in the response body.

Un objeto meetingTimeSuggestionsResult incluye una colección de sugerencias de la reunión y una propiedad emptySuggestionsReason. Cada sugerencia se define como una meetingTimeSuggestion, con los asistentes con un nivel de confianza medio del 50 % de asistir o un porcentaje concreto que especificó en el parámetro minimumAttendeePercentage.A meetingTimeSuggestionsResult includes a collection of meeting suggestions and an emptySuggestionsReason property. Each suggestion is defined as a meetingTimeSuggestion, with attendees having on the average a confidence level of 50% to attend, or a specific % that you have specified in the minimumAttendeePercentage parameter.

De forma predeterminada, cada sugerencia de hora de la reunión se devuelve en formato UTC.By default, each meeting time suggestion is returned in UTC.

Si findMeetingTimes no puede devolver sugerencias de reunión, la respuesta podría indicar un motivo en la propiedad emptySuggestionsReason. Basándose en este valor, se pueden ajustar mejor los parámetros y llamar otra vez a findMeetingTimes.If findMeetingTimes cannot return any meeting suggestions, the response would indicate a reason in the emptySuggestionsReason property. Based on this value, you can better adjust the parameters and call findMeetingTimes again.

La confianza de una sugerencia de la reuniónThe confidence of a meeting suggestion

La propiedad confidence de un objeto meetingTimeSuggestion oscila entre 0 % y 100 %, y representa la posibilidad de que todos los asistentes asistan a la reunión, tomando como base de su estado de disponibilidad individual:The confidence property of a meetingTimeSuggestion ranges from 0% to 100%, and represents the chance that all the attendees attend the meeting, based on each of their individual free/busy status:

  • Para cada asistente, un estado libre para una periodo de tiempo de reunión especificado se corresponde al 100 % de posibilidades de asistencia, un estado desconocido al 49 % y un estado ocupado al 0 %.For each attendee, a free status for a specified meeting time period corresponds to 100% chance of attendance, unknown status 49%, and busy status 0%.
  • La confianza de una sugerencia de hora de la reunión se calcula promediando la posibilidad de asistencia sobre todos los asistentes especificados para esa reunión.The confidence of a meeting time suggestion is computed by averaging the chance of attendance over all the attendees specified for that meeting.
  • Se puede usar el parámetro opcional minimumAttendeePercentage para findMeetingTimes para especificar que solo se devuelvan sugerencias de la hora de la reunión con al menos un nivel de confianza determinado. Por ejemplo, se puede especificar un valor minimumAttendeePercentage de 80 % si solo se quieren sugerencias que tengan una probabilidad del 80 % o más de que asistan todos los asistentes. Si no se especifica minimumAttendeePercentage, findMeetingTimes da por supuesto un valor de 50 %.You can use the minimumAttendeePercentage optional parameter for findMeetingTimes to specify only meeting time suggestions of at least certain confidence level should be returned. For example, you can specify a minimumAttendeePercentage of 80% if you want only suggestions that have an 80% chance or more that all the attendees are attending. If you do not specify minimumAttendeePercentage, findMeetingTimes assumes a value of 50%.
  • Si hay varias sugerencias de hora de la reunión, la acción findMeetingTimes ordena primero las sugerencias por su valor de confianza calculado de alto a bajo. Si hay sugerencias con la misma confianza, entonces la acción las ordena cronológicamente.If there are multiple meeting time suggestions, the findMeetingTimes action first orders the suggestions by their computed confidence value from high to low. If there are suggestions with the same confidence, the action then orders these suggestions chronologically.

Por ejemplo, si una sugerencia de hora de la reunión implica tres asistentes con el siguiente estado de disponibilidad:As an example, if a meeting time suggestion involves 3 attendees with the following free/busy status:

AsistenteAttendee Estado de disponibilidadFree/busy status Posibilidades de asistencia (%)% Chance of attendance
DanaDana LibreFree 100 %100%
PelayoJohn DesconocidoUnknown 49 %49%
NaiaraSamantha OcupadoBusy 0 %0%

Entonces la confianza de la sugerencia de hora de la reunión, que es la posibilidad media de asistencia, es (100 % + 49 % + 0 %)/3 = 49,66 %.Then the confidence of the meeting time suggestion, which is the average chance of attendance, is (100% + 49% + 0%)/3 = 49.66%.

Si especifica un valor minimumAttendeePercentage del 80 % en una operación findMeetingTimes, porque 49,66 %< 8 0%, la operación no sugerirá esta hora en la respuesta.If you specify a minimumAttendeePercentage of 80% in a findMeetingTimes operation, because 49.66% < 80%, the operation will not suggest this time in the response.

EjemploExample

En el ejemplo siguiente se muestra cómo encontrar tiempo para reunirse en un lugar determinado y solicitar un motivo para cada sugerencia, especificando los siguientes parámetros en el cuerpo de la solicitud:The following example shows how to find time to meet at a pre-determined location, and request a reason for each suggestion, by specifying the following parameters in the request body:

  • attendeesattendees
  • locationConstraintlocationConstraint
  • timeConstrainttimeConstraint
  • isOrganizerOptionalisOrganizerOptional
  • meetingDurationmeetingDuration
  • returnSuggestionReasonsreturnSuggestionReasons
  • minimumAttendeePercentageminimumAttendeePercentage

Al establecer el parámetro returnSuggestionReasons, también se obtiene una explicación en la propiedad suggestionReason de cada sugerencia, si findMeetingTimes devuelve alguna sugerencia.By setting the returnSuggestionReasons parameter, you also get an explanation in the suggestionReason property for each suggestion, if findMeetingTimes returns any suggestion.

Observe que la solicitud especifica la hora en la zona horaria PST.Notice that the request specifies time in the PST time zone. De forma predeterminada, la respuesta devuelve las sugerencias para la hora de la reunión en la zona horaria UTC.By default, the response returns meeting time suggestions in UTC. Se puede usar el encabezado de solicitud Prefer: outlook.timezone para especificar la zona horaria PST, además de para los valores de hora de la respuesta.You can use the Prefer: outlook.timezone request header to specify PST as well for the time values in the response.

SolicitudRequest

Aquí está la solicitud de ejemplo.Here is the example request.

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

{ 
  "attendees": [ 
    { 
      "type": "required",  
      "emailAddress": { 
        "name": "Alex Wilbur",
        "address": "alexw@contoso.onmicrosoft.com" 
      } 
    }
  ],  
  "locationConstraint": { 
    "isRequired": "false",  
    "suggestLocation": "false",  
    "locations": [ 
      { 
        "resolveAvailability": "false",
        "displayName": "Conf room Hood" 
      } 
    ] 
  },  
  "timeConstraint": {
    "activityDomain":"work", 
    "timeslots": [ 
      { 
        "start": { 
          "dateTime": "2019-04-16T09:00:00",  
          "timeZone": "Pacific Standard Time" 
        },  
        "end": { 
          "dateTime": "2019-04-18T17:00:00",  
          "timeZone": "Pacific Standard Time" 
        } 
      } 
    ] 
  },  
  "isOrganizerOptional": "false",
  "meetingDuration": "PT1H",
  "returnSuggestionReasons": "true",
  "minimumAttendeePercentage": "100"
}
RespuestaResponse

Esta es una solicitud de ejemplo. Nota: Es posible que el objeto de respuesta que aparezca aquí esté truncado para abreviar. Todas las propiedades se devolverán de una llamada real.Here is an example response. Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

HTTP/1.1 200 OK
Content-type: application/json
Preference-Applied: outlook.timezone="Pacific Standard Time"

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.meetingTimeSuggestionsResult",
    "emptySuggestionsReason": "",
    "meetingTimeSuggestions": [
        {
            "confidence": 100,
            "order": 1,
            "organizerAvailability": "free",
            "suggestionReason": "Suggested because it is one of the nearest times when all attendees are available.",
            "attendeeAvailability": [
                {
                    "availability": "free",
                    "attendee": {
                        "emailAddress": {
                            "address": "alexw@contoso.onmicrosoft.com"
                        }
                    }
                }
            ],
            "locations": [
                {
                    "displayName": "Conf room Hood"
                }
            ],
            "meetingTimeSlot": {
                "start": {
                    "dateTime": "2019-04-18T16:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                },
                "end": {
                    "dateTime": "2019-04-18T17:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                }
            }
        },
        {
            "confidence": 100,
            "order": 2,
            "organizerAvailability": "free",
            "suggestionReason": "Suggested because it is one of the nearest times when all attendees are available.",
            "attendeeAvailability": [
                {
                    "availability": "free",
                    "attendee": {
                        "emailAddress": {
                            "address": "alexw@contoso.onmicrosoft.com"
                        }
                    }
                }
            ],
            "locations": [
                {
                    "displayName": "Conf room Hood"
                }
            ],
            "meetingTimeSlot": {
                "start": {
                    "dateTime": "2019-04-18T08:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                },
                "end": {
                    "dateTime": "2019-04-18T09:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                }
            }
        },
        {
            "confidence": 100,
            "order": 3,
            "organizerAvailability": "tentative",
            "suggestionReason": "Suggested because it is one of the nearest times when all attendees are available.",
            "attendeeAvailability": [
                {
                    "availability": "free",
                    "attendee": {
                        "emailAddress": {
                            "address": "alexw@contoso.onmicrosoft.com"
                        }
                    }
                }
            ],
            "locations": [
                {
                    "displayName": "Conf room Hood"
                }
            ],
            "meetingTimeSlot": {
                "start": {
                    "dateTime": "2019-04-18T15:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                },
                "end": {
                    "dateTime": "2019-04-18T16:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                }
            }
        },
        {
            "confidence": 100,
            "order": 4,
            "organizerAvailability": "tentative",
            "suggestionReason": "Suggested because it is one of the nearest times when all attendees are available.",
            "attendeeAvailability": [
                {
                    "availability": "free",
                    "attendee": {
                        "emailAddress": {
                            "address": "alexw@contoso.onmicrosoft.com"
                        }
                    }
                }
            ],
            "locations": [
                {
                    "displayName": "Conf room Hood"
                }
            ],
            "meetingTimeSlot": {
                "start": {
                    "dateTime": "2019-04-18T09:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                },
                "end": {
                    "dateTime": "2019-04-18T10:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                }
            }
        },
        {
            "confidence": 100,
            "order": 5,
            "organizerAvailability": "tentative",
            "suggestionReason": "Suggested because it is one of the nearest times when all attendees are available.",
            "attendeeAvailability": [
                {
                    "availability": "free",
                    "attendee": {
                        "emailAddress": {
                            "address": "alexw@contoso.onmicrosoft.com"
                        }
                    }
                }
            ],
            "locations": [
                {
                    "displayName": "Conf room Hood"
                }
            ],
            "meetingTimeSlot": {
                "start": {
                    "dateTime": "2019-04-18T12:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                },
                "end": {
                    "dateTime": "2019-04-18T13:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                }
            }
        }
    ]
}