Events: list

Renvoie les événements du calendrier spécifié. Essayer maintenant ou voir un exemple

Demande

Requête HTTP :

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

Paramètres

Nom du paramètre Valeur Description
Paramètres de chemin d'accès
calendarId string Identifiant de l'agenda. Pour récupérer les ID d'agenda, appelez la méthode calendarList.list. Si vous souhaitez accéder à l'agenda principal de l'utilisateur actuellement connecté, utilisez le mot clé "primary".
Paramètres de requête facultatifs
alwaysIncludeEmail boolean Obsolète et ignoré. Une valeur est toujours renvoyée dans le champ email pour l'organisateur, le créateur et les participants, même si aucune adresse e-mail réelle n'est disponible (c'est-à-dire qu'une valeur générée ne fonctionne pas).
eventTypes string Types d'événements à afficher. Facultatif. Les valeurs possibles sont les suivantes:
  • "default"
  • "focusTime"
  • "outOfOffice"
  • "workingLocation"
Ce paramètre peut être répété plusieurs fois pour renvoyer des événements de différents types. Voici les seules valeurs actuellement autorisées pour ce champ:
  • ["default", "focusTime", "outOfOffice"]
  • ["default", "focusTime", "outOfOffice", "workingLocation"]
  • ["workingLocation"]
La valeur par défaut est ["default", "focusTime", "outOfOffice"].
Des combinaisons supplémentaires de ces quatre types d'événements seront disponibles dans les prochaines versions.
iCalUID string Spécifie un ID d'événement au format iCalendar à fournir dans la réponse. Facultatif. Utilisez cette option si vous souhaitez rechercher un événement à l'aide de son ID iCalendar.
maxAttendees integer Nombre maximal de participants à inclure dans la réponse. Si le nombre de participants est supérieur au nombre spécifié, seul le participant est renvoyé. Facultatif.
maxResults integer Nombre maximal d'événements renvoyés sur une page de résultats. Le nombre d'événements sur la page obtenue peut être inférieur ou égal à cette valeur, même si d'autres événements correspondent à la requête. Un champ nextPageToken non vide peut être détecté dans la réponse pour identifier les pages incomplètes. Par défaut, la valeur est de 250 événements. La taille de la page ne peut jamais être supérieure à 2 500 événements. Facultatif.
orderBy string Ordre des événements renvoyés dans le résultat. Facultatif. La valeur par défaut est un ordre non spécifié et stable.

Les valeurs acceptées sont les suivantes :
  • "startTime": trie par date/heure de début (ordre croissant). Cette option n'est disponible que pour les requêtes sur des événements uniques (le paramètre singleEvents est défini sur "True").
  • "updated": tri par date de dernière modification (ordre croissant).
pageToken string Jeton spécifiant la page de résultats à afficher. Facultatif.
privateExtendedProperty string Contrainte de propriété étendue spécifiée en tant que propertyName=valeur. Prend en compte les propriétés privées uniquement. Ce paramètre peut être répété plusieurs fois pour renvoyer des événements qui correspondent à toutes les contraintes données.
q string Termes de recherche en texte libre permettant de trouver des événements correspondant à ces termes dans les champs suivants: summary, description, location, displayName du participant, email du participant. Facultatif.
sharedExtendedProperty string Contrainte de propriété étendue spécifiée en tant que propertyName=valeur. Prend en compte les propriétés partagées. Ce paramètre peut être répété plusieurs fois pour renvoyer des événements qui correspondent à toutes les contraintes données.
showDeleted boolean Permet d'inclure ou non les événements supprimés (avec status correspond à "cancelled") dans le résultat. Les instances d'événements périodiques annulés (mais pas l'événement récurrent sous-jacent) seront toujours incluses si showDeleted et singleEvents sont tous les deux faux. Si showDeleted et singleEvents sont tous les deux vrais, seules les instances uniques d'événements supprimés (mais pas les événements récurrents sous-jacents) sont renvoyées. Facultatif. La valeur par défaut est "False" (faux).
showHiddenInvitations boolean Indique si les invitations masquées sont incluses dans le résultat. Facultatif. La valeur par défaut est "False" (faux).
singleEvents boolean Permet de développer les événements périodiques en instances et de ne renvoyer que des événements ponctuels et ponctuels, mais pas les événements récurrents sous-jacents eux-mêmes. Facultatif. La valeur par défaut est "False" (faux).
syncToken string Jeton obtenu à partir du champ nextSyncToken affiché sur la dernière page des résultats de la requête de liste précédente. Ainsi, le résultat de cette requête de liste ne contient que des entrées qui ont changé depuis. Tous les événements supprimés depuis la demande de liste précédente seront toujours inclus dans l'ensemble de résultats et il n'est pas autorisé de définir showDeleted sur "False".
Vous ne pouvez pas spécifier plusieurs paramètres de requête avec nextSyncToken pour assurer la cohérence de l'état du client.

Les voici:
  • iCalUID
  • orderBy
  • privateExtendedProperty
  • q
  • sharedExtendedProperty
  • timeMin
  • timeMax
  • updatedMin
Tous les autres paramètres de requête doivent être identiques à ceux de la synchronisation initiale pour éviter un comportement non défini. Si la date d'expiration de syncToken est atteinte, le serveur renvoie un code de réponse 410 GONE, et le client doit libérer de l'espace de stockage et effectuer une synchronisation complète sans syncToken.
En savoir plus sur la synchronisation incrémentielle
Facultatif. Par défaut, toutes les entrées sont renvoyées.
timeMax datetime Limite supérieure (exclue) de l'heure de début d'un événement. Facultatif. Par défaut, le filtrage par heure de début n'est pas effectué. Doit être un horodatage RFC3339 avec décalage horaire obligatoire, par exemple 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. Des millisecondes peuvent être indiquées, mais elles sont ignorées. Si timeMin est défini, timeMax doit être supérieur à timeMin.
timeMin datetime Limite inférieure (exclusivité) pour le filtrage de l'heure de fin d'un événement. Facultatif. Le filtrage par heure de fin n'est pas activé par défaut. Doit être un horodatage RFC3339 avec décalage horaire obligatoire, par exemple 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. Des millisecondes peuvent être indiquées, mais elles sont ignorées. Si timeMax est défini, timeMin doit être inférieur à timeMax.
timeZone string Fuseau horaire utilisé dans la réponse. Facultatif. Le fuseau horaire par défaut est celui de l'agenda.
updatedMin datetime Limite inférieure de la dernière date de modification d'un événement (sous la forme d'un horodatage RFC3339) à utiliser pour le filtrage. Si spécifié, les entrées supprimées depuis cette date sont toujours incluses, quelle que soit la showDeleted. Facultatif. Par défaut, le filtre n'est pas basé sur l'heure de la dernière modification.

