Questa pagina è stata tradotta dall'API Cloud Translation.

Lavorare con gli eventi di Google Drive

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

Un evento Drive rappresenta un'attività o una modifica a una risorsa Drive, ad esempio un nuovo file in una cartella. Puoi utilizzare gli eventi per capire cosa è successo e poi intervenire 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 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, 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 succede qualcosa in Drive, una risorsa API Google Drive viene creata, aggiornata o eliminata. Drive utilizza gli eventi per fornire alla tua app informazioni sul tipo di attività che si è verificata e sulla risorsa 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à in Drive influisce su una risorsa API Drive correlata e il tipo di evento ricevuto dall'app Drive:

Attività	Risorsa API Drive	Tipo di evento
Un utente aggiunge un file a una cartella o a un Drive condiviso.	Viene creata una risorsa `File`.	Nuovo file
Un utente crea una proposta di accesso a un file.	Viene creata una risorsa `AccessProposal`.	Nuova proposta di accesso

Ricevere eventi da Google Drive

Tradizionalmente, 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:

Anteprima per gli sviluppatori: iscriviti agli eventi utilizzando l' API Google Workspace Events per ricevere gli eventi man mano che si verificano.
Iscriviti agli eventi utilizzando l'API Drive. Recupera gli eventi di modifica utente 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 è consigliabile abbonarsi agli eventi anziché eseguire query per recuperarli:

	Iscriversi agli eventi di Google Workspace	Abbonarsi 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 degli eventi strutturati tramite Pub/Sub e utilizza prodotti Google Cloud come Cloud Run.	Rileva le modifiche ai metadati dei file e monitora in modo efficiente le modifiche a elementi specifici con notifiche in tempo reale. Supporta un URL di callback webhook per evitare di eseguire il polling ripetuto 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 Drive	Drive Activity API
Origine degli eventi	File, cartelle e Drive condivisi	`changes.watch` e `files.watch`	`DriveActivity`
Eventi supportati	`File` `AccessProposal` Per un elenco dei tipi di eventi supportati, vedi 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 la sezione Informazioni sugli 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 Google Workspace.	Una risorsa dell'API Drive (`Channel`)	Una risorsa API Drive Activity (`Action`)
Dati sugli eventi	Stringa con codifica Base64 con o senza dati delle risorse. Per esempi di payload, vedi Dati sugli eventi.	Payload JSON contenente i dati delle risorse. Per un esempio di payload, consulta la risorsa `Channel` nella documentazione di riferimento.	Payload JSON contenente i dati delle risorse. Per un esempio di payload, consulta il corpo della risposta `activity.query` 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 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 Creare un progetto Google Cloud.

Abilita 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 Google Cloud per la tua app e attiva l'API Google Workspace Events, l'API Pub/Sub e l'API Drive:

Abilita le API
Verifica di abilitare le API nel progetto Cloud corretto, poi fai clic su Avanti.
Verifica di abilitare le API corrette, poi 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 per il progetto cloud della 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, consulta la pagina Creare credenziali ID client OAuth.

crea un argomento Pub/Sub

Prima di creare un abbonamento, devi creare un argomento Google Cloud Pub/Sub che riceva gli eventi pertinenti a cui è interessata la tua applicazione. Per creare l'argomento Pub/Sub, consulta Creare un argomento Pub/Sub e sottoscriverlo.

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 cambia l'oggetto dell'abbonamento (o qualsiasi altro file sotto la gerarchia dell'oggetto). Ad esempio, se crei un abbonamento su un Drive condiviso e un file cambia all'interno di diverse sottocartelle del Drive condiviso, viene generato un evento. Per le risorse supportate e i tipi di eventi di Drive, consulta Tipi di eventi per la creazione di abbonamenti.

La seguente applicazione Node.js crea una sottoscrizione 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.

Per eseguire questo esempio, assicurati di aver installato Node.js e 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'];

/**
 * Loads saved credentials from token.json, or authenticates the user.
 * @return {Promise<OAuth2Client>} The authorized client.
 */
async function authorize() {
  try {
    const content = await fs.readFile('token.json');
    const credentials = JSON.parse(content);
    return google.auth.fromJSON(credentials);
  } catch (err) {
    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;
  }
}

/**
 * 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: 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 array di stringhe. Per elencare più ambiti, separali con le virgole. Come best practice, devi 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 abboni, formattata come nome completo della risorsa. Ad esempio, per iscriverti a un file o 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. Formatta come 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ù, consulta Dati evento.
- 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 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 il 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 è qui che la sottoscrizione distribuisce gli eventi.

Testare l'abbonamento a Drive

Per verificare di ricevere gli eventi di Drive, puoi attivare un evento e recuperare i messaggi nella sottoscrizione Pub/Sub. Per saperne di più, vedi Testare 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 di eventi. A questo punto puoi 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 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 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 all'interno della gerarchia di 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.
Le iscrizioni sono supportate 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 eventi.
L'utente che autorizza l'abbonamento deve disporre dell'autorizzazione per il file corrispondente agli eventi a cui si abbona.
L'abbonamento riceve solo eventi per le risorse a cui l'utente ha accesso tramite il proprio account Google Workspace o Account Google.