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

Nesta página, explicamos 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 estão fazendo, incluindo se estão em 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 hora de se concentrar, fora do escritório e 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.

Para mais detalhes, acesse 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 do Google 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, inspecione 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:

Inscrever-se em mudanças nos eventos de status

É possível se inscrever para receber notificações sobre mudanças nos eventos de status no recurso Events da API Calendar.

Use o método events.watch, especificando o calendarId da agenda a ser inscrita 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 e defina os campos obrigatórios para o tipo de evento.

Se você atualizar o evento de status usando o método events.update, o evento precisa 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 com hora marcada (com horários de início e término especificados).
    As horas de se concentrar não podem ser eventos de dia inteiro.

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

Criar um aviso de ausência

Para criar um evento de ausência do trabalho:

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

Para mais detalhes sobre o recurso, acesse 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 com horário (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 abranger vários dias, mas os eventos com horário podem.

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

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

Para mais detalhes 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 locais de trabalho sobrepostos

Um usuário pode ter vários eventos de local de trabalho no calendário ao mesmo tempo que se sobrepõem. Isso 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 exibido de forma consistente em vários aplicativos. Ao fazer isso, use as seguintes diretrizes para escolher qual evento mostrar:

  • Eventos com horário têm precedência sobre eventos de dia inteiro.
  • Os eventos únicos têm precedência sobre os 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 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 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 início rápido do Google Apps Script para começar a usar o Apps Script e 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 uma lista completa de recursos e métodos 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 Calendar e clique em Adicionar.
  4. Depois de ativada, a API aparece no painel à esquerda. 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. O 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 estas etapas para atualizar o projeto associado ao seu 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 no seu calendário 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/workspace/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/workspace/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/workspace/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/workspace/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 pede que você autorize o acesso. Revise 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 de baixo da janela.