Travailler avec des événements Google Drive

Cette page explique comment recevoir des événements Google Drive à partir de Google Cloud Pub/Sub.

Un événement Drive représente une activité ou une modification apportée à une ressource Drive, comme un nouveau fichier dans un dossier. Vous pouvez utiliser des événements pour comprendre ce qui s'est passé, puis prendre des mesures ou répondre de manière pertinente à vos utilisateurs.

Voici quelques exemples d'utilisation des événements :

Observer et répondre aux modifications apportées à un fichier, un dossier ou un Drive partagé, par exemple lorsqu'un fichier est modifié ou qu'une nouvelle révision est importée.
Surveiller les modifications apportées aux fichiers pour améliorer les performances de votre application.
Auditer les activités telles que le partage, le déplacement et la suppression de fichiers pour détecter les fuites de données potentielles et les accès non autorisés.
Fournir des informations sur la façon dont les utilisateurs gèrent leurs fichiers, ce qui permet d'identifier les domaines dans lesquels la gestion des contenus pourrait être améliorée.
Suivre les modifications apportées aux fichiers pour vérifier la conformité avec les exigences réglementaires ou les règles de sécurité.
Analyser l'activité Drive à l'aide d'autres produits Google Cloud tels qu'Eventarc, Workflows, et BigQuery.

Fonctionnement des événements

Chaque fois qu'un événement se produit dans Drive, une ressource de l'API Google Drive est créée, mise à jour ou supprimée. Drive utilise des événements pour fournir à votre application des informations sur le type d'activité qui s'est produit et sur la ressource de l'API Drive qui a été affectée.

Drive classe les événements par type. Les types d'événements vous aident à filtrer et à ne recevoir que le type d'informations dont vous avez besoin, et vous permettent de gérer les activités similaires de la même manière.

Le tableau suivant montre comment un exemple d'activité dans Drive affecte une ressource d'API Drive associée et le type d'événement que votre application Drive reçoit :

Activité	Ressource de l'API Drive	Type d'événement
Un utilisateur crée une proposition d'accès sur un fichier.	Une ressource `AccessProposal` est créée.	Nouvelle proposition d'accès
Un utilisateur crée une approbation sur un fichier.	Une ressource `Approval` est créée.	Nouvelle approbation
Un utilisateur publie un commentaire dans un fichier Google Docs, Sheets ou Slides.	Une ressource `Comment` est créée.	Nouveau commentaire
Un utilisateur ajoute un fichier à un dossier ou à un Drive partagé.	Une ressource `File` est créée.	Nouveau fichier
Un utilisateur crée des autorisations sur un fichier.	Une ressource `Permission` est créée.	Nouvelle autorisation
Un utilisateur répond à un commentaire.	Une ressource `Reply` est créée.	Nouvelle réponse

Recevoir des événements de Google Drive

Traditionnellement, votre application Drive pouvait localiser des événements via l'API Drive ou l'API Google Drive Activity. Avec l'ajout d'événements Drive dans l'API Google Workspace Events, il existe désormais une troisième méthode pour recevoir des événements :

Abonnez-vous aux événements à l'aide de l'API Google Workspace Events pour les recevoir au fur et à mesure qu'ils se produisent. Pour en savoir plus, consultez S'abonner aux événements Google Drive.
Abonnez-vous aux événements à l'aide de l'API Drive. Obtenez des événements de modification d'utilisateur avec la changes.watch méthode ou des événements de modification de fichier avec la files.watch méthode.
Interrogez les événements récents en appelant l' API Google Drive Activity.

Le tableau suivant explique la différence et les raisons de s'abonner à des événements plutôt que de les interroger :

	S'abonner aux événements Google Workspace	S'abonner aux événements de surveillance de l'API Drive	Interroger les événements de l'API Drive Activity
