Compartilhar via


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.

Esta API está disponível nas seguintes implementações de cloud nacionais.

Serviço global US Government L4 US Government L5 (DOD) China operada pela 21Vianet

Permissões

Escolha a permissão ou permissões marcadas como menos privilegiadas para esta API. Utilize uma permissão ou permissões com privilégios mais elevados apenas se a sua aplicação o exigir. Para obter detalhes sobre as permissões delegadas e de aplicação, veja Tipos de permissão. Para saber mais sobre estas permissões, veja a referência de permissões.

Tipo de permissão Permissões com menos privilégios Permissões com privilégios superiores
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. A UTC é utilizada se este 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. Uma vez que findMeetingTimes assume que qualquer participante que seja uma pessoa é sempre necessário, especifique required para uma pessoa e resource para um recurso na propriedade do 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 tem necessariamente de participar. 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 é indicado como "PT1H", em que "P" é o designador de duração, "T" é o designador de hora e "H" é o designador de hora. Utilize 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 devolver 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 tempo de reunião (propriedade timeSlots ). findMeetingTimes assume activityDomain como work se não especificasse este 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 do horário de trabalho do utilizador, que são definidas na configuração do calendário do utilizador e podem ser personalizadas pelo utilizador 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. Este é o valor predefinido se não for especificado activityDomain .
pessoal As sugestões estão dentro do horário de trabalho do usuário e nos sábados e domingos. A predefinição é de segunda a domingo, das 8h às 17h, na definição de 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 utilize este valor, uma vez que será preterido no futuro. Atualmente, comporta-se da mesma forma que work. Altere qualquer código existente para utilizar work, personal ou unrestricted conforme adequado.

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 especificar um mínimoAttendeePercentage de 80% numa operação findMeetingTimes , porque 49,66% < 80%, a operação não sugerirá este tempo 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"
                }
            }
        }
    ]
}