ユーザーとリソースの空き時間スケジュールを取得する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 アクションを使用すると、特定の期間について 1 つ以上のエンティティ (ユーザー、配布リスト、またはリソース) の空き時間情報を取得できます。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

特定の日の午前 9 時から午後 6 時 (太平洋標準時) までの同僚の Alex の空き時間スケジュールを検索する簡単な例を次に示します。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 の既定の予定表にある既存のイベントと一致する 2 つのスケジュール項目を返します。これで、各イベントの開始時刻と終了時刻と、その空き時間状態がわかります。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 の空き時間スケジュールと勤務時間以外に、getScheduleavailabilityView も返します。これは、その日の 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. 2 つのアクションは、いくつかの主要な点で異なります。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は要求されたユーザーの空き時間状況と稼働時間を返すことも、件名場所、および提供されたイベントのisPrivateプロパティを返すこともできます。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:

  • イベントの秘密度レベルが低く (normal または personal)、さらに次の条件の 1 つ以上が適用される場合: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