Events: list

Devuelve eventos en el 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 obtener los IDs de calendario, llama al método calendarList.list. Si quieres acceder al calendario principal del usuario que accedió, usa la palabra clave "primary".
Parámetros de consulta opcionales
alwaysIncludeEmail boolean Se ignoró y dejó de estar disponible.
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:
  • "default": Eventos normales.
  • "focusTime": Eventos de tiempo dedicado.
  • "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. Usa esta opción si quieres buscar un evento por su ID de iCalendar.
maxAttendees integer Indica la cantidad máxima de asistentes que se deben incluir en la respuesta. Si la cantidad de asistentes supera la cantidad especificada, solo se devolverá el participante. Opcional.
maxResults integer 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 ninguno, incluso si hay más eventos que coincidan con la consulta. Un campo nextPageToken que no esté vacío en la respuesta puede detectar páginas incompletas. De forma predeterminada, el valor es de 250 eventos. El tamaño de la página nunca puede superar los 2,500 eventos. Opcional.
orderBy string Es el orden de los eventos que se muestran en el resultado. Opcional. El orden predeterminado es un orden estable y no especificado.

Los valores aceptables son los siguientes:
  • "startTime": Ordena por fecha y hora de inicio (orden ascendente). Solo está disponible cuando se consultan eventos individuales (es decir, el parámetro singleEvents es verdadero).
  • "updated": Ordenado según la hora de la última modificación (orden ascendente).
pageToken string Token que especifica qué página de resultados se mostrará. Opcional.
privateExtendedProperty string Restricción de propiedades extendidas especificada como propertyName=value. Coincide solo 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 hacen coincidir las palabras clave predefinidas con todas las traducciones de títulos en pantalla de eventos relacionados con la ubicación de trabajo, fuera de la oficina y tiempo dedicado. Por ejemplo, si buscas "Office" o "Bureau", se mostrarán los eventos de ubicación de trabajo del tipo officeLocation, mientras que si buscas "Fuera de la oficina" o "Abwesend", verás eventos fuera de la oficina. Opcional.

sharedExtendedProperty string Restricción de propiedades extendidas especificada como propertyName=value. Coincide solo con las propiedades compartidas. Este parámetro puede repetirse varias veces para mostrar eventos que coincidan con todas las restricciones determinadas.
showDeleted boolean Indica si se deben incluir los eventos eliminados (en el que status es igual a "cancelled") en el resultado. Las instancias canceladas de eventos recurrentes (pero no el evento recurrente subyacente) se seguirán incluyendo si showDeleted y singleEvents se establecen como falsas. Si las políticas showDeleted y singleEvents son verdaderas, solo se muestran instancias individuales 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 mostrar solo eventos únicos y instancias de eventos recurrentes, pero no los eventos recurrentes subyacentes en sí. Opcional. El valor predeterminado es False.
syncToken string 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 solo contenga 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 puede establecer showDeleted como falso.
Existen varios parámetros de consulta que no se pueden especificar junto con nextSyncToken para garantizar la coherencia del estado del cliente.

Estas son las siguientes:
  • iCalUID
  • orderBy
  • privateExtendedProperty
  • q
  • sharedExtendedProperty
  • timeMin
  • timeMax
  • updatedMin
Todos los demás parámetros de consulta deben ser los mismos que para la sincronización inicial a fin de evitar un comportamiento indefinido. Si syncToken vence, el servidor responderá con un código de respuesta 410 GONE y el cliente debería liberar su almacenamiento y realizar una sincronización completa sin ninguna syncToken.
Obtén más información sobre la sincronización incremental.
Opcional. El valor predeterminado es mostrar todas las entradas.
timeMax datetime Límite superior (exclusivo) de la hora de inicio de un evento para filtrar. Opcional. De forma predeterminada, no se filtra por hora de inicio. Debe ser una marca de tiempo RFC3339 con desplazamiento obligatorio de la zona horaria, por ejemplo, 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. Se pueden proporcionar milisegundos, pero se ignoran. Si se configura timeMin, timeMax debe ser mayor que timeMin.
timeMin datetime Límite inferior (exclusivo) de la hora de finalización de un evento para filtrar. Opcional. De forma predeterminada, no se filtra por hora de finalización. Debe ser una marca de tiempo RFC3339 con desplazamiento obligatorio de la zona horaria, por ejemplo, 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. Se pueden proporcionar milisegundos, pero se ignoran. Si se configura 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 especifica, las entradas que se borran desde este momento siempre se incluirán, independientemente de showDeleted. Opcional. La configuración predeterminada no es filtrar por la hora de la última modificación.

Autorización

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

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 de autenticación y autorización.

Cuerpo de la solicitud

No proporciones un cuerpo de 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 Es la 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 La zona horaria del calendario. Solo lectura.
accessRole string Es el rol de acceso del usuario para este calendario. Solo lectura. Los valores posibles son:
  • "none": El usuario no tiene acceso.
  • "freeBusyReader": El usuario tiene acceso de lectura a la información de disponible/ocupado.
  • "reader": El usuario tiene acceso de lectura al calendario. Los eventos privados se mostrarán a los usuarios con acceso de lectura, pero los detalles de los eventos estarán ocultos.
  • writer”: El usuario tiene acceso de lectura y escritura al calendario. Los eventos privados se mostrarán a los usuarios con acceso de escritor y se podrán ver los detalles del evento.
  • "owner": El usuario es propietario del calendario. Este rol cuenta con todos los permisos del rol de escritor, además de la capacidad adicional de ver y manipular las LCA.
defaultReminders[] list Los recordatorios predeterminados en el calendario para el 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 establecen reminders.useDefault como verdadero).
defaultReminders[].method string Es el método que usa este recordatorio. Los valores posibles son:
  • "email": Los recordatorios se envían por correo electrónico.
  • "popup": Los recordatorios se envían a través de una ventana emergente de IU.

Obligatorio al agregar un recordatorio.

admite escritura
defaultReminders[].minutes integer 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 40,320 (4 semanas en minutos).

Obligatorio al agregar un recordatorio.

admite escritura
nextPageToken string El token se usa para acceder a la página siguiente de este resultado. Se omite si no hay más resultados disponibles. En ese caso, se proporciona nextSyncToken.
items[] list Es la lista de eventos del calendario.
nextSyncToken string Es el 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 ese 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

Utiliza la biblioteca cliente 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;
  }
}

Rita

Utiliza la biblioteca cliente 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 con los datos en tiempo real y ver la respuesta.