user: findMeetingTimes

Namespace: microsoft.graph

Localize as sugestões de hora da reunião com base no organizador e na disponibilidade dos participantes, assim como nas restrições de horário ou local especificadas como parâmetros.

Se findMeetingTimes não retorna nenhuma sugestão de reunião, a resposta seria indicar um motivo na propriedade emptySuggestionsReason. Com base nesse valor, é possível ajustar melhor os parâmetros e a chamada findMeetingTimes novamente.

O algoritmo usado para ilustrar horários de reunião e locais passa por ajuste fino de tempos em tempos. Cenários como ambientes de teste onde permanecem estáticos parâmetros de entrada e dados de calendário, espere que os resultados sugeridos sejam diferentes ao longo do tempo.

Essa API está disponível nas seguintes implantações nacionais de nuvem.

Serviço global Governo dos EUA L4 GOVERNO DOS EUA L5 (DOD) China operada pela 21Vianet

Permissões

Escolha a permissão ou as permissões marcadas como menos privilegiadas para essa API. Use uma permissão ou permissões privilegiadas mais altas somente se o aplicativo exigir. Para obter detalhes sobre permissões delegadas e de aplicativo, consulte Tipos de permissão. Para saber mais sobre essas permissões, consulte a referência de permissões.

Tipo de permissão Permissões menos privilegiadas Permissões privilegiadas mais altas
Delegado (conta corporativa ou de estudante) Calendars.Read.Shared Calendars.ReadWrite.Shared
Delegado (conta pessoal da Microsoft) Sem suporte. Sem suporte.
Aplicativo Sem suporte. Sem suporte.

Solicitação HTTP

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

Cabeçalhos de solicitação

Nome Valor
Autorização {token} de portador. Obrigatório. Saiba mais sobre autenticação e autorização.
Prefira: outlook.timezone Uma cadeia de caracteres que representa um fuso horário específico para a resposta; por exemplo, "Hora Oficial do Pacífico". Opcional. O UTC será usado se esse cabeçalho não for especificado.

Corpo da solicitação

Todos os parâmetros suportados estão listados abaixo. Dependendo do cenário, especifique um objeto JSON para cada um dos parâmetros necessários no corpo da solicitação.

Parâmetro Tipo Descrição
attendees Coleção attendeeBase Uma coleção de participantes ou recursos da reunião. Como findMeetingTimes pressupõe que qualquer participante que seja uma pessoa é sempre necessário, especifique required para uma pessoa e resource para um recurso na propriedade de tipo correspondente. Uma coleção vazia faz com que findMeetingTimes procure gratuitamente alocações de tempo somente para o organizador. Opcional.
isOrganizerOptional Edm.Boolean Especifique True se o organizador não precisa necessariamente comparecer. O padrão é false. Opcional.
locationConstraint locationConstraint Os requisitos do organizador sobre o local da reunião, tal como se é necessário sugerir de um local de encontro, ou há locais específicos apenas onde a reunião pode ocorrer. Opcional.
maxCandidates Edm.Int32 O número máximo de sugestões de horários de reunião a ser retornados. Opcional.
meetingDuration Edm.Duration A duração da reunião, indicada no formato ISO8601. Por exemplo, 1 hora é denotada como 'PT1H', em que 'P' é o designador de duração, 'T' é o designador de hora e 'H' é o designador de hora. Use M para indicar minutos para a duração; por exemplo, 2 horas e 30 minutos seriam "PT2H30M". Se a duração da reunião não for especificada, findMeetingTimes usará o padrão de 30 minutos. Opcional.
minimumAttendeePercentage Edm.Double O mínimo necessário de confiança para um intervalo de tempo a ser retornado na resposta. É um valor de % variando de 0 a 100. Opcional.
returnSuggestionReasons Edm.Boolean Especifique True para retornar um motivo para cada sugestão de reunião na propriedade suggestionReason . O padrão é false para não retornar essa propriedade. Opcional.
timeConstraint timeConstraint Quaisquer restrições de tempo para uma reunião, que podem incluir a natureza da reunião (propriedade activityDomain ) e possíveis períodos de reunião (propriedade timeSlots ). findMeetingTimes pressupõe activityDomain como work se você não especificasse esse parâmetro. Opcional.

A tabela a seguir descreve as restrições activityDomain que você pode especificar ainda mais no parâmetro timeConstraint.

