user: findMeetingTimesuser: findMeetingTimes

名前空間: microsoft.graphNamespace: microsoft.graph

パラメーターとして指定された開催者と出席者の空き時間、および時間または場所の制約に基づいて、会議の時間と場所を提案します。Suggest meeting times and locations based on organizer and attendee availability, and time or location constraints specified as parameters.

findMeetingTimes が会議提案を返すことができない場合は、応答で、emptySuggestionsReason プロパティに理由が示されます。この値に基づいて、パラメーターをさらに調整して、findMeetingTimes を再度呼び出すことができます。If findMeetingTimes cannot return any meeting suggestions, the response would indicate a reason in the emptySuggestionsReason property. Based on this value, you can better adjust the parameters and call findMeetingTimes again.

会議の時間と場所を提案するために使用されるアルゴリズムは、随時微調整されます。The algorithm used to suggest meeting times and locations undergoes fine-tuning from time to time. 入力パラメーターと予定表のデータが静的な状態のテスト環境のようなシナリオでは、提案される結果は時間の経過とともに変化する可能性があります。In scenarios like test environments where the input parameters and calendar data remain static, expect that the suggested results may differ over time.

アクセス許可Permissions

この API を呼び出すには、次のいずれかのアクセス許可が必要です。アクセス許可の選択方法などの詳細については、「アクセス許可」を参照してください。One of the following permissions is required to call this API. To learn more, including how to choose permissions, see Permissions.

アクセス許可の種類Permission type アクセス許可 (特権の小さいものから大きいものへ)Permissions (from least to most privileged)
委任 (職場または学校のアカウント)Delegated (work or school account) Calendars.Read.Shared、Calendars.ReadWrite.SharedCalendars.Read.Shared, Calendars.ReadWrite.Shared
委任 (個人用 Microsoft アカウント)Delegated (personal Microsoft account) サポートされていません。Not supported.
アプリケーションApplication サポートされていません。Not supported.

HTTP 要求HTTP request

POST /me/findMeetingTimes
POST /users/{id|userPrincipalName}/findMeetingTimes

要求ヘッダーRequest headers

名前Name Value
AuthorizationAuthorization ベアラー {トークン}。必須。Bearer {token}. Required.
優先: outlook.timezonePrefer: outlook.timezone 応答として "太平洋標準時" などの特定のタイム ゾーンを表す文字列です。省略可能。このヘッダーが指定されていない場合は、UTC が使用されます。A string representing a specific time zone for the response, for example, "Pacific Standard Time". Optional. UTC is used if this header is not specified.

要求本文Request body

サポートされているすべてのパラメーターは以下のとおりです。シナリオに応じて、要求本文で必要な各パラメーターの JSON オブジェクトを指定します。All the supported parameters are listed below. Depending on your scenario, specify a JSON object for each of the necessary parameters in the request body.

パラメーターParameter 種類Type 説明Description
attendeesattendees attendeeBase コレクションattendeeBase collection 会議の出席者またはリソースのコレクションです。findMeetingTimes では個人の出席者が常に必要であると仮定されているため、個人として required、対応する type プロパティのリソースとして resource を指定します。コレクションを空にすると、findMeetingTimes は開催者のみの空き時間帯を検索します。省略可能。A collection of attendees or resources for the meeting. Since findMeetingTimes assumes that any attendee who is a person is always required, specify required for a person and resource for a resource in the corresponding type property. An empty collection causes findMeetingTimes to look for free time slots for only the organizer. Optional.
isOrganizerOptionalisOrganizerOptional Edm.BooleanEdm.Boolean 開催者が必ずしも出席する必要がない場合は、True を指定します。既定値は false です。省略可能。Specify True if the organizer doesn't necessarily have to attend. The default is false. Optional.
locationConstraintlocationConstraint locationConstraintlocationConstraint 会議の場所の提案が必要かどうか、または会議のみが開催できる特定の場所があるか、など、会議の場所に関する開催者の要件。省略可能。The organizer's requirements about the meeting location, such as whether a suggestion for a meeting location is required, or there are specific locations only where the meeting can take place. Optional.
maxCandidatesmaxCandidates Edm.Int32Edm.Int32 返される会議時間の提案の最大数です。省略可能。The maximum number of meeting time suggestions to be returned. Optional.
meetingDurationmeetingDuration Edm.DurationEdm.Duration ISO8601 形式で示された会議の長さです。たとえば、1 時間は 'PT1H' として示され、このとき 'P' は期間の指定子、'T' は時刻の指定子、'H' は時間の指定子です。期間の分を示すには M を使用します。たとえば、2 時間 30 分は 'PT2H30M' になります。会議の期間を指定しない場合、findMeetingTimes は既定値の 30 分を使用します。省略可能。The length of the meeting, denoted in ISO8601 format. For example, 1 hour is denoted as 'PT1H', where 'P' is the duration designator, 'T' is the time designator, and 'H' is the hour designator. Use M to indicate minutes for the duration; for example, 2 hours and 30 minutes would be 'PT2H30M'. If no meeting duration is specified, findMeetingTimes uses the default of 30 minutes. Optional.
minimumAttendeePercentageminimumAttendeePercentage Edm.DoubleEdm.Double 応答で返される時間帯に最低限要求される確度です。割合 ( %) の値 (0 から 100 まで)。省略可能。The minimum required confidence for a time slot to be returned in the response. It is a % value ranging from 0 to 100. Optional.
returnSuggestionReasonsreturnSuggestionReasons Edm.BooleanEdm.Boolean SuggestionReason プロパティで各会議提案の理由を返すには、True を指定します。既定値は false であり、そのプロパティを返しません。省略可能。Specify True to return a reason for each meeting suggestion in the suggestionReason property. The default is false to not return that property. Optional.
timeConstrainttimeConstraint timeConstrainttimeConstraint 会議の性質 (activityDomain プロパティ) と可能な会議の時間帯 (timeSlots property) を含めることのできる時間制限。このパラメーターを指定しない場合、findMeetingTimesactivityDomainwork と仮定します。省略可能。Any time restrictions for a meeting, which can include the nature of the meeting (activityDomain property) and possible meeting time periods (timeSlots property). findMeetingTimes assumes activityDomain as work if you don't specify this parameter. Optional.

