Encontrar possíveis horários de reunião no calendário do Outlook

Seja no trabalho ou em uma instituição de ensino, procurar um horário e local em comum para uma reunião geralmente significa uma sobrecarga. Os aplicativos do Microsoft Graph podem usar findMeetingTimes para identificar possíveis horários de reunião que satisfaçam o horário, o local e outras restrições.

A ação findMeetingTimes permite especificar condições como intervalo de data/hora da reunião, duração, participantes opcionais ou obrigatórios e natureza da atividade (activityDomain). A ação leva em consideração os horários normais de trabalho dos participantes e do organizador e o status de disponibilidade e sugere horários apropriados para os participantes e o tipo de atividade. Por exemplo, sugestões para uma atividade relacionada ao trabalho sempre ocorrem durante o horário de trabalho do organizador e dos participantes, e as sugestões onde os participantes necessários estão disponíveis são ordenadas mais acima na lista sugerida.

No Microsoft 365, as horas de trabalho e os fusos horários são configuráveis por caixa de correio. A ação findMeetingTimes lida com as variações de fuso horário entre o organizador e os participantes. Por padrão, findMeetingTimes retorna sugestões em UTC. Você pode usar o cabeçalho de solicitação a seguir para que as sugestões de retorno de findMeetingTimes sejam expressas em um fuso horário específico.

Prefer: outlook.timezone="{time-zone-string}}"

Especialmente útil para reuniões maiores, você pode especificar um percentual (minimumAttendeePercentage) de quorum e fazer com que findMeetingTimes retorne sugestões somente se essa disponibilidade mínima de participantes for atingida.

Se findMeetingTimes não puder sugerir horários de reunião, isso indicará um motivo específico (emptySuggestionsReason), como o organizador ou um participante necessário não disponível. Com base nesse valor, é possível ajustar melhor os parâmetros e a chamada findMeetingTimes novamente.

Observação

A ação findMeetingTimes está atualmente disponível para caixas de correio de trabalho ou escolares da Microsoft 365, mas não para caixas de correio pessoais do outlook.com.

Exemplo

O exemplo a seguir mostra como usar findMeetingTimes para retornar horários possíveis para 2 usuários se reunirem por algumas horas, levando em consideração os horários de trabalho e disponibilidade dos usuários e o participante ausente parte do tempo. Como há apenas 2 usuários para esta reunião, as sugestões exigem 100% de participação. O diagrama a seguir mostra a agenda de disponibilidade dos usuários.

Calendário do organizador

O calendário de trabalho do organizador para 17 a 21 de abril mostrando os horários de disponibilidade

Calendário do participante

O calendário de trabalho do participante de 17 a 21 de abril mostrando os horários de disponibilidade

O exemplo faz 2 chamadas para findMeetingTimes:

  1. A primeira chamada analisa o intervalo de datas de 18 a 20 de abril. Como o participante está fora do escritório de 18 a 19 de abril e não há horário comumente disponível em 20 de abril, a primeira chamada não retorna sugestões com o motivo (emptySuggestionsReason) de que os participantes não estão disponíveis.
  2. A segunda chamada analisa a disponibilidade em 21 de abril e retorna uma sugestão das 14h às 16h.

As duas chamadas para findMeetingTimes incluem os parâmetros a seguir. Todos os parâmetros para findMeetingTimes são opcionais.

  • attendees: um participante, Sara Melo, definido como required para a propriedade type
  • locationConstraint: não requer nenhuma sugestão de localização
  • timeConstraint: a primeira chamada analisa o intervalo de datas/horário de 18 de abril, às 9h, a 20 de abril, às 17h; depois que a primeira chamada não conseguir sugerir nenhum horário, a segunda chamada analisará 21 de abril, das 9h às 17h
  • meetingDuration: duas horas
  • returnSuggestionReasons: este exemplo requer um motivo para cada sugestão
  • minimumAttendeePercentage: 100%, uma vez que o participante deve ser capaz de participar de qualquer horário sugerido

Primeira solicitação

Procure por um intervalo de tempo disponível de 2 horas para ambos os usuários de 18 a 20 abril.

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

