Events: list

Retorna eventos na agenda especificada. Faça um teste agora ou veja um exemplo.

Solicitação

Solicitação HTTP

GET https://www.googleapis.com/calendar/v3/calendars/calendarId/events

Parâmetros

Nome do parâmetro Valor Descrição
Parâmetros de caminho
calendarId string Identificador da agenda. Para recuperar IDs de agendas, chame o método calendarList.list. Se você quiser acessar a agenda principal do usuário conectado, use a palavra-chave "primary".
Parâmetros de consulta opcionais
alwaysIncludeEmail boolean Obsoleto e ignorado.
eventTypes string Tipos de eventos a serem retornados. Opcional. Esse parâmetro pode ser repetido várias vezes para retornar eventos de tipos diferentes. Se não for definido, retornará todos os tipos de evento.

Os valores aceitáveis são:
  • "default": eventos frequentes.
  • "focusTime": eventos "Horário de concentração".
  • "outOfOffice": eventos fora do escritório.
  • "workingLocation": eventos de local de trabalho.
iCalUID string Especifica um ID de evento no formato iCalendar a ser fornecido na resposta. Opcional. Use esta opção se você quiser pesquisar um evento pelo ID do iAgenda.
maxAttendees integer O número máximo de participantes a serem incluídos na resposta. Se houver mais do que o número especificado de participantes, somente o participante será retornado. Opcional.
maxResults integer Número máximo de eventos retornados em uma página de resultados. O número de eventos na página resultante pode ser menor do que esse valor ou nenhum evento, mesmo que haja mais eventos correspondentes à consulta. Páginas incompletas podem ser detectadas por um campo nextPageToken não vazio na resposta. Por padrão, o valor é de 250 eventos. O tamanho da página nunca pode ser maior que 2.500 eventos. Opcional.
orderBy string A ordem dos eventos retornados no resultado. Opcional. O padrão é uma ordem estável e não especificada.

Os valores aceitáveis são:
  • "startTime": ordenar por data/hora de início (crescente). Disponível apenas ao consultar eventos únicos (ou seja, o parâmetro singleEvents é "True").
  • "updated": ordem pelo horário da última modificação (crescente).
pageToken string Token que especifica qual página de resultados deve ser retornada. Opcional.
privateExtendedProperty string Restrição de propriedades estendidas especificada como propriedadeName=value. Corresponde apenas a propriedades particulares. Esse parâmetro pode ser repetido várias vezes para retornar eventos que correspondam a todas as restrições fornecidas.
q string Termos de pesquisa de texto livre para encontrar eventos que correspondam a esses termos nos seguintes campos:
  • summary
  • description
  • location
  • displayName do convidado
  • email do convidado
  • displayName do organizador
  • email do organizador
  • workingLocationProperties.officeLocation.buildingId
  • workingLocationProperties.officeLocation.deskId
  • workingLocationProperties.officeLocation.label
  • workingLocationProperties.customLocation.label

Esses termos de pesquisa também correspondem palavras-chave predefinidas a todas as traduções de títulos de exibição do local de trabalho, "fora do escritório" e eventos "Horário de concentração". Por exemplo, a pesquisa por "Escritório" ou "Bureau" retorna eventos de local de trabalho do tipo officeLocation, enquanto a pesquisa por "Fora do escritório" ou "Abwesend" retorna eventos fora do escritório. Opcional.
sharedExtendedProperty string Restrição de propriedades estendidas especificada como propriedadeName=value. Corresponde apenas a propriedades compartilhadas. Esse parâmetro pode ser repetido várias vezes para retornar eventos que correspondam a todas as restrições fornecidas.
showDeleted boolean Indica se eventos excluídos (com status é igual a "cancelled") no resultado. Instâncias canceladas de eventos recorrentes (mas não o evento recorrente subjacente) ainda vão ser incluídas se showDeleted e singleEvents forem "False". Se showDeleted e singleEvents forem verdadeiros, apenas instâncias únicas de eventos excluídos, mas não os eventos recorrentes subjacentes, serão retornadas. Opcional. O valor padrão é falso.
showHiddenInvitations boolean Define se convites ocultos devem ser incluídos no resultado. Opcional. O valor padrão é falso.
singleEvents boolean Define se os eventos recorrentes serão expandidos em instâncias e retornarão apenas eventos únicos e instâncias de eventos recorrentes, mas não os eventos recorrentes subjacentes em si. Opcional. O valor padrão é falso.
syncToken string Token recebido do campo nextSyncToken retornado na última página de resultados da solicitação de lista anterior. Ela faz com que o resultado dessa solicitação de lista contenha apenas as entradas que foram alteradas desde então. Todos os eventos excluídos desde a solicitação de lista anterior sempre estarão no conjunto de resultados e não é permitido definir showDeleted como falso.
Há vários parâmetros de consulta que não podem ser especificados com nextSyncToken para garantir a consistência do estado do cliente.

