Работа с событиями из Google Диска

На этой странице объясняется, как получать события Google Drive из Google Cloud Pub/Sub .

Событие Google Диска представляет собой действие или изменение ресурса Диска, например, добавление нового файла в папку. Вы можете использовать события, чтобы понять, что произошло, и затем предпринять соответствующие действия, или чтобы дать пользователям осмысленный ответ.

Вот несколько примеров того, как можно использовать события:

  • Отслеживайте и реагируйте на изменения в файле, папке или общем диске, например, когда файл редактируется или загружается новая версия.

  • Отслеживайте изменения в файлах, чтобы повысить производительность вашего приложения.

  • Проведение аудита, включая обмен файлами, перемещение и удаление файлов, помогает выявлять потенциальные утечки данных и несанкционированный доступ.

  • Предоставляет информацию о том, как пользователи управляют своими файлами, помогая выявить области, где можно улучшить управление контентом.

  • Отслеживайте изменения в файлах для проверки соответствия нормативным требованиям или политикам безопасности.

  • Анализируйте активность в Google Диске, используя другие продукты Google Cloud, такие как Eventarc , Workflows и BigQuery .

Как проходят мероприятия

При каждом изменении в Google Диске создается, обновляется или удаляется ресурс Google Дискового API. Диск использует события для передачи вашему приложению информации о типе произошедшей активности и о ресурсе Дискового API, который был затронут.

Drive классифицирует события по типу. Типы событий помогают фильтровать и получать только необходимую информацию, а также позволяют обрабатывать похожие действия одинаковым образом.

В следующей таблице показано, как пример действия в Google Диска влияет на связанный ресурс API Google Диска, а также тип события, которое получает ваше приложение Google Диска:

Активность Ресурс Drive API Тип события
Пользователь создает предложение о доступе к файлу. Создан ресурс AccessProposal . Новое предложение по доступу

Пользователь создает запрос на утверждение файла.

 Создан ресурс Approval . Новое одобрение
Пользователь оставляет комментарий в файле Google Docs, Sheets или Slides. Создан ресурс Comment . Новый комментарий
Пользователь добавляет файл в папку или на общий диск. Создан ресурс File . Новый файл
Пользователь отвечает на комментарий. Создан ресурс Reply . Новый ответ

Получайте события из Google Диска

Традиционно ваше приложение «Диск» могло получать события либо через API Дистрибьютора, либо через API активности Дистрибьютора. С добавлением событий Дистрибьютора в API событий Google Рабочей области появился третий способ получения событий:

  • Предварительная версия для разработчиков : Подпишитесь на события с помощью API событий Google Workspace , чтобы получать события по мере их возникновения. Для получения дополнительной информации см. раздел «Подписка на события Google Drive» .

  • Подпишитесь на события, используя API Google Drive. Получайте события изменения данных пользователем с помощью метода changes.watch или события изменения файлов с помощью метода files.watch .

  • Запрос последних событий можно выполнить, обратившись к API активности Google Drive .

В таблице ниже объясняется разница и причины подписки на мероприятия по сравнению с запросом информации о них:

Подпишитесь на мероприятия Google Workspace Подпишитесь на отслеживание событий Drive API Запрос событий API активности Google Диска
Варианты использования
  • Обрабатывайте события или реагируйте на них в режиме реального времени.
  • Отслеживайте изменения в ресурсах, чтобы повысить производительность вашего приложения.
  • Получайте структурированные данные о событиях через Pub/Sub и используйте продукты Google Cloud, такие как Cloud Run.
  • Обнаруживайте изменения в метаданных файлов и эффективно отслеживайте изменения в конкретных элементах с помощью уведомлений в режиме реального времени.
  • Поддерживает URL-адрес обратного вызова веб-перехватчика, что позволяет избежать многократного опроса конечных точек API.
  • Получите подробную историю всех действий, включая детальную информацию о каждом событии.
  • Получайте точные данные о действиях, включая информацию о ActionDetail , Actor и Target , для выполнения конкретных задач, таких как аудит.