timeConstraint パラメーターにさらに指定できる activityDomain 制限について、次の表で説明します。The following table describes the activityDomain restrictions you can further specify in the timeConstraint parameter.

activityDomain 値activityDomain value 会議の時間の候補Suggestions for meeting times
作業時間work ユーザーの予定表の構成で定義された稼働時間 (ユーザーまたは管理者がカスタマイズできる) の範囲内で候補が提案されます。既定の稼働時間は、月曜日から金曜日の午前 8 時から午後 5 時 (メールボックスに設定されたタイム ゾーンでの時刻) です。activityDomain を指定しない場合、これが既定値です。Suggestions are within the user's work hours which are defined in the user’s calendar configuration and can be customized by the user or administrator. The default work hours are Monday to Friday, 8am to 5pm in the time zone set for the mailbox. This is the default value if no activityDomain is specified.
personalpersonal ユーザーの稼働時間の範囲内と、土曜日と日曜日の範囲内で候補が提案されます。既定では、月曜日から日曜日の午前 8 時から午後 5 時 (メールボックスに設定されたタイム ゾーンでの時刻) です。Suggestions are within the user's work hours, and Saturday and Sunday. The default is Monday to Sunday, 8am to 5pm, in the time zone setting for the mailbox.
Unrestrictedunrestricted 任意の曜日の任意の時刻から候補が提案されます。Suggestions can be from all hours of a day, all days of a week.
不明unknown 将来的に使われなくなりますので、この値は使わないでください。現在の動作は、work と同じです。workpersonal または unrestricted を使用するように、既存のコードを適宜変更します。Do not use this value as it will be deprecated in the future. Currently behaves the same as work. Change any existing code to use work, personal or unrestricted as appropriate.

指定したパラメーターに基づいて、findMeetingTimes は開催者と出席者の標準として設定されている予定表で空き時間状態を確認します。アクションは、開催できる可能性が最も高い会議の日時を計算し、会議の提案を返します。Based on the specified parameters,findMeetingTimes checks the free/busy status in the primary calendars of the organizer and attendees. The action calculates the best possible meeting times, and returns any meeting suggestions.

応答Response

成功した場合、このメソッドは 200 OK 応答コードと、応答本文に入った meetingTimeSuggestionsResult を返します。If successful, this method returns 200 OK response code and a meetingTimeSuggestionsResult in the response body.

meetingTimeSuggestionsResult には、会議提案のコレクションと emptySuggestionsReason プロパティが含まれます。各提案は、meetingTimeSuggestion として定義され、出席者の参加の確度について、平均で 50% またはminimumAttendeePercentage パラメーターで指定した特定の割合 (%) が付されます。A meetingTimeSuggestionsResult includes a collection of meeting suggestions and an emptySuggestionsReason property. Each suggestion is defined as a meetingTimeSuggestion, with attendees having on the average a confidence level of 50% to attend, or a specific % that you have specified in the minimumAttendeePercentage parameter.

既定では、会議の日時についての各提案は UTC で返されます。By default, each meeting time suggestion is returned in UTC.

findMeetingTimes が会議提案を返すことができない場合は、応答で、emptySuggestionsReason プロパティに理由が示されます。この値に基づいて、パラメーターをさらに調整して、findMeetingTimes を再度呼び出すことができます。If findMeetingTimes cannot return any meeting suggestions, the response would indicate a reason in the emptySuggestionsReason property. Based on this value, you can better adjust the parameters and call findMeetingTimes again.

