utilisateur : findMeetingTimesuser: findMeetingTimes

Suggérez des heures et des lieux de réunion proposés en fonction de la disponibilité de l’organisateur et des participants, des contraintes géographiques et des impératifs de temps spécifiés dans les paramètres.Suggest meeting times and locations based on organizer and attendee availability, and time or location constraints specified as parameters.

Si findMeetingTimes ne peut proposer aucune heure de réunion, la réponse renvoyée en indique la raison dans la propriété emptySuggestionsReason. Grâce à cette valeur, vous pouvez ajuster les paramètres et appeler findMeetingTimes une nouvelle fois.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.

L’algorithme utilisé pour suggérer des heures et lieux de réunion subit de temps à autre un réglage précis.The algorithm used to suggest meeting times and locations undergoes fine-tuning from time to time. Dans des scénarios, tels que des environnements de test où les paramètres d’entrée et les données de calendrier restent statiques, attendez-vous à ce que les résultats suggérés varient au fil du temps.In scenarios like test environments where the input parameters and calendar data remain static, expect that the suggested results may differ over time.

AutorisationsPermissions

L’une des autorisations suivantes est nécessaire pour appeler cette API. Pour plus d’informations, notamment sur la façon de choisir les autorisations, voir Autorisations.One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

Type d’autorisationPermission type Autorisations (de celle qui offre le plus de privilèges à celle qui en offre le moins)Permissions (from least to most privileged)
Déléguée (compte professionnel ou scolaire)Delegated (work or school account) Calendars.Read.Shared, Calendars.ReadWrite.SharedCalendars.Read.Shared, Calendars.ReadWrite.Shared
Déléguée (compte Microsoft personnel)Delegated (personal Microsoft account) Non prise en charge.Not supported.
ApplicationApplication Non prise en charge.Not supported.

Requête HTTPHTTP request

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

En-têtes de demandeRequest headers

NomName ValeurValue
AutorisationAuthorization Porteur {token}. Obligatoire.Bearer {token}. Required.
Prefer: outlook.timezonePrefer: outlook.timezone Chaîne représentant le fuseau horaire de la réponse, par exemple « Pacifique » (PST). Facultatif. L’heure UTC est utilisée si cet en-tête n’est pas spécifié.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.

Corps de la demandeRequest body

Le tableau suivant répertorie tous les paramètres pris en charge. En fonction de votre scénario, spécifiez un objet JSON pour chaque paramètre requis dans le corps de la demande.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.

ParamètreParameter TypeType DescriptionDescription
attendeesattendees Collection attendeeBaseattendeeBase collection Collection des participants ou des ressources de la réunion. Étant donné que findMeetingTimes suppose que la présence de tout participant qui est une personne est toujours obligatoire, spécifiez required pour une personne et resource pour une ressource dans la propriété type correspondante. Si la collection est vide, findMeetingTimes recherche des créneaux de disponibilité pour l’organisateur uniquement. Facultatif.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 Spécifiez True si la participation de l’organisateur n’est pas obligatoire. La valeur par défaut est false. Facultatif.Specify True if the organizer doesn't necessarily have to attend. The default is false. Optional.
locationConstraintlocationConstraint locationConstraintlocationConstraint Exigences de l’organisateur concernant le lieu de la réunion, par exemple, si le lieu de la réunion doit être proposé ou s’il existe des lieux spécifiques où la réunion doit uniquement avoir lieu. Facultatif.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 Nombre maximal de propositions d’heures de réunion à renvoyer. Facultatif.The maximum number of meeting time suggestions to be returned. Optional.
meetingDurationmeetingDuration Edm.DurationEdm.Duration Durée de la réunion, indiquée au format ISO8601. Par exemple, 1 heure est indiquée « PT1H », où « P » est l’indicateur de la durée, « T » l’indicateur du fuseau et « H » l’indicateur de l’heure. M permet d’indiquer les minutes pour la durée ; par exemple, 2 heures et 30 minutes serait « PT2H30M ». Si aucune durée n’est spécifiée, findMeetingTimes indique par défaut une durée de 30 minutes. Facultatif.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 Niveau de probabilité minimal de participation requis pour un créneau horaire, à renvoyer dans la réponse. Il s’agit d’un pourcentage compris entre 0 et 100. Facultatif.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 Spécifiez True pour renvoyer la raison de chaque proposition de réunion dans la propriété suggestionReason. false est la valeur par défaut, si vous ne souhaitez pas renvoyer cette propriété. Facultatif.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 Toute restriction de date et d’heure pour une réunion, ce qui peut inclure la nature de la réunion (propriété activityDomain) et les créneaux horaires possibles pour la réunion (propriété timeSlots). findMeetingTimes définit activityDomain sur la valeur work si vous ne spécifiez pas ce paramètre. Facultatif.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.

Le tableau suivant décrit les restrictions activityDomain, que vous pouvez spécifier dans le paramètre timeConstraint.The following table describes the activityDomain restrictions you can further specify in the timeConstraint parameter.

