Obtenir la planification de disponibilité des utilisateurs et des ressources du calendrier Outlook

  • Article

En milieu professionnel ou scolaire, un scénario classique sert à déterminer la disponibilité d’un utilisateur pour une réunion, ou à parcourir la disponibilité d’une équipe, d’une salle ou d’équipements pour une période précise.

L’action getSchedule vous permet d’obtenir les informations de disponibilité d’une ou plusieurs entités (utilisateurs, listes de distribution ou ressources) pendant une période spécifique.

Exemple

Un exemple simple consiste à trouver les disponibilités d’un collègue, Alex, pour un jour spécifique entre 9 h et 18 h (heure du Pacifique) :

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

{
    "Schedules": ["AlexW@contoso.com"],
    "StartTime": {
        "dateTime": "2018-08-06T09:00:00",
        "timeZone": "Pacific Standard Time"
    },
    "EndTime": {
        "dateTime": "2018-08-06T18:00:00",
        "timeZone": "Pacific Standard Time"
    },
    "availabilityViewInterval": "15"
}

getSchedule renvoie deux éléments de planning correspondant à des événements existants du calendrier par défaut d’Alain, affichant les heures de début et de fin de chaque événement et son statut de disponibilité. Vous pouvez supposer qu’Alain est disponible pendant le temps restant de cette plage date/heure.

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#Collection(microsoft.graph.scheduleInformation)",
    "value":[
        {
            "scheduleId":"AlexW@contoso.com",
            "availabilityView":"111111002222222200000000000000000000",
            "scheduleItems":[
                {
                    "status":"Tentative",
                    "start":{
                        "dateTime":"2018-08-06T09:00:00.0000000",
                        "timeZone":"Pacific Standard Time"
                    },
                    "end":{
                        "dateTime":"2018-08-06T10:30:00.0000000",
                        "timeZone":"Pacific Standard Time"
                    }
                },
                {
                    "status":"Busy",
                    "start":{
                        "dateTime":"2018-08-06T11:00:00.0000000",
                        "timeZone":"Pacific Standard Time"
                    },
                    "end":{
                        "dateTime":"2018-08-06T13:00:00.0000000",
                        "timeZone":"Pacific Standard Time"
                    }
                }
            ],
            "workingHours":{
                "daysOfWeek":[
                    "monday",
                    "tuesday",
                    "wednesday",
                    "thursday",
                    "friday"
                ],
                "startTime":"08:00:00.0000000",
                "endTime":"17:00:00.0000000",
                "timeZone":{
                    "@odata.type":"#microsoft.graph.customTimeZone",
                    "bias":480,
                    "name":"Customized Time Zone",
                    "standardOffset":{
                        "time":"02:00:00.0000000",
                        "dayOccurrence":1,
                        "dayOfWeek":"sunday",
                        "month":11,
                        "year":0
                    },
                    "daylightOffset":{
                        "daylightBias":-60,
                        "time":"02:00:00.0000000",
                        "dayOccurrence":2,
                        "dayOfWeek":"sunday",
                        "month":3,
                        "year":0
                    }
                }
            }
        }
    ]
}

Outre le planning de disponibilité et les heures de travail d’Alain, getSchedule renvoie également availabilityView, c’est-à-dire une vue fusionnée de la disponibilité d’Alain pour le jour sélectionné. La vue fusionnée est une chaîne qui se compose de créneaux horaires couvrant le jour en question : chaque créneau horaire indique la disponibilité d’Alain à l’aide de la convention suivante :

  • 0= disponible
  • 1= provisoire
  • 2= occupé(e)
  • 3= absent(e) du bureau
  • 4= travaille ailleurs.

Par défaut, les créneaux horaires durent 30 minutes. Cet exemple utilise la propriété availabilityViewInterval pour personnaliser le créneau horaire de façon à ce qu’il dure 15 minutes.

Comparaison entre getSchedule et findMeetingTimes

