Trabaja con eventos de Google Drive

En esta página, se explica cómo recibir eventos de Google Drive desde Google Cloud Pub/Sub.

Un evento de Drive representa una actividad o un cambio en un recurso de Drive, como un archivo nuevo en una carpeta. Puedes usar eventos para comprender lo que sucedió y, luego, tomar medidas o responder de manera significativa para tus usuarios.

Estos son algunos ejemplos de cómo puedes usar eventos:

Observa y responde a los cambios en un archivo, una carpeta o una unidad compartida, por ejemplo, cuando se edita un archivo o se sube una revisión nueva.
Supervisa los cambios en los archivos para mejorar el rendimiento de tu app.
Audita actividades como el uso compartido de archivos, los movimientos de archivos y las eliminaciones para ayudar a detectar posibles filtraciones de datos y accesos no autorizados.
Ofrece estadísticas sobre cómo los usuarios administran sus archivos, lo que ayuda a identificar áreas en las que se podría mejorar la administración de contenido.
Haz un seguimiento de los cambios en los archivos para verificar el cumplimiento de los requisitos reglamentarios o las políticas de seguridad.
Analiza la actividad de Drive con otros productos de Google Cloud , como Eventarc, Workflows, y BigQuery.

Cómo funcionan los eventos

Cada vez que sucede algo en Drive, se crea, actualiza o borra un recurso de la API de Google Drive. Drive usa eventos para entregar información a tu app sobre el tipo de actividad que ocurrió y el recurso de la API de Drive que se vio afectado.

Drive categoriza los eventos por tipo. Los tipos de eventos te ayudan a filtrar y recibir solo el tipo de información que necesitas, y te permiten controlar actividades similares de la misma manera.

En la siguiente tabla, se muestra cómo una actividad de ejemplo en Drive afecta a un recurso relacionado de la API de Drive y el tipo de evento que recibe tu app de Drive:

Actividad	Recurso de la API de Drive	Tipo de evento
Un usuario crea una propuesta de acceso en un archivo.	Se crea un recurso `AccessProposal`.	Nueva propuesta de acceso
Un usuario crea una aprobación en un archivo.	Se crea un recurso `Approval`.	Nueva aprobación
Un usuario publica un comentario en un archivo de Documentos, Hojas de cálculo o Presentaciones de Google.	Se crea un recurso `Comment`.	Nuevo comentario
Un usuario agrega un archivo a una carpeta o unidad compartida.	Se crea un recurso `File`.	Archivo nuevo
Un usuario crea permisos en un archivo.	Se crea un recurso `Permission`.	Permiso nuevo
Un usuario responde a un comentario.	Se crea un recurso `Reply`.	Nueva respuesta

Recibe eventos de Google Drive

Tradicionalmente, tu app de Drive podía ubicar eventos a través de la API de Drive o la API de Google Drive Activity. Con la incorporación de eventos de Drive en la API de Google Workspace Events, ahora hay un tercer método para recibir eventos:

Suscríbete a eventos con la API de Google Workspace Events para recibirlos a medida que ocurren. Para obtener más información, consulta Suscríbete a eventos de Google Drive.
Suscríbete a eventos con la API de Drive. Obtén eventos de cambio de usuario con el changes.watch método o eventos de cambio de archivo con el files.watch método.
Llama a la API de Google Drive Activity para consultar eventos recientes.

En la siguiente tabla, se explica la diferencia y los motivos para suscribirse a eventos en lugar de consultarlos:

	Suscríbete a eventos de Google Workspace	Suscríbete a eventos de observación de la API de Drive	Consulta eventos de la API de Drive Activity
