Se usó la API de Cloud Translation para traducir esta página.

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 una manera significativa para tus usuarios.

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

Observar los cambios en un archivo, una carpeta o una unidad compartida, y responder a ellos, 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, el movimiento y la eliminación de archivos para detectar posibles filtraciones de datos y accesos no autorizados.
Ofrecer 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
Hacer un seguimiento de los cambios en los archivos para verificar el cumplimiento de los requisitos reglamentarios o las políticas de seguridad
Analizar 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 se produjo 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 en Drive afecta 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 agrega un archivo a una carpeta o unidad compartida.	Se crea un recurso `File`.	Archivo nuevo
Un usuario crea una propuesta de acceso en un archivo.	Se crea un recurso `AccessProposal`.	Nueva propuesta de acceso

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 los eventos de Drive en la API de Google Workspace Events, ahora hay un tercer método para recibir eventos:

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

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

	Suscríbete a los eventos de Google Workspace	Suscríbete a los eventos de observación de la API de Drive	Consulta los eventos de la API de Drive Activity
Casos de uso	Procesar eventos o responder a ellos 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 Drive	Drive Activity API
Fuente de eventos	Archivos, carpetas y unidades compartidas	`changes.watch` y `files.watch`	`DriveActivity`
Eventos admitidos	`File` `AccessProposal` 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 admitidos, consulta Understand Google Drive API notification events 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	Es un mensaje de Pub/Sub con 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	Es una cadena codificada en Base64 con o sin datos de recursos. Para ver ejemplos de cargas útiles, consulta Datos de eventos.	Es la carga útil JSON que contiene datos de recursos. Para ver un ejemplo de carga útil, consulta el recurso `Channel` en la documentación de referencia.	Es la carga útil JSON que contiene datos de recursos. Para ver un ejemplo de carga útil, consulta el cuerpo de la respuesta de `activity.query` en la documentación de referencia.

Comienza a usar los 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 Crea un proyecto de Google Cloud.

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 de tu app y habilita las APIs de Google Workspace Events, Pub/Sub y 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 como el proyecto de Cloud de tu app:
```
gcloud config set project PROJECT_ID
```
Reemplaza PROJECT_ID por el ID del proyecto del proyecto de Cloud de tu app.

Habilita las APIs de Google Workspace Events, Pub/Sub y 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 los eventos relevantes que le interesan a 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) en tus solicitudes.

Crea una suscripción a Drive

Los eventos de Cloud se despachan 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 detectar eventos de cambio de contenido. Para obtener más información, consulta Cómo crear una suscripción a Google Workspace.

Para ejecutar este ejemplo, asegúrate de tener instalados Node.js y npm. 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.create() de la API de Google Workspace Events para crear un recurso 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);

Reemplaza lo siguiente:

SCOPES: Uno o más alcances de OAuth que admiten cada tipo de evento para la suscripción. Se da formato como un array de cadenas. Para enumerar varios permisos, sepáralos con comas. Como práctica recomendada, debes usar el alcance más restrictivo que permita que tu app siga funcionando. Por ejemplo, 'https://www.googleapis.com/auth/drive.file'.
TARGET_RESOURCE: Es el recurso de Google Workspace al que te suscribes, con el formato de su nombre completo. 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. Se debe dar formato como un array de cadenas, por ejemplo, '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 del recurso. Para limitar los campos incluidos, agrega fieldMask y especifica al menos un campo para el recurso modificado. Solo las suscripciones a 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 de MIME establecido en application/vnd.google-apps.folder. No se puede establecer en la carpeta raíz de Mi unidad ni en las unidades compartidas.
- True: La suscripción incluye todos los archivos descendientes de Drive en la lista de eventos.
- False: Se crea la suscripción para el archivo único o la unidad compartida que se especifica como targetResource.
TOPIC_NAME: Es 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. Tiene el formato projects/PROJECT_ID/topics/TOPIC_ID. El campo notificationEndpoint 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 Cómo probar 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. Cuando crees el activador, asegúrate de que el tema de Pub/Sub del activador coincida con el tema de Pub/Sub de tu suscripción a eventos. Luego, puedes implementar tu función de Cloud Run y editar el archivo para ver los cambios de eventos en los registros.

Antes de crear la función, actualiza 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 muchos niveles por 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 haya otorgado acceso a ellos 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.
Se admiten suscripciones para eventos en todos los archivos y carpetas, pero no en la carpeta raíz de las unidades compartidas. Las suscripciones solo se admiten para los archivos y las carpetas dentro de las unidades compartidas. Los cambios que se realicen 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.