Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

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 intraprendere un'azione o rispondere in modo significativo per i tuoi utenti.

Ecco alcuni esempi di come puoi utilizzare gli eventi:

Osserva e rispondi 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 il rendimento della tua app.
Controlla le attività come la condivisione, lo spostamento e l'eliminazione dei file per rilevare potenziali fughe di dati e accessi non autorizzati.
Offri informazioni su come gli utenti gestiscono i propri file, contribuendo a identificare le aree in cui la gestione dei contenuti potrebbe essere migliorata.
Monitora le modifiche ai file per verificare la conformità ai requisiti normativi o alle norme 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 le attività simili nello stesso modo.

La tabella seguente mostra in che modo un'attività di esempio in Drive influisce su una risorsa dell'API Drive correlata e sul tipo di evento che riceve la tua app Drive:

Attività	Risorsa dell'API Drive	Tipo di evento
Un utente crea una proposta di accesso a un file.	Viene creata una risorsa `AccessProposal`.	Nuova proposta di accesso
Un utente crea un'approvazione su un file.	Viene creata una risorsa `Approval`.	Nuova approvazione
Un utente pubblica un commento in un file di Documenti, Fogli o Presentazioni Google.	Viene creata una risorsa `Comment`.	Nuovo commento
Un utente aggiunge un file a una cartella o a un Drive condiviso.	Viene creata una risorsa `File`.	Nuovo file
Un utente crea le autorizzazioni per un file.	Viene creata una risorsa `Permission`.	Nuova autorizzazione
Un utente risponde a un commento.	Viene creata una risorsa `Reply`.	Nuova risposta

Ricevere eventi da Google Drive

In genere, la tua app Drive può 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ù, vedi Iscriversi agli eventi di Google Drive.
Iscriviti agli eventi utilizzando l'API Drive. Ricevi gli eventi di modifica dell'utente con il changes.watch metodo o gli eventi di modifica dei file con il files.watch metodo.
Esegui una query per gli eventi recenti chiamando l' API Google Drive Activity.

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

	Iscriversi agli eventi di Google Workspace	Iscriversi agli eventi di monitoraggio dell'API Drive	Eseguire query per gli eventi dell'API Drive Activity
Casi d'uso	Elabora o rispondi agli eventi in tempo reale. Monitora le modifiche alle risorse per migliorare il rendimento della tua app. Ricevi dati sugli eventi strutturati tramite Pub/Sub e utilizza i prodotti Google Cloud come Cloud Run.	Rileva le modifiche ai metadati dei file e monitora in modo efficiente le modifiche a elementi specifici con le notifiche in tempo reale. Supporta un URL di callback webhook per evitare di eseguire ripetutamente il polling degli endpoint API.	Recupera una cronologia dettagliata di tutte le attività, incluse informazioni granulari su ogni evento. Recupera attività precise che includono informazioni su `ActionDetail`, `Actor` e `Target` per attività specifiche come gli audit.
API	API Google Workspace Events	API Google Drive	API Google Drive Activity
Origine degli eventi	File, cartelle e Drive condivisi	`changes.watch` e `files.watch`	`DriveActivity`
Eventi supportati	`AccessProposal` `Approval` `Comment` `File` `Permission` `Reply` Per un elenco dei tipi di eventi supportati, consulta Tipi di eventi per la creazione di abbonamenti nella documentazione dell'API Google Workspace Events.	`Channel` Per un elenco dei tipi di eventi supportati, consulta Comprendere gli eventi di notifica dell'API Google Drive nella documentazione dell'API Drive.	`Action` Per un elenco dei campi supportati, consulta la risorsa `Action` nella documentazione di riferimento dell'API Drive Activity.
Formato degli eventi	Un messaggio Pub/Sub, formattato in base alla specifica CloudEvent. Per maggiori dettagli, vedi Struttura degli eventi di Google Workspace.	Una risorsa dell'API Drive (`Channel`)	Una risorsa dell'API Drive Activity (`Action`)
Dati sugli eventi	Stringa con codifica base64 con o senza dati delle risorse. Per i payload di esempio, vedi Dati sugli eventi.	Payload JSON contenente i dati delle risorse. Per un payload di esempio, consulta la `Channel` risorsa nella documentazione di riferimento.	Payload JSON contenente i dati delle risorse. Per un payload di esempio, consulta il `activity.query` corpo della risposta nella documentazione di riferimento.

