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

Esta página explica como usar a API Google Agenda 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 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 de horário de concentração, fora do escritório e de local de trabalho para indicar o status e o local personalizados. Esses recursos estão disponíveis apenas nas agendas principais e para alguns usuários do Google Agenda.

Confira 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

É possível ler e listar eventos de status da 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 saber detalhes sobre o status criado pelo usuário no Google Agenda:

• focusTimeProperties
• outOfOfficeProperties
• workingLocationProperties

Inscrever-se em mudanças nos eventos de status

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

Use o método events.watch, especificando o calendarId do calendário para assinar e um ou mais dos seguintes valores no campo eventTypes:

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

Criar e atualizar eventos de status do Google 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, o evento precisará manter os campos obrigatórios.

Criar um 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 eventos de dia inteiro.

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

Criar um aviso de ausência

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 cronometrados (com horários de início e término especificados).
  Os eventos fora do escritório não podem ser de dia inteiro.

Confira detalhes sobre o recurso em Mostrar quando você está 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 dura exatamente um dia.

  Os eventos de local de trabalho de dia inteiro não podem durar vários dias, mas os eventos com hora marcada podem.

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

• workingLocationProperties.officeLocation.buildingId: precisa corresponder a um buildingId no banco de dados recursos da organização. Isso ajuda os usuários a aproveitar todos os recursos do app Agenda, por exemplo, as sugestões de salas.
• workingLocationProperties.officeLocation.label: é o rótulo mostrado nos clientes da Web e móveis do Google Agenda. Você pode buscar IDs e rótulos de edifícios usando o método resources.buildings.list.

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

Para saber mais sobre o recurso, acesse Definir seu horário de trabalho e local e Ativar ou desativar o local de trabalho para usuários.

Como mostrar eventos de local de trabalho sobrepostos

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

• Os eventos programados têm precedência sobre os eventos de dia inteiro.
• Os eventos únicos têm precedência sobre os eventos recorrentes e as exceções deles.
• Os eventos que começam mais tarde têm precedência sobre os que começam mais cedo.
• Eventos com durações mais curtas têm precedência sobre aqueles com durações mais longas.
• Os eventos criados mais recentemente têm precedência sobre os que foram criados antes.
• 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 baseada em JavaScript na nuvem que permite criar aplicativos empresariais integrados ao Google Workspace. Os scripts são desenvolvidos em um editor de código baseado em navegador e 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 para enviar solicitações à API Google Agenda.

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

Criar e configurar o script

1. Acesse script.google.com/create para criar um script.
2. No painel à esquerda, ao lado de Serviços, clique em Adicionar um serviço .
3. Selecione API Google Agenda e clique em Adicionar.
4. Depois de ativada, a API vai aparecer no painel à esquerda. Os métodos e as 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 associado do Google Cloud. O script pode usar o projeto padrão criado automaticamente pelo Google Apps Script. 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é-lançamento 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 sua agenda principal.

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

   primary é uma palavra-chave para acessar o principal calendário do usuário conectado. Para recuperar eventos em uma agenda diferente, defina o parâmetro calendarId como um endereço de e-mail. Assim, é possível ler eventos de status nas agendas de outros usuários a que você tem acesso com o mínimo de disponibilidade. As 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, você vai precisar autorizar o acesso. Revise e permita que o Apps Script acesse sua agenda.
3. É possível inspecionar os resultados da execução do script no Execution Log que aparece na parte de baixo da janela.