Cas d'utilisation	Traiter les événements ou y répondre en temps réel. Surveiller les modifications apportées aux ressources pour améliorer les performances de votre application. Recevoir des données d'événement structurées via Pub/Sub et utiliser des produits Google Cloud tels que Cloud Run.	Détecter les modifications apportées aux métadonnées des fichiers et surveiller efficacement les modifications apportées à des éléments spécifiques grâce à des notifications en temps réel. Prend en charge une URL de rappel de webhook pour éviter d'interroger de manière répétée les points de terminaison de l'API.	Récupérer un historique détaillé de toutes les activités, y compris des informations précises sur chaque événement. Récupérer des activités précises incluant des informations `ActionDetail`, `Actor` et `Target` pour des tâches spécifiques telles que les audits.
API	API Google Workspace Events	API Google Drive	API Google Drive Activity
Source des événements	Fichiers, dossiers et Drive partagés	`changes.watch` et `files.watch`	`DriveActivity`
Événements compatibles	`AccessProposal` `Approval` `Comment` `File` `Permission` `Reply` Pour obtenir la liste des types d'événements acceptés, consultez la section Types d'événements pour créer des abonnements dans la documentation de l'API Google Workspace Events.	`Channel` Pour obtenir la liste des types d'événements acceptés, consultez la section Comprendre les événements de notification de l'API Google Drive dans la documentation de l'API Drive.	`Action` Pour obtenir la liste des champs acceptés, consultez la section Ressource `Action` dans la documentation de référence de l'API Drive Activity.
Format des événements	Message Pub/Sub, mis en forme conformément à la spécification CloudEvents. Pour en savoir plus, consultez Structure des événements Google Workspace.	Ressource de l'API Drive (`Channel`)	Ressource de l'API Drive Activity (`Action`)
Données d'événement	Chaîne encodée en base64 avec ou sans données de ressource. Pour obtenir des exemples de charges utiles, consultez Données d'événement.	Charge utile JSON contenant des données de ressource. Pour obtenir un exemple de charge utile, consultez la `Channel` ressource dans la documentation de référence.	Charge utile JSON contenant des données de ressource. Pour obtenir un exemple de charge utile, consultez le `activity.query` corps de la réponse dans la documentation de référence.

Premiers pas avec les événements Drive

Ce guide explique comment créer et gérer un abonnement aux événements Google Workspace sur une ressource Drive. Cela permet à votre application de recevoir des événements via Google Cloud Pub/Sub.

Créer un projet Google Cloud

Pour générer un projet Google Cloud, consultez Créer un projet Google Cloud project.

Activer l'API Google Workspace Events, l'API Google Cloud Pub/Sub et l'API Google Drive

Avant d'utiliser les API Google, vous devez les activer dans un projet Google Cloud. Vous pouvez activer une ou plusieurs API dans un même projet Google Cloud.

Console Google Cloud

Dans la console Google Cloud, ouvrez le projet Google Cloud de votre application et activez l'API Google Workspace Events, l'API Pub/Sub et l'API Drive :

Activer les API
Vérifiez que vous activez les API dans le bon projet Cloud, puis cliquez sur Suivant.
Vérifiez que vous activez les bonnes API, puis cliquez sur Activer.

gcloud

Dans votre répertoire de travail, connectez-vous à votre compte Google :
```
gcloud auth login
```
Définissez votre projet sur le projet Cloud de votre application :
```
gcloud config set project PROJECT_ID
```
Remplacez PROJECT_ID par l'ID de projet du projet Cloud de votre application.

Activez l'API Google Workspace Events, l'API Pub/Sub et l'API Drive :

gcloud services enable workspaceevents.googleapis.com \
pubsub.googleapis.com \
drive.googleapis.com

Configurer un ID client

Pour générer un ID client OAuth 2.0, consultez Créer des identifiants d'ID client OAuth.

Créer un sujet Pub/Sub

Avant de créer un abonnement, vous devez créer un sujet Google Cloud Pub/Sub qui reçoit les événements pertinents qui intéressent votre application. Pour créer le sujet Pub/Sub, consultez Créer un sujet Pub/Sub et s'y abonner.

Veillez à faire référence au compte de service Drive (drive-api-event-push@system.gserviceaccount.com) pour vos requêtes.

Créer un abonnement Drive

Les événements cloud sont envoyés lorsque le sujet de l'abonnement (ou tout autre fichier sous la hiérarchie du sujet) est modifié. Par exemple, si vous créez un abonnement sur un Drive partagé et qu'un fichier est modifié dans plusieurs sous-dossiers de ce Drive partagé, un événement est généré. Pour connaître les ressources et les types d'événements Drive compatibles, consultez Types d'événements pour créer des abonnements.

L'application Node.js suivante crée un abonnement aux événements Drive sur un fichier ou un dossier pour écouter les événements de modification de contenu. Pour en savoir plus, consultez Créer un abonnement Google Workspace.