L’action findMeetingTimes est semblable à getSchedule, car elles lisent toutes les deux l’état de disponibilité et les heures de travail des ressources et des utilisateurs indiqués. Cependant, les deux actions varient sur plusieurs points essentiels.

Application

findMeetingTimes applique une certaine logique métier pour proposer les horaires et les emplacements de réunion, tels que :

  • Présence obligatoire ou facultative de chaque entité
  • Nature de l’activité demandée pour l’heure du jour
  • Participation minimale requise pour le quorum d’une réunion

Elle est appropriée aux scénarios qui dépendent de la simplification de la prise d’un rendez-vous.

getSchedule renvoie simplement l’état de disponibilité des événements existants dans chacun des calendriers demandés pour une période donnée et part du principe que le temps restant dans cette période est disponible. Vous pouvez ensuite appliquer d’autres logiques métier afin d’utiliser ces données pour terminer votre scénario.

Prise en charge de l’application uniquement

findmeetingtimes prend en charge uniquement les scénarios délégués qui nécessitent qu’un utilisateur soit connecté à l’application. L’application peut lire les événements uniquement dans les calendriers auxquels l’utilisateur connecté a accès. Cela peut inclure des calendriers que d’autres d’utilisateurs ont délégués ou partagés avec l’utilisateur connecté.

getSchedule prend en charge les scénarios délégués et application uniquement. Dans cette dernière option, l’administrateur accepte que l’application accède à tous les calendriers, sans utilisateur connecté.

Autorisations

Les autorisations requises par findmeetingtimes avec le moins de privilège sont celles de Calendars.Read.Shared.

Les autorisations requises pargetSchedule avec le moins de privilège sont celles de Calendar.Read.

Prise en charge de la version

findmeetingtimes et getSchedule sont généralement disponibles et appropriées pour les applications de production.

Données événement renvoyées

L’autorisation la moins privilégiée requise par getSchedule pour obtenir des informations de disponibilité pour une application est Calendar.Read. En fonction de votre scénario d’application, elle peut être accordée par l’utilisateur connecté ou l’administrateur.

Les autorisations de permission permettent à une application d’utiliser getSchedule sur les calendriers des utilisateurs demandés, via Outlook, l’utilisateur demandé contrôle les données d’événement, le cas échéant, que renvoie getSchedule.

Par exemple, getSchedule peut renvoyer l’état de disponibilité et les heures de travail des utilisateurs demandés, ou il peut également renvoyer l’objet, l’emplacementet les propriétésisPrivate d’un événement, à condition que :

  • L’événement soit identifié avec un niveau de confidentialité faible (normal ou personal), ET une ou plusieurs des conditions suivantes s’appliquent :

    • Les paramètres du calendrier de l’utilisateur demandé autorisent l’utilisateur connecté à afficher les lignes d’objet et les emplacements
    • Le calendrier de l’utilisateur demandé est partagé avec l’utilisateur connecté.

Ces conditions s’appliquent que l’utilisateur connecté soit un administrateur de l’organisation ou non. L’utilisateur demandé contrôle quelles données d’événement sont renvoyées.

Représentation du fuseau horaire

Par défaut, les heures de début et de fin des éléments du planning renvoyé sont représentées au format UTC. Utilisez un en-tête Prefer pour indiquer un fuseau horaire approprié pour votre application. Par exemple :

Prefer: outlook.timezone="Pacific Standard Time"

Limites et conditions d’erreur

Tenez compte de la condition d’erreur et des limites suivantes :

  • getSchedule permet de rechercher des informations de disponibilité de 20 entités maximum simultanément. Cette limite s’applique au nombre d’utilisateurs identifiés individuellement ou en tant que membres d’une liste de distribution, ainsi que le nombre de ressources.
  • La période de recherche doit être inférieure à 62 jours.
  • Si l’action getSchedule ne peut pas identifier une ressource ou un utilisateur spécifié, elle renvoie un élément de planning unique et indique les erreurs.

Contenu connexe