São:
  • iCalUID
  • orderBy
  • privateExtendedProperty
  • q
  • sharedExtendedProperty
  • timeMin
  • timeMax
  • updatedMin
Todos os outros parâmetros de consulta precisam ser os mesmos da sincronização inicial para evitar comportamento indefinido. Se o syncToken expirar, o servidor responderá com um código de resposta 410 GONE, e o cliente limpará o armazenamento e fará uma sincronização completa sem syncToken.
Saiba mais sobre a sincronização incremental.
Opcional. O padrão é retornar todas as entradas.
timeMax datetime Limite superior (exclusivo) para o horário de início de um evento que será filtrado. Opcional. O padrão é não filtrar por horário de início. Precisa ser um carimbo de data/hora RFC3339 com deslocamento de fuso horário obrigatório, por exemplo, 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. Os milissegundos podem ser fornecidos, mas eles serão ignorados. Se timeMin estiver definido, timeMax precisará ser maior que timeMin.
timeMin datetime Limite inferior (exclusivo) para o horário de término de um evento que será filtrado. Opcional. O padrão é não filtrar por horário de término. Precisa ser um carimbo de data/hora RFC3339 com deslocamento de fuso horário obrigatório, por exemplo, 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. Os milissegundos podem ser fornecidos, mas eles serão ignorados. Se timeMax estiver definido, timeMin precisará ser menor que timeMax.
timeZone string Fuso horário usado na resposta. Opcional. O padrão é o fuso horário da agenda.
updatedMin datetime Limite inferior para o horário da última modificação de um evento (como um carimbo de data/hora RFC3339) para filtrar. Quando especificada, as entradas excluídas desde então serão sempre incluídas, independente de showDeleted. Opcional. O padrão é não filtrar pelo horário da última modificação.

Autorização

Esta solicitação permite a autorização com pelo menos um dos seguintes escopos:

Escopo
https://www.googleapis.com/auth/calendar.readonly
https://www.googleapis.com/auth/calendar
https://www.googleapis.com/auth/calendar.events.readonly
https://www.googleapis.com/auth/calendar.events

Para mais informações, consulte a página de autenticação e autorização.

Corpo da solicitação

Não forneça um corpo de solicitação com este método.

Resposta

Se for bem-sucedido, esse método retornará um corpo de resposta com esta estrutura:

{
  "kind": "calendar#events",
  "etag": etag,
  "summary": string,
  "description": string,
  "updated": datetime,
  "timeZone": string,
  "accessRole": string,
  "defaultReminders": [
    {
      "method": string,
      "minutes": integer
    }
  ],
  "nextPageToken": string,
  "nextSyncToken": string,
  "items": [
    events Resource
  ]
}
Nome da propriedade Valor Descrição Observações
kind string Tipo da coleção ("calendar#events").
etag etag ETag da coleção.
summary string Título da agenda. Somente leitura.
description string Descrição da agenda. Somente leitura.
updated datetime Hora da última modificação da agenda (como um carimbo de data/hora RFC3339). Somente leitura.
timeZone string O fuso horário da agenda. Somente leitura.
accessRole string A função de acesso do usuário a esta agenda. Somente leitura. Os valores possíveis são:
  • "none": o usuário não tem acesso.
  • "freeBusyReader": o usuário tem acesso de leitura às informações de disponibilidade.
  • "reader": o usuário tem acesso de leitura à agenda. Os eventos particulares vão aparecer para os usuários com acesso de leitor, mas os detalhes vão ficar ocultos.
  • "writer": o usuário tem acesso de leitura e gravação à agenda. Os eventos particulares aparecem para os usuários com acesso de escritor, e os detalhes dos eventos ficam visíveis.
  • "owner": o usuário tem a propriedade da agenda. Esse papel tem todas as permissões da função de gravador, com a capacidade adicional de ver e manipular as ACLs.
defaultReminders[] list Os lembretes padrão na agenda para o usuário autenticado. Esses lembretes são válidos para todos os eventos da agenda que não os modificam explicitamente (ou seja, não têm reminders.useDefault definido como "Verdadeiro").
defaultReminders[].method string O método usado pelo lembrete. Os valores possíveis são:
  • "email": os lembretes são enviados por e-mail.
  • "popup": os lembretes são enviados em um pop-up da interface.

Obrigatório ao adicionar um lembrete.

 gravável
defaultReminders[].minutes integer Número de minutos antes do início do evento em que o lembrete deve ser acionado. Os valores válidos estão entre 0 e 40320 (4 semanas em minutos).

Obrigatório ao adicionar um lembrete.

 gravável
nextPageToken string Token usado para acessar a próxima página deste resultado. Omitido se não houver mais resultados disponíveis. Nesse caso, nextSyncToken será fornecido.
items[] list Lista de eventos da agenda.
nextSyncToken string Token usado posteriormente para recuperar apenas as entradas que foram alteradas desde que esse resultado foi retornado. Omitido se mais resultados estiverem disponíveis. Nesse caso, nextPageToken será fornecido.

Exemplos

Observação: os exemplos de código disponíveis para esse método não representam todas as linguagens de programação compatíveis. Consulte a página de bibliotecas cliente para ver uma lista de linguagens compatíveis.

Java

Usa a biblioteca cliente de Java.

import com.google.api.services.calendar.Calendar;
import com.google.api.services.calendar.model.Event;
import com.google.api.services.calendar.model.Events;

// ...

// Initialize Calendar service with valid OAuth credentials
Calendar service = new Calendar.Builder(httpTransport, jsonFactory, credentials)
    .setApplicationName("applicationName").build();

// Iterate over the events in the specified calendar
String pageToken = null;
do {
  Events events = service.events().list('primary').setPageToken(pageToken).execute();
  List<Event> items = events.getItems();
  for (Event event : items) {
    System.out.println(event.getSummary());
  }
  pageToken = events.getNextPageToken();
} while (pageToken != null);

Python

Usa a biblioteca cliente de Python.

page_token = None
while True:
  events = service.events().list(calendarId='primary', pageToken=page_token).execute()
  for event in events['items']:
    print event['summary']
  page_token = events.get('nextPageToken')
  if not page_token:
    break

PHP

Usa a biblioteca cliente de PHP.

$events = $service->events->listEvents('primary');

while(true) {
  foreach ($events->getItems() as $event) {
    echo $event->getSummary();
  }
  $pageToken = $events->getNextPageToken();
  if ($pageToken) {
    $optParams = array('pageToken' => $pageToken);
    $events = $service->events->listEvents('primary', $optParams);
  } else {
    break;
  }
}

Ruby

Usa a biblioteca de cliente do Ruby.

page_token = nil
begin
  result = client.list_events('primary', page_token: page_token)
  result.items.each do |e|
    print e.summary + "\n"
  end
  if result.next_page_token != page_token
    page_token = result.next_page_token
  else
    page_token = nil
  end
end while !page_token.nil?

Confira!

Use o APIs Explorer abaixo para chamar esse método em dados ativos e ver a resposta.