Events: list

Muestra los eventos del calendario especificado. Pruébalo ahora y ve un ejemplo.

Solicitud

Solicitud HTTP

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

Parámetros

Nombre del parámetro Valor Descripción
Parámetros de ruta de acceso
calendarId string Es el identificador de calendario. Para recuperar los IDs de calendario, llama al método calendarList.list. Si deseas acceder al calendario principal del usuario que accedió actualmente, usa la palabra clave "primary".
Parámetros de consulta opcionales
alwaysIncludeEmail boolean Dejó de estar disponible y se ignora.
eventTypes string Tipos de eventos que se mostrarán Opcional. Este parámetro se puede repetir varias veces para mostrar eventos de diferentes tipos. Si no se establece, se muestran todos los tipos de eventos.

Los valores aceptables son los siguientes:
  • "birthday": Eventos especiales de todo el día con una recurrencia anual.
  • "default": Eventos normales.
  • "focusTime": Eventos de tiempo dedicado.
  • "fromGmail": Eventos de Gmail.
  • "outOfOffice": Eventos fuera de la oficina.
  • "workingLocation": Eventos de ubicación de trabajo.
iCalUID string Especifica un ID de evento en el formato iCalendar que se proporcionará en la respuesta. Opcional. Úsalo si quieres buscar un evento por su ID de iCalendar.
maxAttendees integer Es la cantidad máxima de asistentes que se deben incluir en la respuesta. Si hay más de la cantidad especificada de asistentes, solo se muestra el participante. Opcional.
maxResults integer Es la cantidad máxima de eventos que se muestran en una página de resultados. La cantidad de eventos en la página resultante puede ser menor que este valor o no tener ninguno, incluso si hay más eventos que coinciden con la búsqueda. Las páginas incompletas se pueden detectar mediante un campo nextPageToken no vacío en la respuesta. De forma predeterminada, el valor es 250 eventos. El tamaño de la página nunca puede ser superior a 2,500 eventos. Opcional.
orderBy string Es el orden de los eventos que se muestran en el resultado. Opcional. El valor predeterminado es un orden estable no especificado.

Los valores aceptables son los siguientes:
  • "startTime": Ordena por la fecha y hora de inicio (ascendente). Solo está disponible cuando se consultan eventos únicos (es decir, el parámetro singleEvents es verdadero).
  • "updated": Ordena por hora de la última modificación (ascendente).
pageToken string Token que especifica qué página de resultados se debe mostrar. Opcional.
privateExtendedProperty string Restricción de propiedades extendidas especificada como propertyName=value. Solo coincide con propiedades privadas. Este parámetro puede repetirse varias veces para mostrar eventos que coincidan con todas las restricciones determinadas.
q string Términos de búsqueda de texto libre para encontrar eventos que coincidan con estos términos en los siguientes campos:
  • summary
  • description
  • location
  • displayName del asistente
  • email del asistente
  • displayName del organizador
  • email del organizador
  • workingLocationProperties.officeLocation.buildingId
  • workingLocationProperties.officeLocation.deskId
  • workingLocationProperties.officeLocation.label
  • workingLocationProperties.customLocation.label

Estos términos de búsqueda también coinciden con palabras clave predefinidas en todas las traducciones de títulos visibles de eventos de ubicación de trabajo, ausencia del lugar de trabajo y tiempo dedicado. Por ejemplo, si buscas "Oficina" o "Bureau", se mostrarán eventos de ubicación de trabajo del tipo officeLocation, mientras que si buscas "Ausente" o "Abwesend", se mostrarán eventos de ausencia. Opcional.
sharedExtendedProperty string Se especificó una restricción de propiedades extendidas como propertyName=value. Solo coincide con las propiedades compartidas. Este parámetro se puede repetir varias veces para mostrar eventos que coincidan con todas las restricciones determinadas.
showDeleted boolean Indica si se deben incluir eventos borrados (con status es igual a "cancelled") en el resultado. Se seguirán incluyendo las instancias canceladas de eventos recurrentes (pero no el evento recurrente subyacente) si showDeleted y singleEvents son "false". Si los valores de showDeleted y singleEvents son verdaderos, solo se muestran instancias únicas de eventos borrados (pero no los eventos recurrentes subyacentes). Opcional. El valor predeterminado es False.
showHiddenInvitations boolean Indica si se deben incluir invitaciones ocultas en el resultado. Opcional. El valor predeterminado es False.
singleEvents boolean Indica si se deben expandir los eventos recurrentes en instancias y solo mostrar eventos únicos e instancias de eventos recurrentes, pero no los eventos recurrentes subyacentes. Opcional. El valor predeterminado es False.
syncToken string Es el token obtenido del campo nextSyncToken que se muestra en la última página de resultados de la solicitud de lista anterior. Hace que el resultado de esta solicitud de lista contenga solo las entradas que cambiaron desde entonces. Todos los eventos borrados desde la solicitud de lista anterior siempre estarán en el conjunto de resultados y no se permite establecer showDeleted como falsa.
Existen varios parámetros de consulta que no se pueden especificar junto con nextSyncToken para garantizar la coherencia del estado del cliente.