Iniziare a utilizzare gli eventi di Drive

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

Creare un progetto Google Cloud

Per generare un progetto Google Cloud, vedi Creare un progetto Google Cloud.

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

Prima di utilizzare le API di Google, devi attivarle in un progetto Google Cloud. Puoi attivare una o più API in un singolo progetto Google Cloud.

Console Google Cloud

Nella console Google Cloud, apri il progetto cloud per la tua app e abilita l'API Google Workspace Events, l'API Pub/Sub e l'API Drive:

Abilitare le API
Verifica di aver abilitato le API nel progetto Cloud corretto, quindi fai clic su Avanti.
Verifica di aver abilitato le API corrette, quindi fai clic su Abilita.

gcloud

Nella directory di lavoro, accedi al tuo Account Google:
```
gcloud auth login
```
Imposta il progetto sul progetto Cloud per la tua app:
```
gcloud config set project PROJECT_ID
```
Sostituisci PROJECT_ID con l'ID progetto del progetto Cloud per la tua app.

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

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

Configurare un ID client

Per generare un ID client OAuth 2.0, vedi Creare le credenziali dell'ID client OAuth.

Creare un argomento Pub/Sub

Prima di creare un abbonamento, 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, vedi Creare e sottoscrivere un argomento Pub/Sub topic.

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

Creare un abbonamento a Drive

Gli eventi Cloud vengono inviati quando il soggetto dell'abbonamento (o qualsiasi altro file nella gerarchia del soggetto) viene modificato. Ad esempio, se crei un abbonamento a un Drive condiviso e un file nidificato in diverse sottocartelle di quel Drive condiviso viene modificato, viene generato un evento. Per le risorse supportate e i tipi di eventi di Drive, vedi Tipi di eventi per la creazione di abbonamenti.

L'applicazione Node.js seguente 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ù, vedi Creare un abbonamento a Google Workspace subscription.

Per eseguire questo esempio, assicurati di aver installato sia Node.js & npm installato. 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 Subscription risorsa:

// 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' abbonamento. Formattato come un array di stringhe. Per elencare più ambiti, separali con una virgola. Come best practice, dovresti utilizzare l'ambito più restrittivo che consenta comunque alla tua app di funzionare. Ad esempio, 'https://www.googleapis.com/auth/drive.file'.
TARGET_RESOURCE: la risorsa Google Workspace a cui ti stai abbonando, formattata come nome completo della risorsa. Ad esempio, per abbonarti 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 abbonarti nella risorsa di destinazione. Formattato come un array di stringhe, ad esempio 'google.workspace.drive.file.v3.contentChanged'.
RESOURCE_DATA: un valore booleano che specifica se l'abbonamento include i dati delle risorse nel payload dell'evento. Questa proprietà influisce sulla durata dell'abbonamento. Per saperne di più, vedi 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 impostato 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 l'abbonamento. Formattato come projects/PROJECT_ID/topics/TOPIC_ID. Il notificationEndpoint campo viene utilizzato per specificare l'argomento Pub/Sub e la posizione in cui l'abbonamento invia gli eventi.

Testare l'abbonamento a Drive

Per verificare di ricevere gli eventi di Drive, puoi attivare un evento ed estrarre i messaggi dall'abbonamento Pub/Sub. Per saperne di più, vedi Testare l'abbonamento a Google Workspace subscription.

Elaborare gli eventi di Drive utilizzando Cloud Functions

Gli eventi di Drive vengono inviati all'argomento Pub/Sub nell'abbonamento che crei. Quando crei il trigger, assicurati che l'argomento Pub/Sub per il trigger corrisponda all'argomento Pub/Sub nell'abbonamento agli eventi. A questo punto puoi eseguire il deployment della funzione Cloud Run e apportare modifiche al file per visualizzare le modifiche degli eventi nei log.

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

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

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

Limitazioni

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

Lavorare con gli eventi di Google Drive Mantieni tutto organizzato con le raccolte Salva e classifica i contenuti in base alle tue preferenze.