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 mostrem o status dos usuários do Google Agenda. Os eventos de status descrevem onde os usuários estão ou o que ela está fazendo, incluindo se está no horário de concentração, fora do escritório ou trabalhando em um determinado local.

No Google Agenda, os usuários podem criar horários de concentração, "fora do escritório" e "trabalhando" eventos de local para indicar o status e o local personalizados deles. Esses recursos são disponível 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 usuários do Google Cloud.

Ler e listar eventos de status do Google Agenda

É possível ler e listar eventos de status da agenda no O recurso Events do 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, inspecione se o O campo eventType tem o solicitado, e consulte o campo correspondente para obter 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 alterações nos eventos de status no O recurso Events do API Calendar.

Use o método events.watch, especificando o calendarId das Agenda na qual assinar e um ou mais dos seguintes valores na 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 Events usando o método events.insert, definindo o campos obrigatórios para o tipo de evento.

Se você atualizar o evento de status usando método events.update, o evento precisa 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 parâmetro focusTimeProperties .
• Defina o transparency. como 'opaque'.
• Defina os start e Campos end para serem 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.

Confira mais detalhes em Usar o horário de concentração no Google Agenda

Criar evento "Fora do escritório"

Para criar um evento "Fora do escritório":

• Defina eventType como 'outOfOffice'.
• Inclua o parâmetro outOfOfficeProperties .
• Defina o transparency. como 'opaque'.
• Defina os start e Campos end para serem 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 inteiro.

Confira detalhes do recurso em Mostrar quando você estiver sem apps escritório

Criar local de trabalho

Para criar um evento de local de trabalho:

• Defina eventType como 'workingLocation'.
• Inclua o parâmetro workingLocationProperties .
• Definir o campo visibility para 'public'.
• Defina o transparency. como 'transparent'.

• Defina os start e end como:

  • um evento cronometrado (com horários de início e término especificados);
  • 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 eventos cronometrados conseguem.

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

• workingLocationProperties.officeLocation.buildingId Ele precisa corresponder a um buildingId no recursos no seu banco de dados. Isso ajuda os usuários a aproveitar todos os recursos do app Agenda, como sugestões de salas.
• workingLocationProperties.officeLocation.label É o marcador mostrado na Web e em clientes de dispositivos móveis do Agenda. Você pode buscar IDs e rótulos de edifício usando o resources.buildings.list .

Criar e atualizar eventos de local de trabalho usando endpoints em lote não é suporte.

Confira mais detalhes sobre os recursos em Definir seu horário de trabalho e localização e Ativar ou desativar o local de trabalho para usuários

Como mostrar eventos sobrepostos de local de trabalho

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 momento pode ter múltiplos horários e os locais definidos para ela. Quando apenas um local pode ser exibido para o usuário, ele deve ver esse local de forma consistente em vários aplicativos conteinerizados. Ao fazer isso, use as seguintes diretrizes para escolher quais a ser exibido:

• Eventos cronometrados levam precedência sobre os eventos de dia inteiro.
• Eventos únicos têm precedência sobre eventos recorrentes e os exceções.
• Os eventos que começam mais tarde têm precedência em relação aos que começam mais cedo.
• Eventos com duração mais curta têm precedência sobre aqueles com duração mais longa durações.
• Eventos criados mais recentemente têm precedência em relação aos criados antes.
• Eventos parcialmente sobrepostos precisam ser mostrados como dois eventos diferentes cada com um local de trabalho próprio.

Criar eventos de status no Google Apps Script

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

As instruções a seguir descrevem como gerenciar eventos de status usando o API Google Calendar como um serviço avançado nas Google Apps Script. Para uma lista completa de 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 à esquerda ao lado de Serviços, clique em Adicionar um serviço add .
3. Selecione API Google Calendar e clique em Adicionar.
4. Depois de ativada, a API aparece no painel esquerdo. Métodos e classes na API podem ser listadas usando a palavra-chave Calendar no editor.

Atualizar o projeto do Google Cloud (opcional)

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

1. No lado esquerdo do editor, clique em "Configurações do projeto" settings:
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 curso "Desenvolvedor" Visualizar programa e clique em Definir projeto.
4. No lado esquerdo, selecione Editor code para volte 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:

   /** 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. Revisar e permitir Apps Script para acessar sua agenda.
3. É possível inspecionar os resultados da execução do script no Registro de execução exibido na parte inferior da janela.