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. As aplicações do Microsoft Graph podem utilizar findMeetingTimes para identificar eventuais horas de reunião que satisfaçam a hora, a localização e outras restrições.

A ação findMeetingTimes permite-lhe especificar condições como o intervalo de data/hora da reunião, a duração, os participantes opcionais ou necessários e a natureza da atividade (activityDomain). A ação tem em conta os horários de trabalho normais dos participantes e organizadores e status de disponibilidade e sugere horas adequadas para os participantes e o tipo de atividade. Por exemplo, as sugestões para uma atividade relacionada com o trabalho ocorrem sempre 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 processa variações de fuso horário entre o organizador e os participantes. Por predefinição, findMeetingTimes devolve sugestões em UTC. Pode utilizar o seguinte cabeçalho de pedido para que findMeetingTimes devolva sugestões expressas num 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 conseguir sugerir horas de reunião, indica 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.

Exemplo

O exemplo seguinte mostra como utilizar findMeetingTimes para devolver possíveis horas para 2 utilizadores se reunirem durante algumas horas, tendo em conta os horários de disponibilidade e trabalho dos utilizadores e o participante estar ausente durante parte do tempo. Uma vez que existem apenas 2 utilizadores nesta reunião, as sugestões requerem 100% de participação. O seguinte mostra a agenda de disponibilidade dos utilizadores.

Calendário do organizador

Calendário do participante

O exemplo faz 2 chamadas para findMeetingTimes:

1. A primeira chamada é apresentada no intervalo de datas de 18 a 20 de abril. Uma vez que o participante está fora do escritório nos dias 18 e 19 de abril e não existe uma hora normalmente disponível no dia 20 de abril, a primeira chamada não devolve 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 seguintes parâmetros. 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á alturas em que nem todos os participantes podem participar numa reunião. Pode fazer com que findMeetingTimes sugira uma hora se a confiança para assiduidade atingir uma determinada percentagem ao especificar o parâmetro opcional minimumAttendeePercentage . Saiba mais sobre a confiança de uma sugestão de reunião e outros parâmetros e aplique-os conforme adequado 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.