Estos son:
  • iCalUID
  • orderBy
  • privateExtendedProperty
  • q
  • sharedExtendedProperty
  • timeMin
  • timeMax
  • updatedMin
Para evitar comportamientos indefinidos, todos los demás parámetros de consulta deben ser los mismos que los de la sincronización inicial. Si vence el syncToken, el servidor responderá con un código de respuesta 410 GONE y el cliente deberá borrar su almacenamiento y realizar una sincronización completa sin ningún syncToken.
Obtén más información sobre la sincronización incremental.
Opcional. La opción predeterminada es mostrar todas las entradas.
timeMax datetime Límite superior (exclusivo) para filtrar por la hora de inicio de un evento. Opcional. La configuración predeterminada es no filtrar por hora de inicio. Debe ser una marca de tiempo RFC3339 con un desplazamiento de zona horaria obligatorio, por ejemplo, 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. Se pueden proporcionar milisegundos, pero se ignoran. Si se establece timeMin, timeMax debe ser mayor que timeMin.
timeMin datetime Límite inferior (no incluido) para filtrar por la hora de finalización de un evento. Opcional. La configuración predeterminada no es filtrar por hora de finalización. Debe ser una marca de tiempo RFC3339 con un desplazamiento de zona horaria obligatorio, por ejemplo, 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. Se pueden proporcionar milisegundos, pero se ignoran. Si se establece timeMax, timeMin debe ser menor que timeMax.
timeZone string Es la zona horaria que se usa en la respuesta. Opcional. El valor predeterminado es la zona horaria del calendario.
updatedMin datetime Límite inferior para la hora de la última modificación de un evento (como una marca de tiempo RFC3339) para filtrar. Cuando se especifique, las entradas borradas desde ese momento siempre se incluirán, independientemente de showDeleted. Opcional. La configuración predeterminada no es filtrar por hora de última modificación.

Autorización

Esta solicitud permite la autorización con al menos uno de los siguientes permisos:

Alcance
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 obtener más información, consulta la página autenticación y autorización.

Cuerpo de la solicitud

No proporciones un cuerpo de la solicitud con este método.

Respuesta

Si se aplica correctamente, este método muestra un cuerpo de respuesta con la siguiente estructura:

{
  "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
  ]
}
Nombre de la propiedad Valor Descripción Notas
kind string Es el tipo de colección ("calendar#events").
etag etag ETag de la colección.
summary string Es el título del calendario. Solo lectura.
description string Descripción del calendario. Solo lectura.
updated datetime Es la hora de la última modificación del calendario (como una marca de tiempo RFC3339). Solo lectura.
timeZone string Es la zona horaria del calendario. Solo lectura.
accessRole string El rol de acceso del usuario en este calendario. Solo lectura. Los valores posibles son los siguientes:
  • "none": El usuario no tiene acceso.
  • "freeBusyReader": El usuario tiene acceso de lectura a la información de disponibilidad.
  • "reader": El usuario tiene acceso de lectura al calendario. Los eventos privados aparecerán para los usuarios con acceso de lector, pero se ocultarán los detalles.
  • "writer": El usuario tiene acceso de lectura y escritura al calendario. Los eventos privados aparecerán para los usuarios con acceso de escritor, y se podrán ver los detalles de los eventos.
  • "owner": El usuario es propietario del calendario. Este rol tiene todos los permisos del rol de escritor con la capacidad adicional de ver y manipular las ACL.
defaultReminders[] list Los recordatorios predeterminados en el calendario del usuario autenticado. Estos recordatorios se aplican a todos los eventos de este calendario que no los anulan de forma explícita (es decir, que no tienen reminders.useDefault establecido como verdadero).
defaultReminders[].method string Es el método que usa este recordatorio. Los valores posibles son los siguientes:
  • "email": Los recordatorios se envían por correo electrónico.
  • "popup": Los recordatorios se envían a través de una ventana emergente de la IU.

Obligatorio cuando se agrega un recordatorio.

 admite escritura
defaultReminders[].minutes integer Es la cantidad de minutos antes del inicio del evento en los que se debe activar el recordatorio. Los valores válidos están entre 0 y 40320 (4 semanas en minutos).

Obligatorio cuando se agrega un recordatorio.

 admite escritura
nextPageToken string Es el token que se usa para acceder a la siguiente página de este resultado. Se omite si no hay más resultados disponibles, en cuyo caso se proporciona nextSyncToken.
items[] list Es la lista de eventos del calendario.
nextSyncToken string Es un token que se usa más adelante para recuperar solo las entradas que cambiaron desde que se mostró este resultado. Se omite si hay más resultados disponibles, en cuyo caso se proporciona nextPageToken.

Ejemplos

Nota: Los ejemplos de código disponibles para este método no representan todos los lenguajes de programación admitidos (consulta la página de bibliotecas cliente para consultar una lista de lenguajes admitidos).

Java

Usa la 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 la 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 la 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 la biblioteca cliente de 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?

Pruébalo

Usa el Explorador de APIs que aparece a continuación para llamar a este método en datos en vivo y ver la respuesta.