Как работать с событиями Google Диска

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

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

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

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

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

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

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

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

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

Как работают события

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

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

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

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

Раньше ваше приложение Диска могло находить события с помощью Drive API или Google Drive Activity API. С добавлением событий Диска в Google Workspace Events API появился третий способ получать события:

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

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

• Запросите недавние события, вызвав Google Drive Activity API.

В таблице ниже объясняется разница между подпиской на события и запросом событий, а также причины, по которым следует использовать тот или иной вариант.

Начало работы с событиями Диска

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

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

Чтобы создать облачный проект Google Cloud, следуйте этим инструкциям.

Включите Google Workspace Events API, Google Cloud Pub/Sub API и Google Drive API

Как настроить идентификатор клиента

Чтобы сгенерировать идентификатор клиента OAuth 2.0, ознакомьтесь с разделом Как создать учетные данные идентификатора клиента OAuth.

Как создать тему издатель-подписчик

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

В запросах указывайте сервисный аккаунт Диска (drive-api-event-push@system.gserviceaccount.com).

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

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

Приложение Node.js ниже создает подписку на события Диска для файла или папки, чтобы прослушивать события изменения контента. Подробнее о том, как создать подписку Google Workspace…

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

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

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

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

• SCOPES – одна или несколько областей действия OAuth, которые поддерживают каждый тип события для подписки. Форматируется как массив строк. Если областей несколько, перечислите их через запятую. Рекомендуется использовать наиболее строгую область действия, которая позволяет приложению работать. Пример: 'https://www.googleapis.com/auth/drive.file'.

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

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

• RESOURCE_DATA – логическое значение, которое определяет, включает ли подписка данные ресурса в полезную нагрузку события. Это свойство влияет на продолжительность подписки. Подробнее о данных о событиях…

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

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

• INCLUDE_DESCENDANTS – логическое поле, которое является частью DriveOptions. Доступно, только если targetResource – это файл на Диске или общий диск с MIME-типом application/vnd.google-apps.folder. Нельзя установить для корневой папки раздела "Мой диск" или общих дисков.

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

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

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

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

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

Как обрабатывать события Диска с помощью Cloud Functions

События Диска отправляются в тему Pub/Sub в созданной вами подписке. При создании триггера убедитесь, что тема Pub/Sub для триггера совпадает с темой Pub/Sub в вашей подписке на события. Затем вы можете развернуть функцию Cloud Run и внести изменения в файл, чтобы увидеть изменения событий в журналах.

Прежде чем создавать функцию, обновите файл 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.

Информацию о квотах на подписки и ограничениях частоты запросов можно найти в статье Лимиты на использование Google Workspace Events API.

Статьи по теме

• Обзор Google Workspace Events API
• Как создать подписку Google Workspace
• Как подписаться на события Google Диска
• Лимиты на использование Google Workspace Events API