Gerencie eventos "Horário de concentração", "Fora do escritório" e "Local de trabalho"

Esta página explica como usar a API Google Calendar para criar eventos que mostram o status dos usuários do Google Agenda. Os eventos de status descrevem onde os usuários estão ou o que eles estão fazendo, incluindo se estão no horário de concentração, fora do escritório ou trabalhando em um determinado local.

No Google Agenda, os usuários podem criar eventos "Horário de concentração", "Fora do escritório" e "Local de trabalho" para indicar o status e a localização personalizados. Esses recursos estão disponíveis apenas nas agendas principais e para alguns usuários do Google Agenda.

Veja mais detalhes em Usar o horário de concentração no Google Agenda e Ativar ou desativar o local de trabalho para os usuários.

Ler e listar eventos de status da Agenda

Você pode ler e listar os eventos de status do Agenda no recurso Events da API Calendar.

Para ler um evento de status, use o método events.get, especificando o eventId do evento.

Para listar eventos de status, use o método events.list, especificando um ou mais dos seguintes valores no campo eventTypes:

• 'focusTime'
• 'outOfOffice'
• 'workingLocation'

Em seguida, nos objetos Event retornados, verifique se o campo eventType tem o valor solicitado e consulte o campo correspondente para ver detalhes sobre o status criado pelo usuário no Google Agenda:

• focusTimeProperties
• outOfOfficeProperties
• workingLocationProperties

Inscrever-se para receber alterações em eventos de status

Você pode se inscrever para receber as mudanças nos eventos de status no recurso Events da API Calendar.

Use o método events.watch, especificando o calendarId da Agenda para assinatura e um ou mais dos seguintes valores no campo eventTypes:

• 'focusTime'
• 'outOfOffice'
• 'workingLocation'

Criar e atualizar eventos de status da Agenda

Para criar um evento de status, crie uma instância do recurso Events usando o método events.insert, definindo os campos obrigatórios para o tipo de evento.

Se você atualizar o evento de status usando o método events.update, ele precisará manter os campos obrigatórios.

Criar horário de concentração

Para criar um evento "Horário de concentração":

• Defina eventType como 'focusTime'.
• Inclua o campo focusTimeProperties.
• Defina o campo transparency como 'opaque'.
• Defina os campos start e end do evento como um evento cronometrado (com horários de início e término especificados).
  Os horários de concentração não podem ser de dia inteiro.

Para mais detalhes sobre o recurso, acesse Usar o horário de concentração no Google Agenda.

Criar fora do escritório

Para criar um evento fora do escritório:

• Defina eventType como 'outOfOffice'.
• Inclua o campo outOfOfficeProperties.
• Defina o campo transparency como 'opaque'.
• Defina os campos start e end do evento como um evento cronometrado (com horários de início e término especificados).
  Os eventos "fora do escritório" não podem durar o dia todo.

Para detalhes sobre os recursos, acesse Mostrar quando você estiver fora do escritório.

Criar local de trabalho

Para criar um evento de local de trabalho:

• Defina eventType como 'workingLocation'.
• Inclua o campo workingLocationProperties.
• Defina o campo visibility como 'public'.
• Defina o campo transparency como 'transparent'.

• Defina os campos start e end do evento como:

  • um evento cronometrado (com horários de início e término especificados);
  • Um evento de dia inteiro (com datas de início e término especificadas) que abrange exatamente um dia.

  Os eventos de local de trabalho que duram o dia todo não podem abranger vários dias, mas os eventos com marcação de tempo podem.

Os campos a seguir são opcionais, mas recomendados para melhorar a experiência do usuário ao inserir um officeLocation:

• workingLocationProperties.officeLocation.buildingId: precisa corresponder a um buildingId no banco de recursos da organização. Isso ajuda os usuários a aproveitar todos os recursos do Agenda, como as sugestões de sala.
• workingLocationProperties.officeLocation.label: é o marcador mostrado nos clientes de dispositivos móveis e da Web do Agenda. É possível buscar IDs e rótulos de criação usando o método resources.buildings.list.