API API событий Google Workspace API Google Drive API активности Google Диска
Источник событий Файлы, папки и общие диски changes.watch и files.watch DriveActivity
Поддерживаемые мероприятия
  • AccessProposal
  • Approval
  • Comment
  • File
  • Reply
Список поддерживаемых типов событий см. в разделе «Типы событий для создания подписок» в документации по API событий Google Workspace.		 Channel

Список поддерживаемых типов событий см. в разделе « Понимание событий уведомлений Google Drive API» в документации по Drive API.		 Action

Список поддерживаемых полей см. в ресурсе Action в справочной документации по API действий на диске.
Формат мероприятия Сообщение Pub/Sub, отформатированное в соответствии со спецификацией CloudEvent. Подробности см. в разделе «Структура событий Google Workspace» . Ресурс API Google Drive ( Channel ) Ресурс API активности Google Диска ( Action )
данные о событии Строка, закодированная в Base64, с данными о ресурсах или без них. Примеры полезной нагрузки см. в разделе «Данные событий» . JSON-данные, содержащие информацию о ресурсе. Пример данных можно найти в документации по ресурсу Channel . JSON-данные, содержащие информацию о ресурсах. Пример данных можно найти в теле ответа activity.query в справочной документации.

Начните работу с мероприятиями Drive.

В этом руководстве объясняется, как создать и управлять подпиской на события Google Workspace для ресурса Google Диска. Это позволит вашему приложению получать события через Google Cloud Pub/Sub.

Создайте проект в Google Cloud.

Чтобы создать проект Google Cloud, см. раздел «Создание проекта Google Cloud» .

Включите API событий Google Workspace, API Google Cloud Pub/Sub и API Google Drive.

Перед использованием API Google необходимо включить их в проекте Google Cloud. В одном проекте Google Cloud можно включить один или несколько API.

Консоль Google Cloud

  1. В консоли Google Cloud откройте проект Google Cloud для вашего приложения и включите API событий Google Workspace, API публикации/подписки и API Google Drive:

    Включите API

  2. Убедитесь, что вы включаете API в правильном облачном проекте, затем нажмите «Далее» .

  3. Убедитесь, что вы включаете правильные API, затем нажмите «Включить» .

gcloud

  1. В своей рабочей директории войдите в свой аккаунт Google:

    gcloud auth login

  2. Установите для своего приложения облачный проект:

    gcloud config set project PROJECT_ID

    Замените PROJECT_ID на идентификатор проекта Cloud для вашего приложения.

  3. Включите API событий Google Workspace, API публикации/подписки и API Google Диска:

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

Настройте идентификатор клиента.

Для генерации идентификатора клиента OAuth 2.0 см. раздел «Создание учетных данных идентификатора клиента OAuth» .

Создать тему Pub/Sub

Перед созданием подписки необходимо создать тему Google Cloud Pub/Sub, которая будет получать события, представляющие интерес для вашего приложения. Инструкции по созданию темы Pub/Sub см. в разделе «Создание и подписка на тему Pub/Sub» .

При отправке запросов обязательно указывайте в качестве источника учетную запись службы Google Диска ( drive-api-event-push@system.gserviceaccount.com ).

Создать подписку на Google Диск

Облачные события отправляются при изменении объекта подписки (или любого другого файла в иерархии объекта). Например, если вы создаете подписку на общем диске и изменяется файл, вложенный в несколько подпапок этого общего диска, генерируется событие. Список поддерживаемых ресурсов и типов событий Drive см. в разделе «Типы событий для создания подписок» .

В следующем примере приложения Node.js создается подписка на события Google Диска для файла или папки, чтобы отслеживать события изменения содержимого. Для получения дополнительной информации см. раздел «Создание подписки на Google Рабочее пространство» .

Для запуска этого примера убедитесь, что у вас установлены Node.js и npm . Также необходимо убедиться, что у вас установлены все необходимые зависимости для запуска этого примера.

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

