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

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

Clé de requête

Vous pouvez demander une activité de deux manières: par élément Google Drive ou pour tout ce qui se trouve 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 dans Drive. Si vous spécifiez un dossier pour cette clé, il affiche l'activité du dossier, par exemple la date de sa création ou de son renommage.

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

Lorsqu'aucune clé n'est définie, la valeur par défaut est ancestorName de "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.

Les tailles de page sont limitées. Si votre application a besoin 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, si l'activité à extraire est plus importante que ce qui est inclus dans la réponse, la réponse contient é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.

Consolidation

Les objets Action sont souvent regroupés et renvoyés dans une seule ressource DriveActivity. Certains regroupements Action se produisent spontanément, par exemple lorsque le déplacement d'un élément vers 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, tels que plusieurs acteurs modifiant un élément ou un Actor déplaçant plusieurs fichiers dans un nouveau dossier Drive.

Alors qu'un Action individuel comporte un Actor et un Target, après le regroupement, le DriveActivity obtenu peut avoir plusieurs acteurs et plusieurs cibles. Toutefois, même après le regroupement, il existe toujours une action "principale" qui est représentative ou la plus importante de toutes les actions de 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 suffire à de nombreux clients de n'afficher que le contenu de premier niveau d'une ressource DriveActivity (comme les acteurs et les cibles collectifs dans le primaryActionDetail) et d'ignorer les actions détaillées dans la réponse.

Filtres

Vous pouvez limiter les actions pouvant être renvoyées dans la ressource DriveActivity en créant 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 les valeurs de date, associés par un "AND" facultatif. Utilisez des millisecondes écoulées 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 limiter par type d'action, appliquez le nom de champ detail.action_detail_case avec l'opérateur "a" (:). Utilisez une valeur au singulier ou une liste de types d'actions autorisés entre parenthèses, 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, par exemple:

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

Exemples de requête

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

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

Demander des activités consolidées pour chaque élément Drive sous un dossier parent:

{
  "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)"
}

Demander toutes les activités depuis le 1er janvier 2018 (heure de l'Est) :

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

Demandez toutes les activités, à l'exception des actions EDIT, pour le mois de juin 2017 en temps UTC:

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