Não é possível criar e atualizar eventos de local de trabalho por endpoints em lote.

Confira mais detalhes em Definir seu horário de trabalho e local e Ativar ou desativar o local de trabalho para os usuários.

Como mostrar eventos de local de trabalho sobrepostos

Um usuário pode ter vários eventos de local de trabalho ao mesmo tempo na agenda que se sobrepõem, o que significa que qualquer momento pode ter vários locais de trabalho definidos para ele. Nas circunstâncias em que apenas um local pode ser mostrado ao usuário, essa informação precisa ser mostrada de forma consistente em vários apps. Ao fazer isso, use as diretrizes a seguir para escolher qual evento mostrar:

• Eventos com marcação de tempo têm precedência sobre eventos de dia inteiro.
• Eventos únicos têm precedência sobre eventos recorrentes e as respectivas exceções.
• Os eventos que começam depois têm prioridade sobre aqueles que começam antes.
• Os eventos com duração mais curta têm precedência sobre aqueles com durações mais longas.
• Os eventos criados mais recentemente têm precedência sobre aqueles que foram criados anteriormente.
• Eventos parcialmente sobrepostos precisam ser mostrados como dois eventos diferentes, cada um com o próprio local de trabalho.

Criar eventos de status no Google Apps Script

O Google Apps Script é uma linguagem de script em nuvem baseada em JavaScript que permite criar aplicativos empresariais que se integram ao Google Workspace. Os scripts são desenvolvidos em um editor de código baseado em navegador. Eles são armazenados e executados nos servidores do Google. Consulte também o guia de início rápido do Google Apps Script para começar a usar o Apps Script e enviar solicitações à API Google Calendar.

As instruções a seguir descrevem como gerenciar eventos de status usando a API Google Calendar como um serviço avançado no Google Apps Script. Para ver uma lista completa dos recursos e métodos da API Google Calendar, consulte a documentação de referência.

Criar e configurar o script

1. Crie um script acessando script.google.com/create.
2. No painel esquerdo, ao lado de Serviços, clique em Adicionar um serviço .
3. Selecione API Google Calendar e clique em Adicionar.
4. Depois de ativada, a API aparece no painel esquerdo. Os métodos e classes disponíveis na API podem ser listados usando a palavra-chave Calendar no editor.

(Opcional) Atualizar o projeto do Google Cloud

Cada projeto do Google Apps Script tem um projeto do Google Cloud associado. Seu script pode usar o projeto padrão que o Google Apps Script cria automaticamente. Se você quiser usar um projeto personalizado do Google Cloud, siga as etapas abaixo para atualizar o projeto associado ao script.

1. No lado esquerdo do editor, clique em Configurações do projeto .
2. Em Projeto do Google Cloud Platform (GCP), clique em Mudar projeto.
3. Insira o número do projeto do Google Cloud que está no Programa de prévia para desenvolvedores e clique em Definir projeto.
4. No lado esquerdo, selecione Editor para voltar ao editor de código.

Adicionar código ao script

O exemplo de código a seguir mostra como criar, ler e listar eventos de status na agenda principal.

