Abrufen des Frei/Gebucht-Zeitplans für Benutzer und Ressourcen,Get free/busy schedule of users and resources

Ein häufiges Szenario in einer Arbeits- oder Schulumgebung besteht darin, anzuzeigen, wann ein Benutzer für eine Besprechung verfügbar ist, oder die Verfügbarkeit eines Teams, Raums oder Geräts für einen Zeitraum zu durchsuchen.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.

Mit der getSchedule-Aktion können Sie die Verfügbarkeitsinformationen einer oder mehrerer Entitäten (Benutzer, Verteilerlisten oder Ressourcen) für einen bestimmten Zeitraum abrufen.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.

BeispielExample

Ein einfach Beispiel ist das Suchen des Frei/Gebucht-Zeitplans eines Mitarbeiters Alex an einem bestimmten Tag von 9 Uhr bis 18 Uhr, Pacific Standard Time: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 gibt zwei Zeitplanelemente zurück, die vorhandenen Ereignissen in dem Standardkalender von Alex entsprechen; es werden die Start- und Endzeiten der einzelnen Ereignisse sowie der Frei/Gebucht-Status angezeigt.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. Sie können davon ausgehen, dass Alex die verbleibende Zeit in diesem Datums-/Uhrzeitbereich verfügbar ist.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
                    }
                }
            }
        }
    ]
}

Unabhängig vom Frei/Gebucht-Zeitplan und den Arbeitszeiten von Alex gibt getSchedule auch availabilityView zurück, eine zusammengeführte Ansicht der Verfügbarkeit von Alex an diesem Tag.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. Die zusammengeführte Ansicht ist eine Zeichenfolge, die aus Zeitfenstern für diesen Tag besteht; jedes Zeitfenster gibt dabei die Verfügbarkeit von Alex mithilfe der folgenden Konvention an: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= frei0= free
  • 1= mit Vorbehalt1= tentative
  • 2= gebucht2= busy
  • 3= abwesend3= out of office
  • 4= an anderem Ort tätig.4= working elsewhere.

Standardmäßig beträgt die Länge der einzelnen Zeitfenster 30 Minuten.By default, the length of each time slot is 30 minutes. Dieses Beispiel verwendet die availabilityViewInterval-Eigenschaft, um das Zeitfenster auf 15 Minuten zu ändern.This example uses the availabilityViewInterval property to customize the time slot to be 15 minutes.

Worin unterscheiden sich getSchedule und findMeetingTimes?How does getSchedule compare with findMeetingTimes

Die findMeetingTimes-Aktion ist dahingehend vergleichbar mit getSchedule, dass beide Aktionen den Frei/Gebucht-Status und die Arbeitszeiten der angegebenen Benutzer und Ressourcen lesen.The findMeetingTimes action is similar to getSchedule in that both read the free/busy status and working hours of specified users and resources. Die beiden Aktionen unterscheiden sich in einigen anderen wichtigen Aspekten.The two actions differ in a few major ways.

AnwendungApplication

findMeetingTimes wendet eine bestimmte Geschäftslogik an, um Besprechungszeiten und Orte vorzuschlagen, z. B.:findMeetingTimes applies certain business logic to suggest meeting times and locations, such as:

  • Optionale oder obligatorische Teilnahme der einzelnen Entitäten.Optional or mandatory attendance of each entity
  • Die Art der angeforderten Aktivität für die Uhrzeit.The nature of the requested activity for the time of the day
  • Die Mindestteilnehmeranzahl, die für ein Quorum für eine Besprechung erforderlich ist.The minimum attendance required for a quorum for a meeting

Dies eignet sich für Szenarien, die von einer optimierten Terminbuchung abhängig sind.It is appropriate for scenarios that depend on streamlining appointment booking.

getSchedule gibt einfach der Frei/Gebucht-Status der vorhandenen Ereignisse in jedem der angeforderten Kalender für einen bestimmten Zeitraum zurück und geht davon aus, dass die verbleibende Zeit in diesem Zeitraum frei ist.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. Dann wird weitere Geschäftslogik angewendet, um diese Daten zur Vervollständigung Ihres Szenarios zu nutzen.You would then apply further business logic to make use of this data to complete your scenario.

Nur-App-SupportApp-only support

findmeetingtimes unterstützt nur delegierte Szenarien, in denen sich ein Benutzer bei der App angemeldet haben muss.findmeetingtimes supports only delegated scenarios which require a user to have signed in to the app. Die App kann Ereignisse nur in den Kalendern lesen, auf die der angemeldete Benutzer zugreifen kann.The app can read events in only the calendars that the signed-in user can access. Dazu zählen Kalender, die andere Benutzer delegiert oder für den angemeldeten Benutzer freigegeben haben.This can include calendars that other users have delegated or shared with the signed-in user.

