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

Developer Preview: доступно в рамках программы Google Workspace Developer Preview , которая предоставляет ранний доступ к определенным функциям.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

• Запросите информацию о последних событиях, вызвав API активности Google Drive .

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

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

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

В этом руководстве объясняется, как создать и управлять подпиской на события Google Workspace на Диске. Это позволит вашему приложению получать события через 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. Вы можете включить один или несколько API в одном проекте Google Cloud.

Консоль Google Cloud

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

   Включить API

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

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

gcloud

1. В рабочем каталоге войдите в свою учетную запись Google:

   gcloud auth login

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

   gcloud config set project PROJECT_ID

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

3. Включите API событий Google Workspace, API Pub/Sub и API Диска:

   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 .

Обязательно указывайте учетную запись службы Drive ( [e-mail] ) для своих запросов.

Создайте подписку на Drive

Бета-версия: События Drive доступны в версии Developer Preview. Необходимо использовать API версии v1beta . Попытки использовать стандартную версию API v1 завершатся неудачей.

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

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

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

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

Чтобы создать подписку на Диск, используйте метод subscriptions.create() API событий Google Workspace для создания ресурса 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 , на который вы подписываетесь, отформатированный как его полное имя. Например, чтобы подписаться на файл или папку на Диске, используйте //drive.googleapis.com/files/FileID .

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

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

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

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

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

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

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

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

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

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

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

События Drive отправляются в тему 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 , подписки Drive на общих дисках и папках всегда отправляют событие, даже если файл, вызвавший событие, находится на много уровней ниже папки, используемой для подписки Drive.
• Даже если вы создали подписку на папку, вы можете не получать все события в иерархии файлов, поскольку у пользователя или приложения может быть не предоставлен к ним доступ. В этом случае подписка останется активной, но вы не будете получать события для ресурсов, к которым у вас нет доступа.
• Подписки поддерживаются для событий во всех файлах и папках, за исключением событий в корневой папке общих дисков. Подписки поддерживаются только для файлов и папок внутри общих дисков. Изменения, вносимые непосредственно в корневую папку общих дисков, не приводят к возникновению событий.
• Пользователь, авторизующий подписку, должен иметь разрешение на файл, соответствующий событиям, на которые он подписывается.
• Подписка получает только события для ресурсов, к которым пользователь имеет доступ через свою учетную запись Google Workspace или учетную запись Google.

Похожие темы

• Обзор API событий Google Workspace
• Создайте подписку на Google Workspace
• Подпишитесь на события Google Диска