Pour exécuter cet exemple, assurez-vous que Node.js et npm sont installés. Vous devez également vous assurer que les dépendances requises sont installées pour exécuter cet exemple.

# Install needed dependencies
$ npm install googleapis @google-cloud/local-auth axios

Pour créer un abonnement Drive, utilisez la méthode subscriptions.create de l'API Google Workspace Events afin de créer une Subscription ressource :

// app.js

const fs = require('fs').promises;
const {authenticate} = require('@google-cloud/local-auth');
const {google} = require('googleapis');
const axios = require('axios');

// Scopes for Google Drive API access.
const SCOPES = ['SCOPES'];

/**
 * Authenticates the user running the script.
 * @return {Promise<OAuth2Client>} The authorized client.
 */
async function authorize() {
  const client = await authenticate({
    scopes: SCOPES,
    keyfilePath: 'credentials.json',
  });
  if (client.credentials) {
    const content = await fs.readFile('credentials.json');
    const keys = JSON.parse(content);
    const {client_id, client_secret} = keys.installed || keys.web;
    const payload = JSON.stringify({
      type: 'authorized_user',
      client_id,
      client_secret,
      refresh_token: client.credentials.refresh_token,
    });
    await fs.writeFile('token.json', payload);
    return client;
  } else {
    throw new Exception(
        'credentials.json did not have the Oauth client secret or it was not properly formatted');
  }
  }

/**
 * Creates a subscription to Google Drive events.
 * @param {OAuth2Client} authClient An authorized OAuth2 client.
 */
async function createSubscription(authClient) {
  const url = 'https://workspaceevents.googleapis.com/v1/subscriptions';
  const data = {
    targetResource: 'TARGET_RESOURCE',
    eventTypes: ['EVENT_TYPES'],
    payload_options: {
      include_resource: {
        {
          'RESOURCE_DATA'
        }
      }
    },
    drive_options: {
      include_descendants: {
        {
          'INCLUDE_DESCENDANTS'
        }
      }
    },
    notification_endpoint: {pubsub_topic: 'TOPIC_NAME'}
  };
  try {
    const {token} = await authClient.getAccessToken();
    const response = await axios.post(
        url, data, {headers: {'Authorization': `Bearer ${token}`}});
    console.log('Subscription created:', response.data);
  } catch (error) {
    const message = error.response ? error.response.data : error.message;
    console.error('Error creating subscription:', message);
  }
}

authorize().then(createSubscription).catch(console.error);

Remplacez les éléments suivants :

SCOPES : un ou plusieurs champs d'application OAuth qui prennent en charge chaque type d'événement pour l' abonnement. Formaté sous forme de tableau de chaînes. Pour lister plusieurs champs d'application, séparez-les par des virgules. Nous vous recommandons d'utiliser le champ d'application le plus restrictif qui permet à votre application de fonctionner. Par exemple, 'https://www.googleapis.com/auth/drive.file'.
TARGET_RESOURCE : ressource Google Workspace à laquelle vous vous abonnez, mise en forme sous son nom de ressource complet. Par exemple, pour vous abonner à un fichier ou à un dossier Drive, utilisez //drive.googleapis.com/files/FileID.
EVENT_TYPES : un ou plusieurs types d'événements auxquels vous souhaitez vous abonner dans la ressource cible. Format sous forme de tableau de chaînes, tel que 'google.workspace.drive.file.v3.contentChanged'.
RESOURCE_DATA: valeur booléenne qui indique si l'abonnement inclut des données de ressource dans la charge utile de l'événement. Cette propriété affecte la durée de votre abonnement. Pour en savoir plus, consultez Données d'événement.
- True : inclut toutes les données de ressource. Pour limiter les champs inclus, ajoutez fieldMask et spécifiez au moins un champ pour la ressource modifiée. Seuls les abonnements aux ressources Chat et Drive sont compatibles avec l'inclusion de données de ressource.
- False : exclut les données de ressource.
INCLUDE_DESCENDANTS : champ booléen qui fait partie de DriveOptions. Disponible uniquement lorsque targetResource est un fichier Drive ou un Drive partagé dont le type MIME est défini sur application/vnd.google-apps.folder. Ne peut pas être défini sur le dossier racine de Mon Drive ni sur les Drive partagés.
- True: l'abonnement inclut tous les fichiers Drive descendants dans la liste des événements.
- False: l'abonnement est créé pour le fichier unique ou le Drive partagé spécifié comme targetResource.
TOPIC_NAME: nom complet du sujet Pub/Sub que vous avez créé dans votre projet Cloud. Ce sujet Pub/Sub reçoit les événements de l'abonnement. Formaté sous la forme projects/PROJECT_ID/topics/TOPIC_ID. The notificationEndpoint champ permet de spécifier le sujet Pub/Sub et c'est là que l'abonnement fournit les événements.

