Compartir a través de

user: findMeetingTimes

  • Artículo

Espacio de nombres: microsoft.graph

Importante

Las API de la versión /beta de Microsoft Graph están sujetas a cambios. No se admite el uso de estas API en aplicaciones de producción. Para determinar si una API está disponible en la versión 1.0, use el selector de Versión.

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.

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.

El algoritmo para recomendar las horas y las ubicaciones de las reuniones se somete a ajustes periódicamente. 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.

Esta API está disponible en las siguientes implementaciones nacionales de nube.

Servicio global Gobierno de EE. UU. L4 Us Government L5 (DOD) China operada por 21Vianet
✅ ✅ ✅ ✅

Permissions

Elija el permiso o los permisos marcados como con privilegios mínimos para esta API. Use un permiso o permisos con privilegios superiores solo si la aplicación lo requiere. Para obtener más información sobre los permisos delegados y de aplicación, consulte Tipos de permisos. Para obtener más información sobre estos permisos, consulte la referencia de permisos.

Tipo de permiso Permisos con privilegios mínimos Permisos con privilegios más altos
Delegado (cuenta profesional o educativa) Calendars.Read.Shared Calendars.ReadWrite.Shared
Delegado (cuenta personal de Microsoft) No admitida. No admitida.
Aplicación No admitida. No admitida.

Solicitud HTTP

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

Encabezados de solicitud

Nombre Valor
Authorization {token} de portador. Obligatorio. Obtenga más información sobre la autenticación y la autorización.
Prefer: outlook.timezone Una cadena que representa una zona horaria concreta para la respuesta, por ejemplo, "Hora estándar del Pacífico". Opcional. Se usa UTC si no se especifica este encabezado.

Cuerpo de solicitud

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.

Parámetro Tipo Descripción
attendees Colección attendeeBase Una colección de los asistentes o los recursos de la reunión. En la propiedad de tipo correspondiente, especifique required o optional para una persona y resource para un recurso como sala de reuniones. Si no se especifica, se supone que findMeetingTimesrequired para la propiedad type . Una colección vacía hace que findMeetingTimes busque intervalos de tiempo libres solo para el organizador. Opcional.
isOrganizerOptional Edm.Boolean Especifique True si el organizador no tiene que asistir necesariamente. El valor predeterminado es false. Opcional.
locationConstraint locationConstraint 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.
maxCandidates Edm.Int32 El número máximo de sugerencias de hora de la reunión que se va a devolver. Opcional.
meetingDuration Edm.Duration La duración de la reunión, indicada en formato ISO 8601 . 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 minutos durante el tiempo; por ejemplo, 2 horas y 30 minutos serían "PT2H30M". Si no se especifica ninguna duración de la reunión, findMeetingTimes usa el valor predeterminado de 30 minutos. Opcional.
minimumAttendeePercentage Edm.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.
returnSuggestionReasons Edm.Boolean Especifique True para devolver un motivo para cada sugerencia de reunión en la propiedad suggestionReason . El valor predeterminado es false para que no se devuelva esa propiedad. Opcional.
timeConstraint timeConstraint Cualquier restricción de tiempo para una reunión, que puede incluir la naturaleza de la reunión (propiedad activityDomain ) y posibles períodos de tiempo de reunión (propiedad timeSlots ). findMeetingTimes asume activityDomain como work si no especificara este parámetro. Opcional.

En la tabla siguiente se describen las restricciones puede especificar en el parámetro timeConstraint.

valor activityDomain en timeConstraint Sugerencias de horas para reuniones
trabajo Las sugerencias se encuentran dentro del horario laboral del usuario que se definen en la configuración del calendario del usuario y pueden personalizarse por el usuario o el administrador. El horario de trabajo predeterminado es de lunes a viernes de 8 a.m. a 5 p.m. en la zona horaria configurada para el buzón. Este es el valor predeterminado si no se especifica activityDomain .
personal Las sugerencias están dentro del horario laboral del usuario, y los sábados y domingos. El valor predeterminado es de lunes a domingo, de 8:00 a 17:00, en la configuración de zona horaria del buzón.
sin restricciones Las sugerencias pueden pertenecer a cualquier hora del día, todos los días de la semana.
desconocido No use este valor, ya que estará en desuso en el futuro. Actualmente se comporta igual workque . Cambie cualquier código existente para usar work, personal o unrestricted según corresponda.

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.

Respuesta

Si es correcto, este método devuelve un código de respuesta 200 OK y un objeto meetingTimeSuggestionsResult en el cuerpo de la respuesta.

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.

De forma predeterminada, cada sugerencia de hora de la reunión se devuelve en formato 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.

La confianza de una sugerencia de la reunión

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:

  • 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 %.
  • 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.
  • 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.
  • 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 %.

Por ejemplo, si una sugerencia de hora de la reunión implica tres asistentes con el siguiente estado de disponibilidad:

Asistente Estado de disponibilidad Posibilidades de asistencia (%)
Dana Libre 100 %
Pelayo Desconocido 49 %
Naiara Ocupado 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 %.

Si especifica un valor minimumAttendeePercentage del 80 % en una operación findMeetingTimes , ya que el 49,66 % < es el 80 %, la operación no sugerirá esta vez en la respuesta.

Ejemplo

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:

  • attendees
  • locationConstraint
  • timeConstraint
  • isOrganizerOptional
  • meetingDuration
  • returnSuggestionReasons
  • minimumAttendeePercentage

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.

Observe que la solicitud especifica la hora en la zona horaria PST. De forma predeterminada, la respuesta devuelve las sugerencias para la hora de la reunión en la zona horaria 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.

Solicitud

Aquí está la solicitud de ejemplo.

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

{
  "attendees": [
    {
      "type": "required",
      "emailAddress": {
        "name": "Alex Wilbur",
        "address": "alexw@contoso.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
}
Respuesta

Esta es una solicitud de ejemplo. Nota: el objeto de respuesta que se muestra aquí puede haberse acortado para mejorar la legibilidad.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$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.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.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.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.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.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"
                }
            }
        }
    ]
}