Для создания подписки на Google Диск используется метод subscriptions.create() API событий Google Рабочей области, который создает ресурс 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);

Замените следующее:

  • SCOPES : Одна или несколько областей действия OAuth , поддерживающих каждый тип события для подписки. Форматируется как массив строк. Чтобы перечислить несколько областей действия, разделяйте их запятыми. В качестве лучшей практики следует использовать наиболее ограниченную область действия, которая все еще позволяет вашему приложению функционировать. Например, 'https://www.googleapis.com/auth/drive.file' .

  • TARGET_RESOURCE : Ресурс Google Workspace , на который вы подписываетесь, в формате полного имени ресурса. Например, чтобы подписаться на файл или папку Google Drive, используйте //drive.googleapis.com/files/FileID .

  • EVENT_TYPES : Один или несколько типов событий , на которые вы хотите подписаться в целевом ресурсе. Формат: массив строк, например, 'google.workspace.drive.file.v3.contentChanged' .

  • RESOURCE_DATA : Логическое значение, указывающее, включает ли подписка данные ресурса в полезную нагрузку события. Это свойство влияет на продолжительность действия вашей подписки. Для получения дополнительной информации см. раздел «Данные события» .

    • True : Включает все данные ресурса. Чтобы ограничить список включаемых полей, добавьте fieldMask и укажите как минимум одно поле для измененного ресурса. Только подписки на ресурсы Chat и Drive поддерживают включение данных ресурса.

    • False : Исключает данные о ресурсах.

  • INCLUDE_DESCENDANTS : Логическое поле, входящее в состав DriveOptions . Доступно только в том случае, если targetResource является файлом Google Диска или общим диском с MIME-типом application/vnd.google-apps.folder . Не может быть установлено для корневой папки «Мой Диск» или общих дисков.

    • True : Подписка включает все дочерние файлы Google Drive в список событий.

    • False : Подписка создается для одного файла или общего диска, указанного в качестве targetResource .

  • TOPIC_NAME : Полное имя темы Pub/Sub, созданной в вашем облачном проекте. Эта тема Pub/Sub получает события для подписки. Форматируется как projects/ PROJECT_ID /topics/ TOPIC_ID . Поле notificationEndpoint используется для указания темы Pub/Sub, и именно сюда подписка доставляет события.

Проверьте свою подписку на Google Диск.

Чтобы проверить, получаете ли вы события Google Диска, вы можете инициировать событие и получить сообщения в подписку Pub/Sub. Для получения дополнительной информации см. раздел «Проверка подписки Google Workspace» .

Обработка событий управления процессом с использованием облачных функций.

Drive events are sent to the Pub/Sub topic in the subscription you create. Make sure when creating the trigger that the Pub/Sub topic for the trigger matches the Pub/Sub topic in your event subscription. You can then deploy your Cloud Run function and make edits to the file to see event changes in the logs.

Перед созданием функции обновите файл package.json , указав необходимые зависимости:

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

Далее создайте исходный код для функции:

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

Ограничения

  • Когда логическое поле includeDescendants в DriveOptions имеет true , подписки на общие диски и папки всегда отправляют событие, даже если файл, вызвавший событие, находится на несколько уровней ниже папки, используемой для подписки на диск.
  • Даже если вы создали подписку на папку, вы можете не получать все события в файловой иерархии, поскольку у пользователя или приложения может не быть доступа к ним. В этом случае подписка остается активной, но вы не будете получать события для ресурсов, к которым у вас нет доступа.
  • Поддерживаются подписки на события для всех файлов и папок, кроме корневой папки общих дисков. Подписки поддерживаются только для файлов и папок внутри общих дисков. Изменения, внесенные непосредственно в корневую папку общего диска, не вызовут событий.
  • Пользователь, авторизующий подписку, должен иметь права доступа к файлу, соответствующему событиям, на которые он подписывается.
  • Подписка получает события только для тех ресурсов, к которым пользователь имеет доступ через свою учетную запись Google Workspace или учетную запись Google.