Valeur d’activityDomainactivityDomain value Suggestions pour les heures de réunionSuggestions for meeting times
travailwork Les suggestions sont comprises dans les heures de travail de l’utilisateur qui sont définies dans la configuration du calendrier de l’utilisateur. Elles peuvent être personnalisées par l’utilisateur ou un administrateur. Les heures de travail par défaut sont du lundi au vendredi, de 8 heures à 17 heures dans le fuseau horaire défini pour la boîte aux lettres. Il s’agit de la valeur par défaut si aucune valeur n’est spécifiée pour 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 Les suggestions sont comprises dans les heures de travail de l’utilisateur, y compris le samedi et le dimanche. La valeur par défaut est de lundi à dimanche, de 8 heures à 17 heures dans le fuseau horaire défini pour la boîte aux lettres.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.
unrestrictedunrestricted Les suggestions peuvent correspondre à n’importe quelle heure de la journée, tous les jours de la semaine.Suggestions can be from all hours of a day, all days of a week.
unknownunknown N’utilisez pas cette valeur qui deviendra obsolète dans le futur. Cette valeur se comporte actuellement comme la valeur work. Modifiez le code existant afin d’utiliser work, personal ou unrestricted selon le cas.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.

Selon les paramètres spécifiés,findMeetingTimes vérifie la disponibilité dans les calendriers principaux de l’organisateur et des participants. L’action calcule les heures de réunion les mieux adaptées et renvoie les suggestions de réunion.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.

RéponseResponse

En cas de réussite, cette méthode renvoie le code de réponse 200 OK et un objet meetingTimeSuggestionsResult dans le corps de la réponse.If successful, this method returns 200 OK response code and a meetingTimeSuggestionsResult in the response body.

L’objet meetingTimeSuggestionsResult inclut une collection de suggestions de réunion et une propriété emptySuggestionsReason. Dans chaque suggestion, intitulée meetingTimeSuggestion, les participants indiquent en moyenne un niveau de probabilité de participation de 50 %, ou un pourcentage spécifique dans le paramètre 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.

Par défaut, chaque suggestion de réunion est renvoyée au format UTC.By default, each meeting time suggestion is returned in UTC.

Si findMeetingTimes ne peut proposer aucune heure de réunion, la réponse renvoyée en indique la raison dans la propriété emptySuggestionsReason. Grâce à cette valeur, vous pouvez ajuster les paramètres et appeler findMeetingTimes une nouvelle fois.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.

Niveau de probabilité d’une suggestion de réunionThe confidence of a meeting suggestion

La propriété confidence d’un objet meetingTimeSuggestion est comprise entre 0 % et 100 %. Elle représente la probabilité de participation de tous les participants, en fonction de leurs disponibilités :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:

  • Pour chaque participant, le statut « disponible » pour le créneau horaire spécifié correspond à un niveau de probabilité de participation de 100 %, le statut « inconnu » à 49 % et le statut « occupé » à 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%.
  • Pour calculer le niveau de probabilité d’une suggestion de réunion, on calcule la moyenne du niveau de probabilité de participation indiqué par les participants pour cette réunion.The confidence of a meeting time suggestion is computed by averaging the chance of attendance over all the attendees specified for that meeting.
  • Vous pouvez utiliser le paramètre facultatif minimumAttendeePercentage pour findMeetingTimes pour que seules les suggestions de réunion possédant un certain niveau de probabilité soient renvoyées. Par exemple, vous pouvez spécifier un minimumAttendeePercentage de 80 % si vous souhaitez uniquement recevoir les suggestions ayant un niveau de probabilité de participation de 80 % ou plus. Si vous ne spécifiez pas minimumAttendeePercentage, findMeetingTimes affiche par défaut une valeur 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%.
  • En cas de suggestions de réunion multiples, l’action findMeetingTimes organise les suggestions dans l’ordre décroissant en fonction de la valeur de probabilité calculée. En cas de suggestions possédant le même niveau de probabilité, l’action les organise dans l’ordre chronologique.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.

Par exemple, si une suggestion de réunion implique 3 participants qui indiquent les informations de disponibilité suivantes :As an example, if a meeting time suggestion involves 3 attendees with the following free/busy status:

ParticipantAttendee Informations de disponibilitéFree/busy status Probabilité de participation (%)% Chance of attendance
DanaDana GratuitFree 100 %100%
NoëlJohn InconnuUnknown 49 %49%
SamanthaSamantha Occupé(e)Busy 0 %0%

Ainsi, le niveau de probabilité de la suggestion de réunion, qui correspond à la probabilité moyenne de participation, est (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 vous spécifiez un minimumAttendeePercentage de 80 % dans une opération findMeetingTimes, l’opération ne proposera pas cette heure dans la réponse car 49,66 % < 80 %.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.

ExempleExample

L’exemple suivant montre comment trouver une heure pour se réunir à un lieu prédéterminé et demander une raison pour chaque proposition, en spécifiant les paramètres suivants dans le corps de la requête :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

En définissant le paramètre returnSuggestionReasons, vous obtenez également une description pour chaque proposition dans la propriété suggestionReason, si findMeetingTimes renvoie une suggestion.By setting the returnSuggestionReasons parameter, you also get an explanation in the suggestionReason property for each suggestion, if findMeetingTimes returns any suggestion.

Notez que la demande spécifie une heure du fuseau horaire PST.Notice that the request specifies time in the PST time zone. Par défaut, la réponse renvoie des suggestions d’heure de réunion en heure UTC.By default, the response returns meeting time suggestions in UTC. Vous pouvez utiliser l’en-tête de demande Prefer: outlook.timezone pour afficher dans la réponse les valeurs horaires proposées au format PST.You can use the Prefer: outlook.timezone request header to specify PST as well for the time values in the response.

DemandeRequest

Voici l’exemple de demande.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"
}
RéponseResponse

Voici un exemple de réponse. Remarque : l’objet de réponse illustré ici peut-être tronqué à des fins de concision. Toutes les propriétés sont renvoyées à partir d’un appel réel.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"
                }
            }
        }
    ]
}