{
  "attendees": [
    {
      "type": "required",
      "emailAddress": {
        "name": "Samantha Booth",
        "address": "samanthab@contoso.com"
      }
    }
  ],
  "locationConstraint": {
    "isRequired": false,
    "suggestLocation": false,
    "locations": [
      {
        "resolveAvailability": false,
        "displayName": "Conf room Hood"
      }
    ]
  },
  "timeConstraint": {
    "activityDomain":"work",
    "timeslots": [
      {
        "start": {
          "dateTime": "2017-04-18T09:00:00",
          "timeZone": "Pacific Standard Time"
        },
        "end": {
          "dateTime": "2017-04-20T17:00:00",
          "timeZone": "Pacific Standard Time"
        }
      }
    ]
  },
  "meetingDuration": "PT2H",
  "returnSuggestionReasons": true,
  "minimumAttendeePercentage": 100
}

Primeira resposta

Não há nenhum intervalo de 2 horas durante o horário de trabalho de 18 a 20 de abril em que ambos os usuários estejam disponíveis.

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

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.meetingTimeSuggestionsResult",
    "emptySuggestionsReason":"AttendeesUnavailable",
    "meetingTimeSuggestions":[

    ]
}

Segunda solicitação

Procure um intervalo de tempo de 2 horas em 21 de abril.

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

{
  "attendees": [
    {
      "type": "required",
      "emailAddress": {
        "name": "Samantha Booth",
        "address": "samanthab@contoso.com"
      }
    }
  ],
  "locationConstraint": {
    "isRequired": false,
    "suggestLocation": false,
    "locations": [
      {
        "resolveAvailability": false,
        "displayName": "Conf room Hood"
      }
    ]
  },
  "timeConstraint": {
    "activityDomain":"work",
    "timeslots": [
      {
        "start": {
          "dateTime": "2017-04-21T09:00:00",
          "timeZone": "Pacific Standard Time"
        },
        "end": {
          "dateTime": "2017-04-21T17:00:00",
          "timeZone": "Pacific Standard Time"
        }
      }
    ]
  },
  "meetingDuration": "PT2H",
  "returnSuggestionReasons": true,
  "minimumAttendeePercentage": 100
}

Segunda resposta

A segunda solicitação findMeetingTimes sugere de 21 de abril, das 14h às 16h, para que os dois usuários se reúnam.

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

{
    "@odata.context":"https://graph.microsoft.com/v1.0/$metadata#microsoft.graph.meetingTimeSuggestionsResult",
    "emptySuggestionsReason":"",
    "meetingTimeSuggestions":[
        {
            "confidence":100.0,
            "organizerAvailability":"free",
            "suggestionReason":"Suggested because it is one of the nearest times when all attendees are available.",
            "meetingTimeSlot":{
                "start":{
                    "dateTime":"2017-04-21T14:00:00.0000000",
                    "timeZone":"Pacific Standard Time"
                },
                "end":{
                    "dateTime":"2017-04-21T16:00:00.0000000",
                    "timeZone":"Pacific Standard Time"
                }
            },
            "attendeeAvailability":[
                {
                    "availability":"free",
                    "attendee":{
                        "type":"required",
                        "emailAddress":{
                            "address":"samanthab@contoso.com"
                        }
                    }
                }
            ],
            "locations":[
                {
                    "displayName":"Conf room Hood"
                }
            ]
        }
    ]
}

Próximas etapas

Há momentos em que nem todos os participantes podem participar de uma reunião. Você pode fazer com que o findMeetingTimes sugira um horário se a confiança para o comparecimento atingir uma determinada porcentagem, especificando o parâmetro opcional minimumAttendeePercent . Saiba mais sobre a confiança de uma sugestão de reunião e outros parâmetros e aplique-os conforme apropriado para reuniões de tamanhos maiores.

Depois de receber sugestões de horário de reunião, você talvez queira:

  1. Criar um evento e enviá-lo como uma solicitação de reunião.
  2. Adicionar um anexo a um evento.

Veja mais detalhes em integração com o calendário do Outlook.

  • Last updated on