会議の提案の確実性The confidence of a meeting suggestion

meetingTimeSuggestionconfidence プロパティの範囲は 0% から 100% で、各個人の空き時間状態に基づいて会議に出席するすべての出席者の見込みを表します。The confidence property of a meetingTimeSuggestion ranges from 0% to 100%, and represents the chance that all the attendees attend the meeting, based on each of their individual free/busy status:

  • 各出席者に関する、指定の会議期間の空き状態で、確実に出席する場合は 100%、不明な状態は 49%、忙しい場合には 0% です。For each attendee, a free status for a specified meeting time period corresponds to 100% chance of attendance, unknown status 49%, and busy status 0%.
  • 会議時間の提案の確実性は、指定された対象会議のすべての出席者の出席見込みの平均によって算出されます。The confidence of a meeting time suggestion is computed by averaging the chance of attendance over all the attendees specified for that meeting.
  • findMeetingTimesminimumAttendeePercentage オプション パラメーターを使用して、少なくとも特定の信頼度の会議の時間帯のみが返されるように指定することができます。たとえば、すべての出席者が出席する見込みが 80% 以上ある提案のみを行う場合は、80% の minimumAttendeePercentage を指定できます。minimumAttendeePercentage を指定しない場合は、findMeetingTimes は 50% の値を前提とします。You can use the minimumAttendeePercentage optional parameter for findMeetingTimes to specify only meeting time suggestions of at least certain confidence level should be returned. For example, you can specify a minimumAttendeePercentage of 80% if you want only suggestions that have an 80% chance or more that all the attendees are attending. If you do not specify minimumAttendeePercentage, findMeetingTimes assumes a value of 50%.
  • 会議時間の提案が複数ある場合、findMeetingTimes アクションは、算出した確実性が高い方から順番に提案を並べて示します。確実性が同じ提案がある場合には、時系列で提案を並べて示します。If there are multiple meeting time suggestions, the findMeetingTimes action first orders the suggestions by their computed confidence value from high to low. If there are suggestions with the same confidence, the action then orders these suggestions chronologically.

たとえば、提案の会議時間に次の空き時間状態の 3 人の出席者がいるとします。As an example, if a meeting time suggestion involves 3 attendees with the following free/busy status:

出席者Attendee 空き時間状態Free/busy status 出席見込み (%)% Chance of attendance
DanaDana 空きFree 100%100%
JohnJohn 不明Unknown 49%49%
SamanthaSamantha 多忙Busy 0%0%

この場合、出席の平均見込みである会議時間の提案の信頼度は、(100% + 49% + 0%)/3 = 49.66% です。Then the confidence of the meeting time suggestion, which is the average chance of attendance, is (100% + 49% + 0%)/3 = 49.66%.

findMeetingTimes で 80% の minimumAttendeePercentage を指定すると、49.66% < 80% のため、操作では応答でこの時間の提案は返されません。If you specify a minimumAttendeePercentage of 80% in a findMeetingTimes operation, because 49.66% < 80%, the operation will not suggest this time in the response.

Example

次の例は、要求本文で次のパラメーターを指定して、あらかじめ決められた会議を開催する時間を検索し、各提案の理由を要求する方法を示しています。The following example shows how to find time to meet at a pre-determined location, and request a reason for each suggestion, by specifying the following parameters in the request body:

  • attendeesattendees
  • locationConstraintlocationConstraint
  • timeConstrainttimeConstraint
  • isOrganizerOptionalisOrganizerOptional
  • meetingDurationmeetingDuration
  • returnSuggestionReasonsreturnSuggestionReasons
  • minimumAttendeePercentageminimumAttendeePercentage

findMeetingTimes が任意の提案を返す場合は、returnSuggestionReasons パラメーターを設定することで、各提案の SuggestionReason プロパティの説明も取得できます。By setting the returnSuggestionReasons parameter, you also get an explanation in the suggestionReason property for each suggestion, if findMeetingTimes returns any suggestion.

この要求では PST タイム ゾーンで時間を指定します。Notice that the request specifies time in the PST time zone. 既定では、UTC での会議の時間の候補を応答で返します。By default, the response returns meeting time suggestions in UTC. PST を指定するのに、また応答の時間の値にも Prefer: outlook.timezone 要求ヘッダーを使うことができます。You can use the Prefer: outlook.timezone request header to specify PST as well for the time values in the response.

要求Request

要求の例を次に示します。Here is the example request.

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