Valor activityDomain Sugestões de horário para reuniões
trabalho As sugestões estão dentro das horas de trabalho do usuário que são definidas na configuração do calendário do usuário e podem ser personalizadas pelo usuário ou administrador. O horário de trabalho padrão é de segunda a sexta, das 8h às 17h, no fuso horário definido para a caixa de correio. Esse é o valor padrão se nenhuma atividadeDomain for especificada.
pessoal As sugestões estão dentro do horário de trabalho do usuário e nos sábados e domingos. O padrão é de segunda a domingo, das 8h às 17h, na configuração do fuso horário da caixa de correio.
irrestrito As sugestões podem ser todas as horas do dia, todos os dias da semana.
desconhecido Não use esse valor, pois ele será preterido no futuro. Atualmente, se comporta da mesma forma que work. Altere qualquer código existente para usar workouunrestricted, personal conforme apropriado.

Com base nos parâmetros especificados,findMeetingTimes verifica o status disponível/ocupado nos calendários principais do organizador e dos participantes. A ação calcula os melhores possíveis horários de reuniões e retorna as sugestões de reunião.

Resposta

Se bem-sucedido, este método retorna o código de resposta 200 OK e o recurso meetingTimeSuggestionsResult no corpo da resposta.

Um meetingTimeSuggestionsResult inclui uma coleção de sugestões de reunião e uma propriedade emptySuggestionsReason. Cada sugestão é definida como uma meetingTimeSuggestion, e participantes com um nível de confiança de 50% na média para participar ou uma % específica que definida no parâmetro minimumAttendeePercentage.

Por padrão, cada sugestão de horário de reunião é retornado em UTC.

Se findMeetingTimes não retorna nenhuma sugestão de reunião, a resposta seria indicar um motivo na propriedade emptySuggestionsReason. Com base nesse valor, é possível ajustar melhor os parâmetros e a chamada findMeetingTimes novamente.

A confiança de uma sugestão de reunião

A propriedade confidence de uma meetingTimeSuggestion varia de 0% a 100% e representa a chance de que todos os participantes compareçam à reunião, com base em seu status disponível/ocupado:

  • Para cada participante, um status livre para um período de tempo de reunião especificado corresponde à chance de 100% de presença, status desconhecido 49% e status ocupado 0%.
  • A confiança na sugestão de um horário de reunião é calculada pela média da chance de presença de todos os participantes especificados para essa reunião.
  • Você pode usar o parâmetro opcional minimumAttendeePercentagefindMeetingTimes para especificar que apenas as sugestões de horário da reunião com pelo menos determinado nível de confiança retornem. Por exemplo, você pode especificar uma minimumAttendeePercentage de 80% se você quiser apenas sugestões que tenham uma chance de 80% ou mais de que todos os participantes comparecerão. Se você não especificar minimumAttendeePercentage, findMeetingTimes pressupõe um valor de 50%.
  • Se houver diversas sugestões de horário de reunião, a ação findMeetingTimes primeiramente classifica as sugestões por seu valor de confiança computado que vai de alto para baixo. Se houver sugestões com a mesma confiança, a ação ordena essas sugestões em ordem cronológica.

Por exemplo, se uma sugestão de horário de reunião envolve três participantes com o seguinte status livre/ocupado:

Participante Status disponível/ocupado % de chance de comparecer
Sara Disponível 100%
Davi Desconhecido 49%
Sara Ocupado 0%

Então a confiança na sugestão do horário da reunião, que corresponde à chance média de presença, é (100% + 49% + 0%) /3 = 49.66%.

Se você especificar um mínimoAttendeePercentage de 80% em uma operação findMeetingTimes , porque 49,66% < 80%, a operação não sugerirá desta vez na resposta.

Exemplo

O exemplo a seguir mostra como encontrar um horário para reunir-se em um local predeterminado e solicitar um motivo para cada sugestão, especificando os seguintes parâmetros no corpo da solicitação:

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

Definindo o parâmetro returnSuggestionReasons, você também obtém uma explicação na propriedade suggestionReason para cada sugestão, se findMeetingTimes retornar qualquer sugestão.

Observe que a solicitação especifica o tempo no fuso horário PST. Por padrão, a resposta retorna horário em sugestões UTC. Você pode usar o cabeçalho Prefer: outlook.timezone para especificar os valores de horário para o Horário Padrão do Pacífico na resposta.

Solicitação

Aqui está a solicitação de exemplo.

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.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
}
Resposta

Aqui está uma resposta de exemplo. Observação: o objeto de resposta mostrado aqui pode ser encurtado para legibilidade.

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.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"
                }
            }
        }
    ]
}