Partager via

user: findMeetingTimes

  • Article

Espace de noms: microsoft.graph

Importante

Les API sous la version /beta dans Microsoft Graph sont susceptibles d’être modifiées. L’utilisation de ces API dans des applications de production n’est pas prise en charge. Pour déterminer si une API est disponible dans v1.0, utilisez le sélecteur Version .

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.

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.

L’algorithme utilisé pour suggérer des heures et lieux de réunion subit de temps à autre un réglage précis. 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.

Cette API est disponible dans les déploiements de cloud national suivants.

Service global Gouvernement des États-Unis L4 Us Government L5 (DOD) Chine gérée par 21Vianet
✅ ✅ ✅ ✅

Autorisations

Choisissez l’autorisation ou les autorisations marquées comme moins privilégiées pour cette API. Utilisez une autorisation ou des autorisations privilégiées plus élevées uniquement si votre application en a besoin. Pour plus d’informations sur les autorisations déléguées et d’application, consultez Types d’autorisations. Pour en savoir plus sur ces autorisations, consultez les informations de référence sur les autorisations.

Type d’autorisation Autorisations avec privilèges minimum Autorisations privilégiées plus élevées
Déléguée (compte professionnel ou scolaire) Calendars.Read.Shared Calendars.ReadWrite.Shared
Déléguée (compte Microsoft personnel) Non prise en charge. Non prise en charge.
Application Non prise en charge. Non prise en charge.

Requête HTTP

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

En-têtes de demande

Nom Valeur
Autorisation Porteur {token}. Obligatoire. En savoir plus sur l’authentification et l’autorisation.
Prefer: outlook.timezone Chaîne représentant le fuseau horaire de la réponse, par exemple « Pacifique » (PST). Optional. L’utc est utilisé si cet en-tête n’est pas spécifié.

Corps de la demande

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.

Paramètre Type Description
attendees Collection attendeeBase Collection des participants ou des ressources de la réunion. Dans la propriété de type correspondante, spécifiez required ou optional pour une personne et resource pour une ressource telle que la salle de réunion. S’il n’est pas spécifié, findMeetingTimes suppose required pour la propriété type . Si la collection est vide, findMeetingTimes recherche uniquement les créneaux de disponibilité de l’organisateur. Optional.
isOrganizerOptional Edm.Boolean Spécifiez True si l’organisateur n’a pas nécessairement besoin d’être présent. La valeur par défaut est false. Optional.
locationConstraint locationConstraint 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. Optional.
maxCandidates Edm.Int32 Nombre maximal de propositions d’heures de réunion à renvoyer. Optional.
meetingDuration Edm.Duration Durée de la réunion, indiquée au format ISO 8601 . Par exemple, 1 heure est désignée comme « PT1H », où « P » est l’identificateur de durée, « T » est l’identificateur de temps et « H » est l’identificateur d’heure. Utilisez M pour indiquer les minutes de 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. Optional.
minimumAttendeePercentage Edm.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. Optional.
returnSuggestionReasons Edm.Boolean Spécifiez True pour renvoyer une raison pour chaque suggestion de réunion dans la propriété suggestionReason . false est la valeur par défaut, si vous ne souhaitez pas renvoyer cette propriété. Optional.
timeConstraint timeConstraint Toutes les restrictions de temps pour une réunion, qui peuvent inclure la nature de la réunion (propriété activityDomain ) et les périodes de réunion possibles (propriété timeSlots ). findMeetingTimes suppose activityDomain comme work si vous ne spécifiiez pas ce paramètre. Optional.

Le tableau suivant décrit les restrictions que vous pouvez spécifier dans le paramètre timeConstraint.

Valeur activityDomain dans timeConstraint Suggestions pour les heures de réunion
travail Les suggestions sont comprises dans les heures de travail de l’utilisateur qui sont définies dans la configuration du calendrier de l’utilisateur et peuvent être personnalisées par l’utilisateur ou l’administrateur. Les heures de travail par défaut sont du lundi au vendredi, de 8 h à 17 h dans le fuseau horaire défini pour la boîte aux lettres. Il s’agit de la valeur par défaut si aucun activityDomain n’est spécifié.
personal Les suggestions sont comprises dans les heures de travail de l’utilisateur, ainsi que le samedi et le dimanche. La valeur par défaut est du lundi au dimanche, de 8 h à 17 h, dans le paramètre de fuseau horaire de la boîte aux lettres.
unrestricted Les suggestions peuvent correspondre à n’importe quelle heure de la journée, tous les jours de la semaine.
unknown N’utilisez pas cette valeur, car elle sera dépréciée à l’avenir. Se comporte actuellement de la même façon que work. Modifiez tout code existant pour utiliser work, personal ou unrestricted le cas échéant.

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.

Réponse

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.

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.

Par défaut, chaque suggestion de réunion est renvoyée au format 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.

Niveau de probabilité d’une suggestion de réunion

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 :

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

Par exemple, si une suggestion de réunion implique 3 participants qui indiquent les informations de disponibilité suivantes :

Participant Informations de disponibilité Probabilité de participation (%)
Dana Gratuit 100 %
Noël Inconnu 49 %
Samantha Occupé(e) 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 %.

Si vous spécifiez un minimumAttendeePercentage de 80 % dans une opération findMeetingTimes , car 49,66 % < 80 %, l’opération ne suggère pas cette fois dans la réponse.

Exemple

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 :

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

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.

Notez que la demande spécifie une heure du fuseau horaire PST. Par défaut, la réponse renvoie des suggestions d’heure de réunion en heure 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.

Demande

Voici l’exemple de demande.

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
}
Réponse

Voici un exemple de réponse. Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

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"
                }
            }
        }
    ]
}