Casos de uso	Procesa o responde a eventos en tiempo real. Supervisa los cambios en los recursos para mejorar el rendimiento de tu app. Recibe datos de eventos estructurados a través de Pub/Sub y usa productos de Google Cloud como Cloud Run.	Detecta cambios en los metadatos de los archivos y supervisa de manera eficiente los cambios en elementos específicos con notificaciones en tiempo real. Admite una URL de devolución de llamada de webhook para evitar sondear repetidamente los extremos de la API.	Recupera un historial detallado de todas las actividades, incluida información detallada sobre cada evento. Recupera actividades precisas que incluyen información de `ActionDetail`, `Actor` y `Target` para tareas específicas, como auditorías.
API	API de Google Workspace Events	API de Google Drive	API de Google Drive Activity
Fuente de eventos	Archivos, carpetas y unidades compartidas	`changes.watch` y `files.watch`	`DriveActivity`
Eventos admitidos	`AccessProposal` `Approval` `Comment` `File` `Permission` `Reply` Para obtener una lista de los tipos de eventos compatibles, consulta Tipos de eventos para crear suscripciones en la documentación de la API de Google Workspace Events.	`Channel` Para obtener una lista de los tipos de eventos compatibles, consulta Comprende los eventos de notificación de la API de Google Drive en la documentación de la API de Drive.	`Action` Para obtener una lista de los campos admitidos, consulta el recurso `Action` en la documentación de referencia de la API de Drive Activity.
Formato del evento	Un mensaje de Pub/Sub, con el formato según la especificación de CloudEvent. Para obtener más detalles, consulta Estructura de los eventos de Google Workspace.	Un recurso de la API de Drive (`Channel`)	Un recurso de la API de Drive Activity (`Action`)
Datos de eventos	String codificada en Base64 con o sin datos de recursos. Para ver cargas útiles de ejemplo, consulta Datos de eventos.	Carga útil de JSON que contiene datos de recursos. Para ver una carga útil de ejemplo, consulta el `Channel` recurso en la documentación de referencia.	Carga útil de JSON que contiene datos de recursos. Para ver una carga útil de ejemplo, consulta el `activity.query` cuerpo de la respuesta en la documentación de referencia.

Comienza a usar eventos de Drive

En esta guía, se explica cómo crear y administrar una suscripción a eventos de Google Workspace en un recurso de Drive. Esto permite que tu app reciba eventos a través de Google Cloud Pub/Sub.

Crea un proyecto de Google Cloud

Para generar un proyecto de Google Cloud, consulta Create a Google Cloud project.

Habilita la API de Google Workspace Events, la API de Google Cloud Pub/Sub y la API de Google Drive

Antes de usar las APIs de Google, debes activarlas en un proyecto de Google Cloud. Puedes activar una o más APIs en un solo proyecto de Google Cloud.

Consola de Google Cloud

En la consola de Google Cloud, abre el proyecto de Google Cloud para tu app y habilita la API de Google Workspace Events, la API de Pub/Sub y la API de Drive:

Habilita las APIs
Confirma que habilitarás las APIs en el proyecto de Cloud correcto y, luego, haz clic en Siguiente.
Confirma que habilitarás las APIs correctas y, luego, haz clic en Habilitar.

gcloud

En tu directorio de trabajo, accede a tu Cuenta de Google:
```
gcloud auth login
```
Configura tu proyecto en el proyecto de Cloud para tu app:
```
gcloud config set project PROJECT_ID
```
Reemplaza PROJECT_ID por el ID del proyecto de Cloud para tu app.

Habilita la API de Google Workspace Events, la API de Pub/Sub y la API de Drive:

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

Configura un ID de cliente

Para generar un ID de cliente de OAuth 2.0, consulta Crea credenciales de ID de cliente de OAuth.

Crea un tema de Pub/Sub

Antes de crear una suscripción, debes crear un tema de Google Cloud Pub/Sub que reciba eventos relevantes en los que esté interesada tu aplicación. Para crear el tema de Pub/Sub, consulta Crea un tema de Pub/Sub y suscríbete a él .

Asegúrate de hacer referencia a la cuenta de servicio de Drive (drive-api-event-push@system.gserviceaccount.com) para tus solicitudes.

Crea una suscripción a Drive

Los eventos de Cloud se envían cuando cambia el asunto de la suscripción (o cualquier otro archivo debajo de la jerarquía del asunto). Por ejemplo, si creas una suscripción en una unidad compartida y cambia un archivo anidado en varias subcarpetas de esa unidad compartida, se genera un evento. Para obtener información sobre los recursos admitidos y los tipos de eventos de Drive, consulta Tipos de eventos para crear suscripciones.

La siguiente aplicación de Node.js crea una suscripción a eventos de Drive en un archivo o una carpeta para escuchar eventos de cambio de contenido. Para obtener más información, consulta Crea una suscripción a Google Workspace.

Para ejecutar este ejemplo, asegúrate de tener instalados Node.js y npm instalados. También debes asegurarte de tener instaladas las dependencias necesarias para ejecutar este ejemplo.

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

