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 os possíveis horários de reunião que satisfaçam a hora, o local e outras restrições.
A ação findMeetingTimes permite especificar condições como o intervalo de data/hora da reunião, duração, participantes opcionais ou obrigatórios e a natureza da atividade (activityDomain). A ação leva em conta as agendas de trabalho normais dos participantes e dos organizadores e as status gratuitas/ocupadas e sugere horários apropriados para os participantes e o tipo de atividade. Por exemplo, as 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 em que 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 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 findMeetingTimes retorne sugestões 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 nenhum horário de reunião, ele 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 dois usuários se reunirem por algumas horas, levando em conta as agendas gratuitas/ocupadas e de trabalho dos usuários e o participante ficar fora por parte do tempo. Como há apenas dois usuários para essa reunião, as sugestões exigem 100% de presença. A seguir, mostra a agenda gratuita/ocupada dos usuários.
Calendário do organizador
Calendário do participante
O exemplo faz 2 chamadas para findMeetingTimes:
- A primeira chamada está no intervalo de datas de 18 a 20 de abril. Como o participante está fora do escritório nos dias 18 e 19 de abril, e não há horário disponível em 20 de abril, a primeira chamada não retorna nenhuma sugestão com o motivo (emptySuggestionsReason) de que os participantes não estão disponíveis.
- 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
requiredpara 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 ter findMeetingTimes sugerir um tempo se a confiança para o atendimento atingir uma determinada porcentagem, especificando 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 apropriado para reuniões de tamanhos maiores.
Depois de receber sugestões de horário de reunião, você talvez queira:
Veja mais detalhes em integração com o calendário do Outlook.