user: findMeetingTimes

  • [アーティクル]

名前空間: microsoft.graph

重要

Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。

パラメーターとして指定された開催者と出席者の空き時間、および時間または場所の制約に基づいて、会議の時間と場所を提案します。

findMeetingTimes が会議提案を返すことができない場合は、応答で、emptySuggestionsReason プロパティに理由が示されます。 この値に基づいて、パラメーターをさらに調整して、findMeetingTimes を再度呼び出すことができます。

会議の時間と場所を提案するために使用されるアルゴリズムは、随時微調整されます。 入力パラメーターと予定表のデータが静的な状態のテスト環境のようなシナリオでは、提案される結果は時間の経過とともに変化する可能性があります。

この API は、次の国内クラウド展開で使用できます。

グローバル サービス 米国政府機関 L4 米国政府機関 L5 (DOD) 21Vianet が運営する中国
✅ ✅ ✅ ✅

アクセス許可

この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。 アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「 アクセス許可の種類」を参照してください。 これらのアクセス許可の詳細については、 アクセス許可のリファレンスを参照してください。

アクセス許可の種類 最小特権アクセス許可 特権の高いアクセス許可
委任 (職場または学校のアカウント) Calendars.Read.Shared Calendars.ReadWrite.Shared
委任 (個人用 Microsoft アカウント) サポートされていません。 サポートされていません。
アプリケーション サポートされていません。 サポートされていません。

HTTP 要求

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

要求ヘッダー

名前 値
Authorization ベアラー {token}。 必須です。 認証と承認の詳細については、こちらをご覧ください。
優先: outlook.timezone 応答として "太平洋標準時" などの特定のタイム ゾーンを表す文字列です。 省略可能です。 このヘッダーが指定されていない場合は、UTC が使用されます。

要求本文

サポートされているすべてのパラメーターは以下のとおりです。 シナリオに応じて、要求本文で必要な各パラメーターの JSON オブジェクトを指定します。

パラメーター 型 説明
attendees attendeeBase コレクション 会議の出席者またはリソースのコレクションです。 対応する type プロパティで、ユーザーとresource会議室などのリソースの または optional を指定requiredします。 指定しない場合、findMeetingTimes は type プロパティを想定しますrequired。 コレクションを空にすると、findMeetingTimes は開催者のみの空き時間帯を検索します。 省略可能です。
isOrganizerOptional Edm.Boolean 開催者が必ずしも出席する必要がない場合は、True を指定します。 既定値は false です。 省略可能です。
locationConstraint locationConstraint 会議の場所の提案が必要かどうか、または会議のみが開催できる特定の場所があるか、など、会議の場所に関する開催者の要件。 省略可能です。
maxCandidates Edm.Int32 返される会議時間の提案の最大数です。 オプション。
meetingDuration Edm.Duration ISO 8601 形式で示される会議の長さ。 たとえば、1 時間は "PT1H" として表され、"P" は期間指定子、'T' は時間指定子、'H' は時間指定子です。 M を使用して、期間の分数を示します。たとえば、2 時間 30 分は "PT2H30M" になります。 会議の期間を指定しない場合、findMeetingTimes は既定値の 30 分を使用します。 省略可能です。
minimumAttendeePercentage Edm.Double 応答で返される時間帯に最低限要求される確度です。 割合 (%) の値 (0 から 100 まで)。 省略可能です。
returnSuggestionReasons Edm.Boolean suggestionReason プロパティで会議の提案ごとに理由を返すには、 を指定Trueします。 既定値は false であり、そのプロパティを返しません。 省略可能です。
timeConstraint timeConstraint 会議の時間制限。これには、会議の性質 (activityDomain プロパティ) と会議の期間 (timeSlots プロパティ) が含まれます。 findMeetingTimes では、 このパラメーターを指定しないかのように activityDomainwork が想定されます。 省略可能です。

timeConstraint パラメーターに指定できるその他の制限について、次の表で説明します。