1. Cole o seguinte no editor de código.

   primary é uma palavra-chave para acessar a agenda principal do usuário conectado. Para recuperar eventos em uma agenda diferente, defina o parâmetro calendarId como um endereço de e-mail. Isso permite que você leia eventos de status nas agendas de outros usuários a que você tenha, no mínimo, acesso disponível/ocupado. Agendas secundárias não podem ter eventos de status.

   /** Creates a focus time event. */
   function createFocusTime() {
     const event = {
       start: { dateTime: '2023-11-14T10:00:00+01:00' },
       end: { dateTime: '2023-11-14T12:00:00+01:00' },
       eventType: 'focusTime',
       focusTimeProperties: {
         chatStatus: 'doNotDisturb',
         autoDeclineMode: 'declineOnlyNewConflictingInvitations',
         declineMessage: 'Declined because I am in focus time.',
       }
     }
     createEvent(event);
   }
   
   /** Creates an out of office event. */
   function createOutOfOffice() {
     const event = {
       start: { dateTime: '2023-11-15T10:00:00+01:00' },
       end: { dateTime: '2023-11-15T18:00:00+01:00' },
       eventType: 'outOfOffice',
       outOfOfficeProperties: {
         autoDeclineMode: 'declineOnlyNewConflictingInvitations',
         declineMessage: 'Declined because I am on vacation.',
       }
     }
     createEvent(event);
   }
   
   /** Creates a working location event. */
   function createWorkingLocation() {
     const event = {
       start: { date: "2023-06-01" },
       end: { date: "2023-06-02" },
       eventType: "workingLocation",
       visibility: "public",
       transparency: "transparent",
       workingLocationProperties: {
         type: 'customLocation',
         customLocation: { label: "a custom location" },
       }
     }
     createEvent(event);
   }
   
   /**
     * Creates a Calendar event.
     * See https://developers.google.com/calendar/api/v3/reference/events/insert
     */
   function createEvent(event) {
     const calendarId = 'primary';
   
     try {
       var response = Calendar.Events.insert(event, calendarId);
       var event = (response.eventType === 'workingLocation') ? parseWorkingLocation(response) : response;
       console.log(event);
     } catch (exception) {
       console.log(exception.message);
     }
   }
   
   /**
     * Reads the event with the given eventId.
     * See https://developers.google.com/calendar/api/v3/reference/events/get
     */
   function readEvent() {
     const calendarId = 'primary';
   
     // Replace with a valid eventId.
     const eventId = "sample-event-id";
   
     try {
       var response = Calendar.Events.get(calendarId, eventId);
       var event = (response.eventType === 'workingLocation') ? parseWorkingLocation(response) : response;
       console.log(event);
     } catch (exception) {
       console.log(exception.message);
     }
   }
   
   /** Lists focus time events. */
   function listFocusTimes() {
     listEvents('focusTime');
   }
   
   /** Lists out of office events. */
   function listOutOfOffices() {
     listEvents('outOfOffice');
   }
   
   /** Lists working location events. */
   function listWorkingLocations() {
     listEvents('workingLocation');
   }
   
   /**
     * Lists events with the given event type.
     * See https://developers.google.com/calendar/api/v3/reference/events/list
     */
   function listEvents(eventType = 'default') {
     const calendarId = 'primary'
   
     // Query parameters for the list request.
     const optionalArgs = {
       eventTypes: [eventType],
       showDeleted: false,
       singleEvents: true,
       timeMax: '2023-04-01T00:00:00+01:00',
       timeMin: '2023-03-27T00:00:00+01:00',
     }
     try {
       var response = Calendar.Events.list(calendarId, optionalArgs);
       response.items.forEach(event =>
         console.log(eventType === 'workingLocation' ? parseWorkingLocation(event) : event));
     } catch (exception) {
       console.log(exception.message);
     }
   }
   
   /**
     * Parses working location properties of an event into a string.
     * See https://developers.google.com/calendar/api/v3/reference/events#resource
     */
   function parseWorkingLocation(event) {
     if (event.eventType != "workingLocation") {
       throw new Error("'" + event.summary + "' is not a working location event.");
     }
   
     var location = 'No Location';
     const workingLocation = event.workingLocationProperties;
     if (workingLocation) {
       if (workingLocation.type === 'homeOffice') {
         location = 'Home';
       }
       if (workingLocation.type === 'officeLocation') {
         location = workingLocation.officeLocation.label;
       }
       if (workingLocation.type === 'customLocation') {
         location = workingLocation.customLocation.label;
       }
     }
     return `${event.start.date}: ${location}`;
   }
   

Executar a amostra de código

1. Acima do editor de código, selecione a função a ser executada no menu suspenso e clique em Executar.
2. Na primeira execução, ele solicita que você autorize o acesso. Analise e permita que o Apps Script acesse sua agenda.
3. É possível inspecionar os resultados da execução do script no Registro de execução que aparece na parte inferior da janela.