Lavorare con gli eventi di Google Drive

Questa pagina spiega come ricevere eventi di Google Drive da Google Cloud Pub/Sub.

Un evento di Drive rappresenta un'attività o una modifica a una risorsa di Drive, ad esempio un nuovo file in una cartella. Puoi utilizzare gli eventi per capire cosa è successo e poi passare all'azione o rispondere in modo significativo per i tuoi utenti.

Ecco alcuni esempi di come puoi utilizzare gli eventi:

• Osservare e rispondere alle modifiche apportate a un file, una cartella o un Drive condiviso, ad esempio quando un file viene modificato o viene caricata una nuova revisione.

• Monitora le modifiche ai file per migliorare le prestazioni della tua app.

• Controlla attività come la condivisione, lo spostamento e l'eliminazione di file per rilevare potenziali fughe di dati e accessi non autorizzati.

• Offrono informazioni su come gli utenti gestiscono i propri file, aiutando a identificare le aree in cui la gestione dei contenuti potrebbe essere migliorata.

• Monitorare le modifiche ai file per verificare la conformità ai requisiti normativi o alle policy di sicurezza.

• Analizza l'attività di Drive utilizzando altri prodotti Google Cloud come Eventarc, Workflows e BigQuery.

Come funzionano gli eventi

Ogni volta che si verifica un evento in Drive, viene creata, aggiornata o eliminata una risorsa dell'API Google Drive. Drive utilizza gli eventi per fornire alla tua app informazioni sul tipo di attività che si è verificata e sulla risorsa dell'API Drive interessata.

Drive classifica gli eventi per tipo. I tipi di eventi ti aiutano a filtrare e ricevere solo il tipo di informazioni di cui hai bisogno e ti consentono di gestire attività simili nello stesso modo.

La tabella seguente mostra in che modo un'attività di esempio in Drive influisce su una risorsa API Drive correlata e il tipo di evento ricevuto dalla tua app Drive:

Ricevi eventi da Google Drive

In genere, l'app Drive poteva individuare gli eventi tramite l'API Drive o l'API Google Drive Activity. Con l'aggiunta degli eventi di Drive nell'API Google Workspace Events, ora esiste un terzo metodo per ricevere gli eventi:

• Iscriviti agli eventi utilizzando l'API Google Workspace Events per ricevere gli eventi man mano che si verificano. Per saperne di più, consulta Iscriviti agli eventi di Google Drive.

• Iscriviti agli eventi utilizzando l'API Drive. Recupera gli eventi di modifica degli utenti con il metodo changes.watch o gli eventi di modifica dei file utilizzando il metodo files.watch.

• Esegui query sugli eventi recenti chiamando l'API Google Drive Activity.

La tabella seguente spiega la differenza e i motivi per cui è preferibile iscriversi agli eventi anziché eseguire query:

Inizia a utilizzare gli eventi di Drive

Questa guida spiega come creare e gestire un abbonamento agli eventi di Google Workspace su una risorsa Drive. In questo modo, la tua app può ricevere eventi tramite Google Cloud Pub/Sub.

Crea un progetto Google Cloud

Per generare un progetto Google Cloud, consulta Crea un progetto Google Cloud.

Abilita l'API Google Workspace Events, l'API Google Cloud Pub/Sub e l'API Google Drive

Configura un ID client

Per generare un ID client OAuth 2.0, consulta Crea le credenziali dell'ID client OAuth.

Crea un argomento Pub/Sub

Prima di creare una sottoscrizione, devi creare un argomento Google Cloud Pub/Sub che riceva gli eventi pertinenti di interesse per la tua applicazione. Per creare l'argomento Pub/Sub, consulta Crea e sottoscrivi un argomento Pub/Sub.

Assicurati di fare riferimento al service account di Drive (drive-api-event-push@system.gserviceaccount.com) per le tue richieste.

Crea un abbonamento a Drive

Gli eventi Cloud vengono inviati quando l'oggetto della sottoscrizione (o qualsiasi altro file nella gerarchia dell'oggetto) cambia. Ad esempio, se crei un abbonamento su un Drive condiviso e un file nidificato in diverse sottocartelle di quel Drive condiviso cambia, viene generato un evento. Per le risorse e i tipi di eventi di Drive supportati, consulta Tipi di eventi per la creazione di abbonamenti.

La seguente applicazione Node.js crea un abbonamento agli eventi di Drive su un file o una cartella per ascoltare gli eventi di modifica dei contenuti. Per saperne di più, consulta Crea un abbonamento a Google Workspace.

Per eseguire questo esempio, assicurati di aver installato sia Node.js che npm. Devi anche assicurarti di aver installato le dipendenze richieste per eseguire questo esempio.

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

Per creare un abbonamento a Drive, utilizza il metodo subscriptions.create dell'API Google Workspace Events per creare una risorsa 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/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);