Tester votre abonnement Drive

Pour vérifier que vous recevez des événements Drive, vous pouvez déclencher un événement et extraire des messages vers l'abonnement Pub/Sub. Pour en savoir plus, consultez Tester votre abonnement Google Workspace.

Traiter les événements Drive à l'aide de Cloud Functions

Les événements Drive sont envoyés au sujet Pub/Sub dans l'abonnement que vous créez. Lorsque vous créez le déclencheur, assurez-vous que le sujet Pub/Sub du déclencheur correspond au sujet Pub/Sub de votre abonnement aux événements. Vous pouvez ensuite déployer votre fonction Cloud Run et modifier le fichier pour afficher les modifications d'événement dans les journaux.

Avant de créer la fonction, mettez à jour le package.json pour les dépendances :

{
  "dependencies": {
    "@google-cloud/functions-framework": "^3.0.0",
    "cloudevents": "^8.0.0"
  }
}

Ensuite, créez le code source de la fonction :

const functions = require('@google-cloud/functions-framework');
const { HTTP } = require("cloudevents");

/**
 * A Cloud Function triggered by Pub/Sub messages containing Google Drive activity events.
 * This function processes different types of Drive events.
 *
 * @param {object} cloudEvent The CloudEvent object.
 * @param {object} cloudEvent.data The data payload from the event source.
 */
functions.cloudEvent('helloFromDrive', async (cloudEvent) => {
  try {
    // Verify the Pub/Sub message exists
    if (!cloudEvent.data || !cloudEvent.data.message) {
      console.warn("Event is missing the Pub/Sub message payload.");
      return;
    }

    // Extract the Pub/Sub message details
    const { message } = cloudEvent.data;
    const { attributes, data } = message;

    // The original Drive CloudEvent is reconstructed from the Pub/Sub message attributes
    const driveEvent = HTTP.toEvent({ headers: attributes });
    const { type } = driveEvent;

    // The Drive event's payload is a base64 encoded JSON string
    const payload = JSON.parse(Buffer.from(data, "base64").toString());

    console.log(`Processing Drive event type: ${type}`);

    // Use a switch statement to handle different event types
    switch (type) {
      case 'google.workspace.drive.file.v3.contentChanged':
        console.log('File Content Changed:', payload);
        break;
      case 'google.workspace.drive.accessproposal.v3.created':
        console.log('Access Proposal Created:', payload);
        break;
      default:
        console.log(`Received unhandled event type: ${type}`);
        break;
    }
  } catch (error) {
    console.error("An error occurred while processing the Drive event:", error);
  }
});

Limites

Lorsque le champ booléen includeDescendants DriveOptions est true, les abonnements Drive sur les Drive partagés et les dossiers envoient toujours un événement, même si le fichier qui a déclenché l'événement est imbriqué plusieurs niveaux sous le dossier utilisé pour l'abonnement Drive.
Même si vous avez créé un abonnement sur un dossier, vous ne recevrez peut-être pas tous les événements de la hiérarchie des fichiers, car l'utilisateur ou l'application n'y aura peut-être pas accès. Dans ce cas, l'abonnement reste actif, mais vous ne recevrez aucun événement pour les ressources auxquelles vous n'avez pas accès.
Les abonnements sont compatibles avec les événements sur tous les fichiers et dossiers, mais pas sur le dossier racine des Drive partagés. Les abonnements ne sont compatibles qu'avec les fichiers et les dossiers dans les Drive partagés. Les modifications apportées directement au dossier racine d'un Drive partagé ne déclenchent pas d'événements.
L'utilisateur qui autorise l'abonnement doit disposer d'une autorisation sur le fichier correspondant aux événements auxquels il s'abonne.
L'abonnement ne reçoit que les événements pour les ressources auxquelles l'utilisateur a accès via son compte Google Workspace ou son compte Google.

Travailler avec des événements Google Drive Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.