getSchedule unterstützt sowohl delegierte als auch Nur-App-Szenarien.getSchedule supports both delegated and app-only scenarios. Bei letzterem stimmt ein Administrator zu, dass die App auf alle Kalender ohne einen angemeldeten Benutzer zugreift.In the latter, an administrator consents the app to access all calendars without a signed-in user.

BerechtigungenPermissions

"Calendars.Read.Shared" ist die niedrigste Berechtigung, die von findmeetingtimes benötigt wird.The least privileged permissions required by findmeetingtimes is Calendars.Read.Shared.

"Calendars.Read" ist die niedrigste Berechtigung, die von getSchedule benötigt wird.The least privileged permission required by getSchedule is Calendars.Read.

VersionsunterstützungVersion support

findmeetingtimes und getSchedule sind sowohl allgemein verfügbar als auch für den Einsatz in Produktionsanwendungen geeignet.findmeetingtimes and getSchedule are both generally available and appropriate for use in production apps.

Zurückgegebene EreignisdatenEvent data returned

"Calendars.Read" ist die niedrigste Berechtigung, die von getSchedule zum Abrufen von Frei/Gebucht-Informationen durch eine App benötigt wird.The least privileged permission required by getSchedule for an app to get free/busy information is Calendars.Read. Je nach App-Szenario kann der angemeldete Benutzer oder der Administrator zustimmen.Depending on your app scenario, this can be consented by the signed-in user or administrator.

Während die genehmigte Berechtigung es einer App erlaubt, getSchedule auf den Kalendern der angeforderten Benutzer über Outlook zu verwenden, steuert der angeforderte Benutzer, welche Ereignisdaten, falls vorhanden, von getSchedule zurückgegeben werden.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.

Beispielsweise kann getSchedule den Frei/Belegt-Status und die Arbeitszeiten der angeforderten Benutzer oder auch die Eigenschaften subject, location und isPrivate eines Ereignisses zurückgeben, vorausgesetzt, dass: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:

  • Das Ereignis mit geringer Vertraulichkeitsstufe markiert ist (normal oder personal) UND eine oder mehrere der folgenden Bedingungen zutreffen:The event is marked with low sensitivity level - normal or personal - AND one or more of the following conditions apply:

    • Die Kalendereinstellungen des angeforderten Benutzers erlauben es dem angemeldeten Benutzer, Betreffzeilen und Orte anzuzeigen.The requested user’s calendar settings allow the signed-in user to view subject lines and locations
    • Der Kalender des angeforderten Benutzers ist für den angemeldeten Benutzer freigegeben.The requested user’s calendar is shared with the signed-in user

Diese Bedingungen gelten unabhängig davon, ob der angemeldete Benutzer ein Administrator in der Organisation ist.These conditions apply regardless of whether the signed-in user is an administrator in the organization. Der angeforderte Benutzer hat die Kontrolle über die zurückgegebenen Ereignisdaten.The requested user has control over the event data returned.

ZeitzonendarstellungTime zone representation

Standardmäßig werden die Start- und Endzeiten der zurückgegebenen Zeitplanelemente in UTC dargestellt.By default, the start and end times of the returned schedule items are represented in UTC. Sie können eine Prefer-Kopfzeile verwenden, um eine für Ihre App geeignete Zeitzone anzugeben.You can use a Prefer header to specify a time zone appropriate for your app. Beispiel:As an example:

Prefer: outlook.timezone="Pacific Standard Time"

Beschränkungen und FehlerursachenLimits and error conditions

Beachten Sie die folgenden Beschränkungen und Fehlerbedingungen:Be aware of the following limits and error condition:

  • getSchedule kann das Nachschlagen von Frei/Gebucht-Informationen für bis zu 20 Entitäten gleichzeitig unterstützen.getSchedule can support looking up free/busy information for up to 20 entities at once. Dieser Grenzwert gilt für die Anzahl von Benutzern, die einzeln oder als Mitglieder einer Verteilerliste identifiziert wurden, und auch für die Anzahl von Ressourcen.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.
  • Der Zeitraum zum Nachschlagen muss weniger als 42 Tage betragen.The time period to look up must be less than 42 days.
  • Wenn getSchedule keinen angegebenen Benutzer oder keine angegebene Ressource identifizieren kann, wird ein einzelnes Zeitplanelement zurückgegeben und der Fehler angezeigt.If getSchedule cannot identify a specified user or resource, it returns a single schedule item and indicates the error.

Siehe auchSee also