{ 
  "attendees": [ 
    { 
      "type": "required",  
      "emailAddress": { 
        "name": "Alex Wilbur",
        "address": "alexw@contoso.onmicrosoft.com" 
      } 
    }
  ],  
  "locationConstraint": { 
    "isRequired": "false",  
    "suggestLocation": "false",  
    "locations": [ 
      { 
        "resolveAvailability": "false",
        "displayName": "Conf room Hood" 
      } 
    ] 
  },  
  "timeConstraint": {
    "activityDomain":"work", 
    "timeSlots": [ 
      { 
        "start": { 
          "dateTime": "2019-04-16T09:00:00",  
          "timeZone": "Pacific Standard Time" 
        },  
        "end": { 
          "dateTime": "2019-04-18T17:00:00",  
          "timeZone": "Pacific Standard Time" 
        } 
      } 
    ] 
  },  
  "isOrganizerOptional": "false",
  "meetingDuration": "PT1H",
  "returnSuggestionReasons": "true",
  "minimumAttendeePercentage": "100"
}
応答Response

応答の例を次に示します。メモ:簡潔にするために、ここに示す応答オブジェクトは切り詰められている場合があります。実際の呼び出しではすべてのプロパティが返されます。Here is an example response. Note: The response object shown here may be truncated for brevity. All of the properties will be returned from an actual call.

HTTP/1.1 200 OK
Content-type: application/json
Preference-Applied: outlook.timezone="Pacific Standard Time"

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.meetingTimeSuggestionsResult",
    "emptySuggestionsReason": "",
    "meetingTimeSuggestions": [
        {
            "confidence": 100,
            "order": 1,
            "organizerAvailability": "free",
            "suggestionReason": "Suggested because it is one of the nearest times when all attendees are available.",
            "attendeeAvailability": [
                {
                    "availability": "free",
                    "attendee": {
                        "emailAddress": {
                            "address": "alexw@contoso.onmicrosoft.com"
                        }
                    }
                }
            ],
            "locations": [
                {
                    "displayName": "Conf room Hood"
                }
            ],
            "meetingTimeSlot": {
                "start": {
                    "dateTime": "2019-04-18T16:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                },
                "end": {
                    "dateTime": "2019-04-18T17:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                }
            }
        },
        {
            "confidence": 100,
            "order": 2,
            "organizerAvailability": "free",
            "suggestionReason": "Suggested because it is one of the nearest times when all attendees are available.",
            "attendeeAvailability": [
                {
                    "availability": "free",
                    "attendee": {
                        "emailAddress": {
                            "address": "alexw@contoso.onmicrosoft.com"
                        }
                    }
                }
            ],
            "locations": [
                {
                    "displayName": "Conf room Hood"
                }
            ],
            "meetingTimeSlot": {
                "start": {
                    "dateTime": "2019-04-18T08:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                },
                "end": {
                    "dateTime": "2019-04-18T09:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                }
            }
        },
        {
            "confidence": 100,
            "order": 3,
            "organizerAvailability": "tentative",
            "suggestionReason": "Suggested because it is one of the nearest times when all attendees are available.",
            "attendeeAvailability": [
                {
                    "availability": "free",
                    "attendee": {
                        "emailAddress": {
                            "address": "alexw@contoso.onmicrosoft.com"
                        }
                    }
                }
            ],
            "locations": [
                {
                    "displayName": "Conf room Hood"
                }
            ],
            "meetingTimeSlot": {
                "start": {
                    "dateTime": "2019-04-18T15:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                },
                "end": {
                    "dateTime": "2019-04-18T16:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                }
            }
        },
        {
            "confidence": 100,
            "order": 4,
            "organizerAvailability": "tentative",
            "suggestionReason": "Suggested because it is one of the nearest times when all attendees are available.",
            "attendeeAvailability": [
                {
                    "availability": "free",
                    "attendee": {
                        "emailAddress": {
                            "address": "alexw@contoso.onmicrosoft.com"
                        }
                    }
                }
            ],
            "locations": [
                {
                    "displayName": "Conf room Hood"
                }
            ],
            "meetingTimeSlot": {
                "start": {
                    "dateTime": "2019-04-18T09:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                },
                "end": {
                    "dateTime": "2019-04-18T10:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                }
            }
        },
        {
            "confidence": 100,
            "order": 5,
            "organizerAvailability": "tentative",
            "suggestionReason": "Suggested because it is one of the nearest times when all attendees are available.",
            "attendeeAvailability": [
                {
                    "availability": "free",
                    "attendee": {
                        "emailAddress": {
                            "address": "alexw@contoso.onmicrosoft.com"
                        }
                    }
                }
            ],
            "locations": [
                {
                    "displayName": "Conf room Hood"
                }
            ],
            "meetingTimeSlot": {
                "start": {
                    "dateTime": "2019-04-18T12:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                },
                "end": {
                    "dateTime": "2019-04-18T13:00:00.0000000",
                    "timeZone": "Pacific Standard Time"
                }
            }
        }
    ]
}