TimeConstraint の activityDomain 値 会議の時間の候補
作業時間 提案は、ユーザーの予定表構成で定義され、ユーザーまたは管理者によってカスタマイズできるユーザーの勤務時間内です。 既定の勤務時間は、メールボックスのタイム ゾーン セットの月曜日から金曜日の午前 8 時から午後 5 時です。 activityDomain が指定されていない場合、これは既定値です。
personal 提案は、ユーザーの勤務時間内、および土曜日と日曜日です。 既定では、メールボックスのタイム ゾーン設定では、月曜日から日曜日、午前 8 時から午後 5 時です。
Unrestricted 任意の曜日の任意の時刻から候補が提案されます。
不明 この値は、今後非推奨になる予定であるため使用しないでください。 現在、 は と work同じように動作します。 を使用workpersonalするように、またはunrestricted必要に応じて既存のコードを変更します。

指定したパラメーターに基づいて、findMeetingTimes は開催者と出席者の標準として設定されている予定表で空き時間状態を確認します。 アクションは、開催できる可能性が最も高い会議の日時を計算し、会議の提案を返します。

応答

成功した場合、このメソッドは 200 OK 応答コードと、応答本文に入った meetingTimeSuggestionsResult を返します。

meetingTimeSuggestionsResult には、会議提案のコレクションと emptySuggestionsReason プロパティが含まれます。 各提案は、meetingTimeSuggestion として定義され、出席者の参加の確度について、平均で 50% またはminimumAttendeePercentage パラメーターで指定した特定の割合 (%) が付されます。

既定では、会議の日時についての各提案は UTC で返されます。

findMeetingTimes が会議提案を返すことができない場合は、応答で、emptySuggestionsReason プロパティに理由が示されます。 この値に基づいて、パラメーターをさらに調整して、findMeetingTimes を再度呼び出すことができます。

会議の提案の確実性

meetingTimeSuggestion の confidence プロパティの範囲は 0% から 100% で、各個人の空き時間状態に基づいて会議に出席するすべての出席者の見込みを表します。

  • 各出席者に関する、指定の会議期間の空き状態で、確実に出席する場合は 100%、不明な状態は 49%、忙しい場合には 0% です。
  • 会議時間の提案の確実性は、指定された対象会議のすべての出席者の出席見込みの平均によって算出されます。
  • 会議時間の提案が複数ある場合、findMeetingTimes アクションは、算出した確実性が高い方から順番に提案を並べて示します。 確実性が同じ提案がある場合には、時系列で提案を並べて示します。
  • findMeetingTimes に minimumAttendeePercentage 省略可能なパラメーターを使用して、少なくとも特定の信頼度レベルの会議時間候補のみを指定できます。 たとえば、すべての出席者が出席する可能性が 80% 以上の提案のみを必要とする場合は、 minimumAttendeePercentage を 80% に指定できます。 minimumAttendeePercentage を指定しない場合、findMeetingTimes は 50% の値を想定します。

たとえば、提案の会議時間に次の空き時間状態の 3 人の出席者がいるとします。

出席者 空き時間状態 出席見込み (%)
Dana 空き 100%
John 不明 49%
Samantha 多忙 0%

この場合、出席の平均見込みである会議時間の提案の信頼度は、(100% + 49% + 0%)/3 = 49.66% です。

findMeetingTimes 操作で minimumAttendeePercentage を 80% に指定した場合、49.66% 80% < であるため、この操作は応答でこの時間を推奨しません。

例

次の例は、要求本文で次のパラメーターを指定して、あらかじめ決められた会議を開催する時間を検索し、各提案の理由を要求する方法を示しています。

  • attendees
  • locationConstraint
  • timeConstraint
  • isOrganizerOptional
  • meetingDuration
  • returnSuggestionReasons
  • minimumAttendeePercentage

findMeetingTimes が任意の提案を返す場合は、returnSuggestionReasons パラメーターを設定することで、各提案の SuggestionReason プロパティの説明も取得できます。

この要求では PST タイム ゾーンで時間を指定します。 既定では、UTC での会議の時間の候補を応答で返します。 PST を指定するのに、また応答の時間の値にも Prefer: outlook.timezone 要求ヘッダーを使うことができます。

要求

要求の例を次に示します。

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

{
  "attendees": [
    {
      "type": "required",
      "emailAddress": {
        "name": "Alex Wilbur",
        "address": "alexw@contoso.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
}
応答

応答の例を次に示します。 注: ここに示す応答オブジェクトは、読みやすさのために短縮されている場合があります。

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$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.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.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.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.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.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"
                }
            }
        }
    ]
}