Obtenir le planning de disponibilité des utilisateurs et des ressourcesGet free/busy schedule of users and resources

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.In a work or school setting, a common scenario is to see when a user is free for meeting, or to browse the availability of a team, room, or equipment for a time period.

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.The getSchedule action lets you get the availability information of one or more entities - users, distribution lists, or resources - for a specific period of time.

ExempleExample

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) :A simple example is to find the free/busy schedule of a coworker, Alex, on a specific day, from 9am to 6pm, Pacific Standard Time:

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

{        
    "Schedules": ["AlexW@contoso.OnMicrosoft.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é.getSchedule returns two schedule items that match existing events in Alex' default calendar, showing the start and end times of each event and its free/busy status. Vous pouvez supposer qu’Alain est disponible pendant le temps restant de cette plage date/heure.You can assume Alex is free for the remaining time in that date/time range.

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.OnMicrosoft.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é.Apart from the free/busy schedule and working hours of Alex, getSchedule also returns availabilityView, which is a merged view of Alex' availability for that day. 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 :The merged view is a string that consists of time slots covering that day, with each time slot indicating Alex' availability using the following convention:

  • 0= disponible0= free
  • 1= provisoire1= tentative
  • 2= occupé(e)2= busy
  • 3= absent(e) du bureau3= out of office
  • 4= travaille ailleurs.4= working elsewhere.

Par défaut, les créneaux horaires durent 30 minutes.By default, the length of each time slot is 30 minutes. Cet exemple utilise la propriété availabilityViewInterval pour personnaliser le créneau horaire de façon à ce qu’il dure 15 minutes.This example uses the availabilityViewInterval property to customize the time slot to be 15 minutes.

Comparaison entre getSchedule et findMeetingTimesHow does getSchedule compare with 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.The findMeetingTimes action is similar to getSchedule in that both read the free/busy status and working hours of specified users and resources. Cependant, les deux actions varient sur plusieurs points essentiels.The two actions differ in a few major ways.

ApplicationApplication

findMeetingTimes applique une certaine logique métier pour proposer les horaires et les emplacements de réunion, tels que :findMeetingTimes applies certain business logic to suggest meeting times and locations, such as:

  • Présence obligatoire ou facultative de chaque entitéOptional or mandatory attendance of each entity
  • Nature de l’activité demandée pour l’heure du jourThe nature of the requested activity for the time of the day
  • Participation minimale requise pour le quorum d’une réunionThe minimum attendance required for a quorum for a meeting

Elle est appropriée aux scénarios qui dépendent de la simplification de la prise d’un rendez-vous.It is appropriate for scenarios that depend on streamlining appointment booking.

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.getSchedule simply returns the free/busy status of existing events in each of the requested calendars for a given time period, and assumes the remaining time in that time period to be free. Vous pouvez ensuite appliquer d’autres logiques métier afin d’utiliser ces données pour terminer votre scénario.You would then apply further business logic to make use of this data to complete your scenario.

Prise en charge de l’application uniquementApp-only support

findmeetingtimes prend en charge uniquement les scénarios délégués qui nécessitent qu’un utilisateur soit connecté à l’application.findmeetingtimes supports only delegated scenarios which require a user to have signed in to the app. L’application peut lire les événements uniquement dans les calendriers auxquels l’utilisateur connecté a accès.The app can read events in only the calendars that the signed-in user can access. Cela peut inclure des calendriers que d’autres d’utilisateurs ont délégués ou partagés avec l’utilisateur connecté.This can include calendars that other users have delegated or shared with the signed-in user.

getSchedule prend en charge les scénarios délégués et application uniquement.getSchedule supports both delegated and app-only scenarios. Dans cette dernière option, l’administrateur accepte que l’application accède à tous les calendriers, sans utilisateur connecté.In the latter, an administrator consents the app to access all calendars without a signed-in user.

AutorisationsPermissions

Les autorisations requises par findmeetingtimes avec le moins de privilège sont celles de Calendars.Read.Shared.The least privileged permissions required by findmeetingtimes is Calendars.Read.Shared.

Les autorisations requises pargetSchedule avec le moins de privilège sont celles de Calendar.Read.The least privileged permission required by getSchedule is Calendars.Read.

Prise en charge de la versionVersion support

findmeetingtimes et getSchedule sont généralement disponibles et appropriées pour les applications de production.findmeetingtimes and getSchedule are both generally available and appropriate for use in production apps.

Données événement renvoyéesEvent data returned

L’autorisation la moins privilégiée requise par getSchedule pour obtenir des informations de disponibilité pour une application est Calendar.Read.The least privileged permission required by getSchedule for an app to get free/busy information is Calendars.Read. En fonction de votre scénario d’application, elle peut être accordée par l’utilisateur connecté ou l’administrateur.Depending on your app scenario, this can be consented by the signed-in user or administrator.

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.While the consented permission lets an app use getSchedule on the requested users' calendars, through Outlook, the requested user controls which event data, if any, that getSchedule returns.

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 :For example, getSchedule can return the free/busy status and working hours of the requested users, or it can also return the subject, location, and isPrivate properties of an event, provided that:

  • L’événement soit identifié avec un niveau de confidentialité faible (normal ou personal), ET une ou plusieurs des conditions suivantes s’appliquent :The event is marked with low sensitivity level - normal or personal - AND one or more of the following conditions apply:

    • Les paramètres du calendrier de l’utilisateur demandé autorisent l’utilisateur connecté à afficher les lignes d’objet et les emplacementsThe requested user’s calendar settings allow the signed-in user to view subject lines and locations
    • Le calendrier de l’utilisateur demandé est partagé avec l’utilisateur connecté.The requested user’s calendar is shared with the signed-in user

Ces conditions s’appliquent que l’utilisateur connecté soit un administrateur de l’organisation ou non.These conditions apply regardless of whether the signed-in user is an administrator in the organization. L’utilisateur demandé contrôle quelles données d’événement sont renvoyées.The requested user has control over the event data returned.

Représentation du fuseau horaireTime zone representation

Par défaut, les heures de début et de fin des éléments du planning renvoyé sont représentées au format UTC.By default, the start and end times of the returned schedule items are represented in UTC. Utilisez un en-tête Prefer pour indiquer un fuseau horaire approprié pour votre application.You can use a Prefer header to specify a time zone appropriate for your app. Par exemple :As an example:

Prefer: outlook.timezone="Pacific Standard Time"

Limites et conditions d’erreurLimits and error conditions

Tenez compte de la condition d’erreur et des limites suivantes :Be aware of the following limits and error condition:

  • getSchedule permet de rechercher des informations de disponibilité de 20 entités maximum simultanément.getSchedule can support looking up free/busy information for up to 20 entities at once. 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.This limit applies to the number of users identified individually or as members of a distribution list, and to the number of resources as well.
  • La période sélectionnée pour la recherche doit être inférieure à 42 jours.The time period to look up must be less than 42 days.
  • 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.If getSchedule cannot identify a specified user or resource, it returns a single schedule item and indicates the error.

Voir aussiSee also