Events: list

Renvoie les événements de l'agenda spécifié. Essayez dès maintenant ou consultez un exemple.

Requête

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 bouton "primary" mot clé.
Paramètres de requête facultatifs
alwaysIncludeEmail boolean Obsolète et ignoré.
eventTypes string Types d'événements à renvoyer. Facultatif. Ce paramètre peut être répété plusieurs fois pour renvoyer des événements de différents types. Si cette règle n'est pas configurée, elle renvoie tous les types d'événements.

Les valeurs possibles sont les suivantes: <ph type="x-smartling-placeholder">
    </ph>
  • "default" : événements réguliers.
  • "focusTime" : événements "Moment de concentration"
  • "fromGmail" : événements ajoutés à partir de Gmail.
  • "outOfOffice" : absence du bureau.
  • "workingLocation" : événements liés à votre lieu de travail.
iCalUID string Spécifie un ID d'événement au format iCalendar à fournir dans la réponse. Facultatif. Utilisez cette option pour rechercher un événement à l'aide de son ID iCalendar.
maxAttendees integer Nombre maximal de participants à inclure dans la réponse. S'il y a plus de participants que le 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 qui s'affiche peut être inférieur à cette valeur, voire aucun, même s'il existe davantage d'événements correspondant à la requête. Les pages incomplètes peuvent être détectées par un champ nextPageToken non vide dans la réponse. Par défaut, la valeur est fixée à 250 événements. La taille de la page ne peut jamais dépasser 2 500 événements. Facultatif.
orderBy string Ordre des événements affichés dans le résultat. Facultatif. La valeur par défaut est un ordre stable non spécifié.

Les valeurs possibles sont les suivantes: <ph type="x-smartling-placeholder">
    </ph>
  • "startTime" : trie par date/heure de début (dans l'ordre croissant). Cette option n'est disponible que lorsque vous interrogez des événements uniques (par exemple, le paramètre singleEvents est défini sur "True").
  • "updated" : trie par heure de dernière modification (dans l'ordre croissant).
pageToken string Jeton spécifiant la page de résultats à renvoyer. Facultatif.
privateExtendedProperty string Contrainte des propriétés étendues spécifiée en tant que propriétéName=valeur. Correspond uniquement aux propriétés privées. Ce paramètre peut être répété plusieurs fois pour renvoyer des événements correspondant à 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
  • displayName de l'organisateur
  • email de l'organisateur
  • workingLocationProperties.officeLocation.buildingId
  • workingLocationProperties.officeLocation.deskId
  • workingLocationProperties.officeLocation.label
  • workingLocationProperties.customLocation.label

Ces termes de recherche mettent également en correspondance des mots clés prédéfinis avec toutes les traductions du titre à afficher concernant le lieu de travail, les absences du bureau et les moments de concentration. Par exemple, si vous recherchez "bureau", ou "Bureau" renvoie les événements de lieu de travail de type officeLocation, et la recherche "Absent du bureau" ou "Abwesend" renvoie les événements d'absence du bureau. Facultatif.
sharedExtendedProperty string Contrainte des propriétés étendues spécifiée en tant que propriétéName=valeur. Correspond uniquement aux propriétés partagées. Ce paramètre peut être répété plusieurs fois pour renvoyer des événements correspondant à toutes les contraintes données.
showDeleted boolean Permet d'inclure ou non les événements supprimés (où status est égal à "cancelled") dans le résultat. Les instances annulées d'événements périodiques (mais pas l'événement périodique sous-jacent) seront toujours incluses si les valeurs showDeleted et singleEvents sont toutes les deux définies sur "False". Si les valeurs showDeleted et singleEvents sont toutes deux définies sur "True", seules des instances uniques des événements supprimés (mais pas des événements périodiques sous-jacents) sont renvoyées. Facultatif. La valeur par défaut est "False" (faux).
showHiddenInvitations boolean Permet d'inclure ou non les invitations masquées dans le résultat. Facultatif. La valeur par défaut est "False" (faux).
singleEvents boolean Permet de transformer les événements périodiques en instances et de ne renvoyer que des événements ponctuels ou des instances d'événements périodiques, 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 renvoyé sur la dernière page de résultats de la requête de liste précédente. Le résultat de cette requête de liste ne contient alors que les entrées qui ont été modifiées depuis. Tous les événements supprimés depuis la requête de liste précédente figureront toujours dans l'ensemble de résultats. Vous n'êtes pas autorisé à définir showDeleted sur "False".
Plusieurs paramètres de requête ne peuvent pas être spécifiés avec nextSyncToken pour assurer la cohérence de l'état du client.

Il s'agit des éléments suivants:
  • 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 tout comportement non défini. Si l'syncToken expire, le serveur renvoie un code de réponse 410 GONE, et le client doit effacer son 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 (exclusive) pour l'heure de début d'un événement à utiliser comme critère de filtrage. Facultatif. Par défaut, les filtres ne sont pas filtrés par heure de début. Doit être un code temporel RFC3339 avec décalage de fuseau horaire obligatoire, par exemple, 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. Les 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) pour l'heure de fin d'un événement à utiliser comme critère de filtrage. Facultatif. Par défaut, les filtres ne sont pas filtrés par heure de fin. Doit être un code temporel RFC3339 avec décalage de fuseau horaire obligatoire, par exemple, 2011-06-03T10:00:00-07:00, 2011-06-03T10:00:00Z. Les 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. La valeur par défaut est le fuseau horaire de l'agenda.
updatedMin datetime Limite inférieure de l'heure de la dernière modification d'un événement (en tant qu'horodatage RFC3339) à utiliser comme critère de filtrage. Si cette valeur est spécifiée, les entrées supprimées depuis cette date sont toujours incluses, indépendamment de showDeleted. Facultatif. Par défaut, les filtres ne sont pas filtrés en fonction de l'heure de la dernière modification.

Autorisation

Cette requête autorise l'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. En lecture seule.
description string Description de l'agenda. En lecture seule.
updated datetime Heure de la dernière modification du calendrier (sous forme d'horodatage RFC3339). En lecture seule.
timeZone string Fuseau horaire de l'agenda. En lecture seule.
accessRole string Rôle d'accès de l'utilisateur pour cet agenda. En lecture seule. Les valeurs possibles sont:
  • "none" - L'utilisateur n'a aucun accès.
  • "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 événements privés seront visibles par les utilisateurs disposant d'un accès en lecture, mais les détails des événements 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, et les détails des événements seront visibles.
  • "owner" - L'utilisateur est propriétaire de l'agenda. Il dispose de toutes les autorisations du rôle de rédacteur, ainsi que de la possibilité supplémentaire de voir et de manipuler les LCA.
defaultReminders[] list Rappels par défaut du calendrier pour l'utilisateur authentifié. Ces rappels s'appliquent à tous les événements de cet agenda qui ne les remplacent pas explicitement (c'est-à-dire que reminders.useDefault n'est pas défini sur "True").
defaultReminders[].method string Méthode utilisée pour ce rappel. Les valeurs possibles sont:
  • "email" - Les rappels sont envoyés par e-mail.
  • "popup" - Les rappels sont envoyés via un pop-up d'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 pendant lesquelles le rappel doit se déclencher. Les valeurs valides sont comprises entre 0 et 40 320 (4 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é ultérieurement pour récupérer uniquement les entrées qui ont été modifiées depuis que ce résultat a été renvoyé. Ignoré 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

Elle 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

Elle 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

Elle 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

Elle 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.