Cette page a été traduite par l'API Cloud Translation.

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 les é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 version est importée.
Surveillez les modifications apportées aux fichiers pour améliorer les performances de votre application.
Auditez les activités telles que le partage, le déplacement et la suppression de fichiers pour détecter les potentielles fuites de données et les accès non autorisés.
Fournissent des insights sur la façon dont les utilisateurs gèrent leurs fichiers, ce qui permet d'identifier les domaines dans lesquels la gestion de contenu pourrait être améliorée.
Suivez les modifications apportées aux fichiers pour vérifier la conformité avec les exigences réglementaires ou les règles de sécurité.
Analysez l'activité Drive à l'aide d'autres produits Google Cloud tels que 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 les informations et à ne recevoir que celles dont vous avez besoin. Ils vous permettent également de gérer les activités similaires de la même manière.

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

Activité	Ressource de l'API Drive	Type d'événement
Un utilisateur ajoute un fichier à un dossier ou à un Drive partagé.	Une ressource `File` est créée.	Nouveau fichier
Un utilisateur crée une proposition d'accès pour un fichier.	Une ressource `AccessProposal` est créée.	Nouvelle proposition d'accès

Recevoir des événements depuis 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 :

Preview développeur : abonnez-vous à des événements à l'aide de l' API Google Workspace Events pour recevoir des événements dès 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 les événements de modification d'utilisateur avec la méthode changes.watch ou les événements de modification de fichier avec la méthode files.watch.
Interrogez l'API Google Drive Activity pour obtenir les événements récents.

Le tableau suivant explique la différence entre s'abonner à des événements et les interroger, et les raisons de choisir l'une ou l'autre de ces options :

	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 ; Surveillez les modifications apportées aux ressources pour améliorer les performances de votre application. Recevez des données d'événement structurées via Pub/Sub et utilisez des produits Google Cloud tels que Cloud Run.	Détectez les modifications apportées aux métadonnées des fichiers et surveillez efficacement les modifications apportées à des éléments spécifiques grâce aux notifications en temps réel. Compatible avec une URL de rappel de webhook pour éviter d'interroger les points de terminaison de l'API à plusieurs reprises.	Récupérer un historique détaillé de toutes les activités, y compris des informations précises sur chaque événement. Récupérez des activités précises incluant des informations `ActionDetail`, `Actor` et `Target` pour des tâches spécifiques comme les audits.
API	API Google Workspace Events	API Drive	Drive Activity API
Source des événements	Fichiers, dossiers et Drive partagés	`changes.watch` et `files.watch`	`DriveActivity`
Événements compatibles	`File` `AccessProposal` Pour obtenir la liste des types d'événements acceptés, consultez Types d'événements pour la création d'abonnements dans la documentation de l'API Google Workspace Events.	`Channel` Pour obtenir la liste des types d'événements compatibles, consultez 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 compatibles, consultez la ressource `Action` dans la documentation de référence de l'API Drive Activity.
Format des événements	Message Pub/Sub, mis en forme selon la spécification CloudEvent. 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 ressources. Pour obtenir des exemples de charges utiles, consultez Données d'événement.	Charge utile JSON contenant les données de ressources. Pour obtenir un exemple de charge utile, consultez la ressource `Channel` dans la documentation de référence.	Charge utile JSON contenant les données de ressources. Pour obtenir un exemple de charge utile, consultez le corps de réponse `activity.query` 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.

Activez les API Google Workspace Events, Google Cloud Pub/Sub et 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 les API Google Workspace Events, Pub/Sub et 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 API appropriées, puis cliquez sur Activer.

gcloud

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

Activez les API Google Workspace Events, Pub/Sub et 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 ID client OAuth.

Créer un sujet Pub/Sub

Avant de créer un abonnement, vous devez créer un thème 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 demandes.

Créer un abonnement Drive

Les événements cloud sont déclenchés lorsque le sujet de l'abonnement (ou tout autre fichier de la hiérarchie du sujet) change. Par exemple, si vous créez un abonnement sur un Drive partagé et qu'un fichier imbriqué dans plusieurs sous-dossiers de ce Drive partagé est modifié, 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 la création d'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 d'avoir installé Node.js et npm. 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 ressource Subscription :

// 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/v1beta/subscriptions';
  const data = {
    targetResource: 'TARGET_RESOURCE',
    eventTypes: ['EVENT_TYPES'],
    payload_options: {
      include_resource: {
        {
          '<var>RESOURCE_DATA</var>'
        }
      }
    },
    drive_options: {
      include_descendants: {
        {
          '<var>INCLUDE_DESCENDANTS</var>'
        }
      }
    },
    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 scopes OAuth compatibles avec chaque type d'événement pour l'abonnement. Formaté sous forme de tableau de chaînes. Pour lister plusieurs portées, séparez-les par des virgules. Nous vous recommandons d'utiliser le champ d'application le plus restrictif qui permet à votre application de fonctionner. Exemple : 'https://www.googleapis.com/auth/drive.file'.
TARGET_RESOURCE : ressource Google Workspace à laquelle vous vous abonnez, formatée sous la forme de son nom complet. Par exemple, pour s'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. Mettez-le en forme de tableau de chaînes, comme 'google.workspace.drive.file.v3.contentChanged'.
RESOURCE_DATA : valeur booléenne qui indique si l'abonnement inclut des données de ressources 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 ressources. 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 permettent d'inclure des données de ressources.
- False : exclut les données de ressources.
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. Le fichier est au format projects/PROJECT_ID/topics/TOPIC_ID. Le champ notificationEndpoint permet de spécifier le sujet Pub/Sub auquel l'abonnement envoie les événements.

Tester votre abonnement Drive

Pour vérifier que vous recevez bien les événements Drive, vous pouvez déclencher un événement et extraire les 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 de l'abonnement que vous créez. Lorsque vous créez le déclencheur, assurez-vous que le sujet Pub/Sub correspondant correspond à celui de votre abonnement aux événements. Vous pouvez ensuite déployer votre fonction Cloud Run et modifier le fichier pour voir les changements d'événements dans les journaux.

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

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

Créez ensuite 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 dans DriveOptions est défini sur true, les abonnements Drive sur les Drive et dossiers partagés envoient toujours un événement, même si le fichier qui a déclenché l'événement est imbriqué plusieurs niveaux en dessous du dossier utilisé pour l'abonnement Drive.
Même si vous avez créé un abonnement à un dossier, il est possible que vous ne receviez pas tous les événements de la hiérarchie de fichiers, car l'utilisateur ou l'application n'y ont 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 acceptés pour les événements liés à tous les fichiers et dossiers, mais pas pour le dossier racine des Drive partagés. Les abonnements ne sont disponibles que pour les fichiers et 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.