Events: list

Renvoie les événements de l'agenda 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ée. 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 et qui ne fonctionne pas sera fournie).
eventTypes string Types d'événements à afficher. Facultatif. Les valeurs possibles sont les suivantes:
  • "default"
  • "focusTime"
  • "outOfOffice"
Ce paramètre peut être répété plusieurs fois pour renvoyer des événements de types différents. Actuellement, il s'agit de la seule valeur autorisée pour ce champ:
  • ["default", "focusTime", "outOfOffice"]
Il s'agira de la valeur par défaut.

Si vous êtes inscrit au programme Preview lieu de travail pour les développeurs, en plus de la valeur par défaut ci-dessus, vous pouvez également définir le type d'événement "workingLocation":
  • ["default", "focusTime", "outOfOffice", "workingLocation"]
  • ["workingLocation"]
D'autres combinaisons 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 dans la page obtenue peut être inférieur ou inférieur à cette valeur, même si d'autres événements correspondent à la requête. Les pages incomplètes peuvent être détectées par un champ nextPageToken vide dans la réponse. La valeur par défaut est de 250 événements. La taille de la page ne doit jamais dépasser 2 500 événements. Facultatif.
orderBy string Ordre de priorité des événements renvoyés dans le résultat. Facultatif. La valeur par défaut est une commande non spécifiée et stable.

Les valeurs autorisées sont les suivantes :
  • "startTime": tri par date/heure de début (ordre croissant). Cette option n'est disponible que pour les requêtes portant 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ésultat à afficher. Facultatif.
privateExtendedProperty string Contrainte étendue de propriétés spécifiée en tant que propertyName=value. Renvoie uniquement les propriétés privées. 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 pour trouver des événements correspondant à ces termes dans les champs suivants: summary, description, location, displayName du participant, email du participant. Facultatif.
sharedExtendedProperty string Contrainte étendue de propriétés spécifiée en tant que propertyName=value. Correspond uniquement aux 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 Indique si les événements supprimés (avec status est égal à "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 deux "True", seules des instances 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 Indique s'il faut développer les événements périodiques en instances et ne renvoyer que des événements ponctuels et des événements périodiques uniques, mais pas les événements périodiques 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 de résultats de la requête "list" 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 requête de liste précédente figureront toujours 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.

Il s'agit de:
  • iCalUID
  • orderBy
  • privateExtendedProperty
  • q
  • sharedExtendedProperty
  • timeMin
  • timeMax
  • updatedMin
. Si syncToken arrive à expiration, le serveur envoie une réponse 410 GONE. 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 pour le filtrage. Facultatif. Par défaut, le filtrage par heure de début n'est pas activé. Il doit s'agir d'un horodatage RFC3339 avec un 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 (exclusive) de fin de l'événement. Facultatif. Par défaut, le filtre n'est pas basé sur l'heure de fin. Il doit s'agir d'un horodatage RFC3339 avec un 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. Par défaut, il s'agit du fuseau horaire de l'agenda.
updatedMin datetime Limite inférieure de la dernière date de modification d'un événement (en tant qu'horodatage RFC3339) à utiliser pour le filtrage. Si spécifié, les entrées supprimées depuis cette date seront toujours incluses, quelle que soit la valeur showDeleted. Facultatif. Par défaut, le filtre n'est pas basé sur l'heure de la dernière modification.

Autorisation

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

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 Authentification et autorisation.

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 Remarques
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 à cet agenda. Lecture seule. Les valeurs possibles sont les suivantes:
  • "none" : l'utilisateur n'a plus accès au fichier.
  • "freeBusyReader" : l'utilisateur dispose d'un accès en lecture aux informations de disponibilité.
  • "reader" : l'utilisateur dispose d'un accès en lecture à l'agenda. Les utilisateurs ayant accès au lecteur verront les événements privés, mais les détails de l'événement seront masqués.
  • "writer" : l'utilisateur dispose d'un accès en lecture et en écriture à l'agenda. Les utilisateurs ayant un accès en écriture pourront voir les événements privés, ainsi que les détails de l'événement.
  • "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 droits supplémentaires pour afficher et 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 dont la valeur "reminders.useDefault" n'est pas définie 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 une fenêtre pop-up.

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 où 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 de l'agenda.
nextSyncToken string Jeton utilisé par la suite pour récupérer uniquement les entrées qui ont été modifiées depuis l'affichage de ce résultat. Omis si d'autres résultats sont disponibles, auquel cas nextPageToken est fourni.

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.