Envoyer des requêtes dans l'API Google Drive Activity

Ce guide explique comment envoyer des requêtes dans l'API Google Drive Activity à l'aide de la méthode activity.query.

Clé de requête

Il existe deux façons de demander une activité: par élément Google Drive ou pour tout élément sous une hiérarchie de dossiers.

  • itemName: le format de cette clé est "items/ITEM_ID". Il s'agit généralement d'un fichier stocké dans Drive. Si vous spécifiez un dossier pour cette clé, l'activité du dossier s'affiche, par exemple sa date de création ou de nom.

  • ancestorName: le format de cette clé est "items/ITEM_ID" et la réponse inclut l'activité sur tous les éléments de la sous-arborescence située sous ce dossier.

Si aucune clé n'est définie, le ancestorName est utilisé par défaut dans "items/root" et affiche l'activité de tous les éléments de votre Drive.

Pagination

Le champ pageSize vous permet de demander un nombre approximatif d'activités à renvoyer dans chaque réponse. Le nombre réel d'activités renvoyées varie. Votre application doit donc gérer des quantités arbitraires dans la réponse.

La taille des pages est limitée. Si votre application nécessite de nombreuses activités, effectuez plusieurs requêtes à l'aide de la pagination au lieu de définir une valeur élevée pour pageSize. Plus précisément, s'il peut y avoir plus d'activité à récupérer que ce qui est inclus dans la réponse, la réponse contiendra également un nextPageToken. Pour récupérer plus de résultats, répétez la même requête, mais ajoutez un champ pageToken avec la valeur nextPageToken de la réponse précédente.

Regroupement

Les objets Action sont souvent regroupés et renvoyés dans une seule ressource DriveActivity. Certains regroupements Action se produisent spontanément, par exemple le déplacement d'un élément dans un dossier partagé déclenche une modification d'autorisation.

Vous pouvez également spécifier un ConsolidationStrategy (parfois appelé agrégation ou traitement par lot) dans la requête. Cela permet d'autres regroupements d'objets Action associés, par exemple plusieurs acteurs modifiant un élément, ou un Actor déplaçant plusieurs fichiers dans un nouveau dossier Drive.

Bien qu'une Action individuelle ait une Actor et une Target, une fois le regroupement effectué, le DriveActivity résultant peut avoir plusieurs acteurs et plusieurs cibles. Cependant, même après le regroupement, il existe toujours une action "principale" qui est soit représentative, soit la plus importante de toutes les actions dans la ressource DriveActivity, en fonction de la stratégie de consolidation demandée.

Par conséquent, que la consolidation soit activée ou non, il peut être suffisant pour de nombreux clients d'afficher uniquement le contenu de premier niveau d'une ressource DriveActivity (tels que les acteurs et les cibles collectifs dans primaryActionDetail) et d'ignorer les actions détaillées dans la réponse.

Filtres

Vous pouvez limiter les actions susceptibles d'être renvoyées dans la ressource DriveActivity en construisant une chaîne filter dans la requête activity.query. Deux champs sont acceptés: time et detail.action_detail_case.

Filtrer par période

Pour limiter les actions par période, spécifiez le nom de champ time avec des opérateurs numériques sur des valeurs de date, jointes par un "AND" facultatif. Utilisez les millisecondes depuis le 1er janvier 1970 ou le format RFC 3339, par exemple:

  • time > 1452409200000 AND time <= 1492812924310
  • time >= "2016-01-10T01:02:03-05:00"

Filtrer par type

Pour effectuer une restriction en fonction du type d'action, appliquez le nom de champ detail.action_detail_case avec l'opérateur "has" (:). Utilisez soit une valeur singulier, soit une liste de types d'actions autorisées délimitées par des parenthèses et séparés par un espace. Pour obtenir la liste des types d'actions, consultez les objets ActionDetail.

Pour exclure un type d'action de la réponse, ajoutez un trait d'union (-) au début de la chaîne de filtre.

Voici quelques exemples de types d'actions:

  • detail.action_detail_case:RENAME
  • detail.action_detail_case:(CREATE RESTORE)
  • -detail.action_detail_case:MOVE

Combinaisons

Ces conditions de filtrage peuvent être combinées dans une seule chaîne filter, comme suit:

  • detail.action_detail_case:(CREATE EDIT RESTORE) time > 1452409200000

Exemples de requête

Demandez les 10 activités les plus récentes pour un élément Drive:

{
  "itemName": "items/ITEM_ID",
  "pageSize": 10
}

Demandez le regroupement des activités pour chaque élément Drive situé sous un dossier ancêtre:

{
  "ancestorName": "items/ITEM_ID",
  "consolidationStrategy": {
    "legacy": {}
  }
}

Demandez toutes les actions MOVE et RENAME sur un élément Drive:

{
  "itemName": "items/ITEM_ID",
  "filter": "detail.action_detail_case:(MOVE RENAME)"
}

Demandez toute l'activité depuis le 1er janvier 2018 EST:

{
  "ancestorName": "items/root",
  "filter": "time >= \"2018-01-01T00:00:00-05:00\""
}

Demandez toutes les activités, à l'exception des actions EDIT, en juin 2017 UTC:

{
  "ancestorName": "items/root",
  "filter": "time >= \"2018-06-01T00:00:00Z\" time < \"2018-07-01T00:00:00Z\" -detail.action_detail_case:EDIT"
}