Sostituisci quanto segue:

• SCOPES: uno o più ambiti OAuth che supportano ogni tipo di evento per l'iscrizione. Formattato come array di stringhe. Per elencare più ambiti, separali con virgole. Come best practice, devi utilizzare l'ambito più restrittivo che consenta comunque il funzionamento della tua app. Ad esempio 'https://www.googleapis.com/auth/drive.file'.

• TARGET_RESOURCE: la risorsa Google Workspace a cui ti stai iscrivendo, formattata con il nome completo della risorsa. Ad esempio, per iscriverti a un file o a una cartella di Drive, utilizza //drive.googleapis.com/files/FileID.

• EVENT_TYPES: uno o più tipi di eventi a cui vuoi iscriverti nella risorsa di destinazione. Formato come array di stringhe, ad esempio 'google.workspace.drive.file.v3.contentChanged'.

• RESOURCE_DATA: un valore booleano che specifica se la sottoscrizione include i dati delle risorse nel payload dell'evento. Questa proprietà influisce sulla durata dell'abbonamento. Per saperne di più, consulta Dati sugli eventi.

  • True: include tutti i dati delle risorse. Per limitare i campi inclusi, aggiungi fieldMask e specifica almeno un campo per la risorsa modificata. Solo gli abbonamenti alle risorse di Chat e Drive supportano l'inclusione dei dati delle risorse.

  • False: esclude i dati delle risorse.

• INCLUDE_DESCENDANTS: un campo booleano che fa parte di DriveOptions. Disponibile solo quando targetResource è un file di Drive o un Drive condiviso con il tipo MIME impostato su application/vnd.google-apps.folder. Non può essere impostata nella cartella principale di Il mio Drive o dei Drive condivisi.

  • True: l'abbonamento include tutti i file di Drive discendenti nell'elenco degli eventi.

  • False: l'abbonamento viene creato per il singolo file o Drive condiviso specificato come targetResource.

• TOPIC_NAME: il nome completo dell'argomento Pub/Sub che hai creato nel tuo progetto cloud. Questo argomento Pub/Sub riceve gli eventi per la sottoscrizione. Formattato come projects/PROJECT_ID/topics/TOPIC_ID. Il campo notificationEndpoint viene utilizzato per specificare l'argomento Pub/Sub ed è il punto in cui la sottoscrizione invia gli eventi.

Testa l'abbonamento a Drive

Per verificare che stai ricevendo gli eventi di Drive, puoi attivare un evento ed eseguire il pull dei messaggi nella sottoscrizione Pub/Sub. Per saperne di più, consulta Testa l'abbonamento a Google Workspace.

Elabora gli eventi di Drive utilizzando Cloud Functions

Gli eventi di Drive vengono inviati all'argomento Pub/Sub nella sottoscrizione che crei. Quando crei il trigger, assicurati che l'argomento Pub/Sub per il trigger corrisponda all'argomento Pub/Sub nella sottoscrizione agli eventi. Puoi quindi eseguire il deployment della funzione Cloud Run e apportare modifiche al file per visualizzare le modifiche agli eventi nei log.

Prima di creare la funzione, aggiorna il file package.json per le dipendenze:

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

Quindi, crea il codice sorgente per la funzione:

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);
  }
});

• Quando il campo booleano includeDescendants in DriveOptions è true, le sottoscrizioni di Drive su Drive e cartelle condivisi inviano sempre un evento, anche se il file che ha attivato l'evento è nidificato molti livelli sotto la cartella utilizzata per la sottoscrizione di Drive.
• Anche se hai creato una sottoscrizione su una cartella, potresti non ricevere tutti gli eventi all'interno della gerarchia dei file, poiché l'utente o l'applicazione potrebbe non avere l'autorizzazione di accesso. In questo caso, l'abbonamento rimane attivo, ma non riceverai eventi per le risorse a cui non hai accesso.
• Le iscrizioni sono supportate per gli eventi su tutti i file e le cartelle, ma non sulla cartella principale dei Drive condivisi. Le iscrizioni sono supportate solo per i file e le cartelle all'interno dei Drive condivisi. Le modifiche apportate direttamente alla cartella principale di un Drive condiviso non attiveranno eventi.
• L'utente che autorizza l'abbonamento deve disporre dell'autorizzazione per il file corrispondente agli eventi a cui si iscrive.
• L'abbonamento riceve solo gli eventi per le risorse a cui l'utente ha accesso tramite il proprio account Google Workspace o Account Google.

Per informazioni sulle quote di abbonamento e sui limiti di frequenza, consulta Limiti di utilizzo dell'API Google Workspace Events.

Argomenti correlati

• Panoramica dell'API Google Workspace Events
• Crea un abbonamento a Google Workspace
• Iscriviti agli eventi di Google Drive
• Limiti di utilizzo dell'API Google Workspace Events