Autorisation

Cette requête autorise l'autorisation avec au moins l'un des champs d'application suivants:

Définition du champ d'application
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

Pour en savoir plus, consultez la page sur l'authentification et les autorisations.

Corps de la requête

Ne spécifiez pas de corps de requête pour cette méthode.

Réponse

Si la requête aboutit, cette méthode renvoie un corps de réponse présentant la structure suivante :

{
  "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
  ]
}
Nom de propriété Valeur Description Notes
kind string Type de la collection ("calendar#events").
etag etag ETag de la collection.
summary string Titre de l'agenda. Lecture seule.
description string Description de l'agenda. Lecture seule.
updated datetime Heure de la dernière modification de l'agenda (au format RFC3339). Lecture seule.
timeZone string Fuseau horaire de l'agenda. Lecture seule.
accessRole string Rôle d'accès de l'utilisateur pour cet agenda. Lecture seule. Les valeurs possibles sont les suivantes:
  • "none" : l'utilisateur n'a pas accès.
  • "freeBusyReader" : l'utilisateur dispose d'un accès en lecture aux informations de disponibilité.
  • "reader" : l'utilisateur a accès en lecture à l'agenda. Les événements privés sont présentés aux utilisateurs ayant un accès en lecture, mais les détails des événements sont masqués.
  • "writer" : l'utilisateur a accès en lecture et en écriture à l'agenda. Les utilisateurs privés disposant d'un accès en écriture pourront voir les événements privés, ainsi que les détails les concernant.
  • "owner" : l'utilisateur est propriétaire de l'agenda. Ce rôle dispose de toutes les autorisations du rôle "Rédacteur", ainsi que de la possibilité d'afficher et de manipuler les LCA.
defaultReminders[] list Rappels par défaut dans l'agenda de l'utilisateur authentifié. Ces rappels s'appliquent à tous les événements de cet agenda qui ne les remplacent pas explicitement (c'est-à-dire, si reminders.useDefault n'est pas défini sur "True").
defaultReminders[].method string Méthode utilisée par ce rappel. Les valeurs possibles sont les suivantes:
  • "email" : les rappels sont envoyés par e-mail.
  • "popup" : les rappels sont envoyés via un pop-up dans l'interface utilisateur.

Obligatoire lors de l'ajout d'un rappel.

 accessible en écriture
defaultReminders[].minutes integer Nombre de minutes avant le début de l'événement au cours duquel le rappel doit se déclencher. Les valeurs valides sont comprises entre 0 et 40 320 (quatre semaines en minutes).

Obligatoire lors de l'ajout d'un rappel.

 accessible en écriture
nextPageToken string Jeton utilisé pour accéder à la page suivante de ce résultat. Omis si aucun autre résultat n'est disponible, auquel cas nextSyncToken est fourni.
items[] list Liste des événements du calendrier.
nextSyncToken string Jeton utilisé ultérieurement pour ne récupérer que les entrées modifiées depuis l'affichage de ce résultat. Omis si d'autres résultats sont disponibles, auquel cas nextPageToken.

Exemples

Remarque : Les langages de programmation compatibles ne figurent pas tous dans les exemples de code présentés pour cette méthode (consultez la page Bibliothèques clientes pour obtenir la liste des langages compatibles).

Java

Utilise la bibliothèque cliente 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

Utilise la bibliothèque cliente 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

Utilise la bibliothèque 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;
  }
}

Ruby

Utilise la bibliothèque 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?

Essayer

Utilisez l'explorateur d'API ci-dessous pour appeler cette méthode sur des données en direct, puis observez la réponse.