Para crear una suscripción a Drive, usa el método subscriptions.createde la API de Google Workspace Events para crear un Subscription recurso:

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

Reemplaza lo siguiente:

SCOPES: Uno o más permisos de OAuth que admiten cada tipo de evento para la suscripción. Se formatea como un array de strings. Para enumerar varios permisos, sepáralos con comas. Como práctica recomendada, debes usar el permiso más restrictivo que permita que tu app funcione. Por ejemplo, 'https://www.googleapis.com/auth/drive.file'.
TARGET_RESOURCE: El recurso de Google Workspace al que te suscribes, con el formato de su nombre completo del recurso. Por ejemplo, para suscribirte a un archivo o una carpeta de Drive, usa //drive.googleapis.com/files/FileID.
EVENT_TYPES: Uno o más tipos de eventos a los que deseas suscribirte en el recurso de destino. Formatea como un array de strings, como 'google.workspace.drive.file.v3.contentChanged'.
RESOURCE_DATA: Es un valor booleano que especifica si la suscripción incluye datos de recursos en la carga útil del evento. Esta propiedad afecta la duración de tu suscripción. Para obtener más información, consulta Datos de eventos.
- True: Incluye todos los datos de recursos. Para limitar los campos incluidos, agrega fieldMask y especifica al menos un campo para el recurso modificado. Solo las suscripciones a los recursos de Chat y Drive admiten la inclusión de datos de recursos.
- False: Excluye los datos de recursos.
INCLUDE_DESCENDANTS: Es un campo booleano que forma parte de DriveOptions. Solo está disponible cuando targetResource es un archivo de Drive o una unidad compartida que tiene el tipo MIME establecido en application/vnd.google-apps.folder. No se puede configurar en la carpeta raíz de Mi unidad ni en las unidades compartidas.
- True: La suscripción incluye todos los archivos de Drive descendientes en la lista de eventos.
- False: La suscripción se crea para el archivo único o la unidad compartida que se especifica como targetResource.
TOPIC_NAME: El nombre completo del tema de Pub/Sub que creaste en tu proyecto de Cloud. Este tema de Pub/Sub recibe eventos para la suscripción. Se formatea como projects/PROJECT_ID/topics/TOPIC_ID. El notificationEndpoint campo se usa para especificar el tema de Pub/Sub y es donde la suscripción entrega eventos.

Prueba tu suscripción a Drive

Para probar que recibes eventos de Drive, puedes activar un evento y extraer mensajes a la suscripción de Pub/Sub. Para obtener más información, consulta Prueba tu suscripción a Google Workspace.

Procesa eventos de Drive con Cloud Functions

Los eventos de Drive se envían al tema de Pub/Sub en la suscripción que creas. Asegúrate de que, cuando crees el activador, el tema de Pub/Sub para el activador coincida con el tema de Pub/Sub en tu suscripción a eventos. Luego, puedes implementar tu función de Cloud Run y realizar ediciones en el archivo para ver los cambios de eventos en los registros.

Antes de crear la función, actualiza el package.json para las dependencias:

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

A continuación, crea el código fuente de la función:

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

Limitaciones

Cuando el campo booleano includeDescendants en DriveOptions es true, las suscripciones de Drive en unidades y carpetas compartidas siempre envían un evento, incluso si el archivo que activó el evento está anidado en muchas capas debajo de la carpeta que se usa para la suscripción de Drive.
Aunque hayas creado una suscripción en una carpeta, es posible que no recibas todos los eventos dentro de la jerarquía de archivos, ya que es posible que no se le otorgue acceso al usuario o a la aplicación. En este caso, la suscripción permanece activa, pero no recibirás ningún evento para los recursos a los que no tengas acceso.
Las suscripciones son compatibles con eventos en todos los archivos y carpetas, pero no en la carpeta raíz de unidades compartidas. Las suscripciones solo son compatibles con archivos y carpetas dentro de unidades compartidas. Los cambios realizados directamente en la carpeta raíz de una unidad compartida no activarán eventos.
El usuario que autoriza la suscripción debe tener permiso en el archivo correspondiente a los eventos a los que se suscribe.
La suscripción solo recibe eventos para los recursos a los que el usuario tiene acceso a través de su cuenta de Google Workspace o Cuenta de Google.

Trabaja con eventos de Google Drive Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.