获取用户和资源的忙/闲日程安排Get free/busy schedule of users and resources

在工作或学校设置中,一种常见方案是查看用户何时有空参加会议,或浏览团队、会议室或设备在一段时间内的状态。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.

使用 getSchedule 操作,可以获取一个或多个实体(用户、通讯组列表或资源)在特定时间段内的状态信息。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.

示例Example

下面的简单示例展示了如何查找同事 Alex 在某天上午 9 点到下午 6 点(太平洋标准时间)之间的忙/闲日程安排: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 返回两个与 Alex 默认日历中现有事件匹配的日程安排项,同时显示每个事件的开始时间和结束时间及其忙/闲状态。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. 可以假定 Alex 在此日期/时间范围的剩余时间内是空闲的。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
                    }
                }
            }
        }
    ]
}

除了 Alex 的忙/闲日程安排和工作时间之外,getSchedule 还返回 availabilityView,这是 Alex 这一天状态的合并视图。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. 此合并视图是一个字符串,其中包含这一天的所有时间段,每个时间段都使用以下约定指明 Alex 的状态: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= 空闲0= free
  • 1= 暂定1= tentative
  • 2= 忙碌2= busy
  • 3= 外出3= out of office
  • 4= 在其他地方工作。4= working elsewhere.

默认情况下,每个时间段的长度为 30 分钟。By default, the length of each time slot is 30 minutes. 此示例使用 availabilityViewInterval 属性,将时间段自定义为 15 分钟。This example uses the availabilityViewInterval property to customize the time slot to be 15 minutes.

getSchedule 如何与 findMeetingTimes 进行比较How does getSchedule compare with findMeetingTimes

findMeetingTimes 操作与 getSchedule 类似,两者都读取指定用户和资源的忙/闲状态和工作时间。The findMeetingTimes action is similar to getSchedule in that both read the free/busy status and working hours of specified users and resources. 这两项操作的区别主要在以下几方面。The two actions differ in a few major ways.

用途Application

findMeetingTimes 应用特定业务逻辑来建议会议时间和地点,如:findMeetingTimes applies certain business logic to suggest meeting times and locations, such as:

  • 每个实体是自愿与会还是必须与会Optional or mandatory attendance of each entity
  • 一天内请求执行的活动的性质The nature of the requested activity for the time of the day
  • 会议仲裁要求的最少与会人数The minimum attendance required for a quorum for a meeting

它适用于依赖简化约会预订的方案。It is appropriate for scenarios that depend on streamlining appointment booking.

getSchedule 只返回每个所需日历中现有事件在给定时间段内的忙/闲状态,并假定在此时间段的剩余时间内是空闲的。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. 然后,应用其他业务逻辑来利用此类数据完成方案。You would then apply further business logic to make use of this data to complete your scenario.

仅应用支持App-only support

findmeetingtimes 仅支持要求用户必须已登录应用的委托方案。findmeetingtimes supports only delegated scenarios which require a user to have signed in to the app. 应用只能读取已登录用户可以访问的日历中的事件。The app can read events in only the calendars that the signed-in user can access. 这可以包括其他用户已委托或已与登录用户共享的日历。This can include calendars that other users have delegated or shared with the signed-in user.

getSchedule 支持委托方案和仅应用方案。getSchedule supports both delegated and app-only scenarios. 对于后者,管理员同意应用访问所有日历,即使没有已登录用户,也不例外。In the latter, an administrator consents the app to access all calendars without a signed-in user.

权限Permissions

findmeetingtimes 所需的最低特权权限为 Calendars.Read.Shared。The least privileged permissions required by findmeetingtimes is Calendars.Read.Shared.

getSchedule 所需的最低特权权限为 Calendars.Read。The least privileged permission required by getSchedule is Calendars.Read.

版本支持Version support

findmeetingtimesgetSchedule 均已正式发布且适用于生产应用。findmeetingtimes and getSchedule are both generally available and appropriate for use in production apps.

返回的事件数据Event data returned

要使应用能够获取忙/闲信息,getSchedule 所需的最低特权权限为 Calendars.Read。The least privileged permission required by getSchedule for an app to get free/busy information is Calendars.Read. 根据应用方案,这可由已登录用户或管理员同意授予。Depending on your app scenario, this can be consented by the signed-in user or administrator.

虽然借助同意后授予的权限,应用可通过 Outlook 在所请求用户的日历上使用 getSchedule但所请求的用户可控制该 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.

例如,getSchedule 可返回所请求用户的忙/闲状态和工作时间,还能返回事件的 subjectlocationisPrivate,但前提是: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:

  • 事件被标记为低敏感度级别(normalpersonal),且符合以下一个或多个条件:The event is marked with low sensitivity level - normal or personal - AND one or more of the following conditions apply:

    • 所请求的用户的日历设置允许用户登录后查看主题行和位置The requested user’s calendar settings allow the signed-in user to view subject lines and locations
    • 所请求的用户的日历与已登录用户共享The requested user’s calendar is shared with the signed-in user

无论已登录用户是否是组织中的管理员,都需遵循这些条件。These conditions apply regardless of whether the signed-in user is an administrator in the organization. 所请求的用户可控制返回的事件数据。The requested user has control over the event data returned.

时区表示Time zone representation

默认情况下,返回的日程安排项的开始时间和结束时间都采用 UTC。By default, the start and end times of the returned schedule items are represented in UTC. 可使用 Prefer 头指定适合应用的时区。You can use a Prefer header to specify a time zone appropriate for your app. 例如:As an example:

Prefer: outlook.timezone="Pacific Standard Time"

限制和错误条件Limits and error conditions

请注意以下限制和错误条件:Be aware of the following limits and error condition:

  • getSchedule 支持一次查找最多 20 个实体的忙/闲信息。getSchedule can support looking up free/busy information for up to 20 entities at once. 标识为个人的用户数或标识为通讯组列表成员的用户数以及资源数都计入此限制。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.
  • 查找时间段不得长于 42 天。The time period to look up must be less than 42 days.
  • 如果 getSchedule 无法识别指定用户或资源,便会返回一个日程安排项并指明错误。If getSchedule cannot identify a specified user or resource, it returns a single schedule item and indicates the error.

另请参阅See also