Praca z wydarzeniami z Dysku Google

Z tego artykułu dowiesz się, jak otrzymywać zdarzenia z Dysku Google z Google Cloud Pub/Sub.

Zdarzenie z Dysku reprezentuje działanie lub zmianę zasobu Dysku, np. nowy plik w folderze. Zdarzenia pozwalają Ci zrozumieć, co się stało, a następnie podjąć działania lub odpowiedzieć użytkownikom w odpowiedni sposób.

Oto kilka przykładów użycia zdarzeń:

• Obserwuj zmiany w pliku, folderze lub na dysku współdzielonym i reaguj na nie, np. gdy plik zostanie edytowany lub zostanie przesłana nowa wersja.

• Monitoruj zmiany w plikach, aby poprawić wydajność aplikacji.

• Kontroluj działania takie jak udostępnianie plików, przenoszenie plików i usuwanie, aby wykrywać potencjalne wycieki danych i nieautoryzowany dostęp.

• Uzyskaj wgląd w to, jak użytkownicy zarządzają swoimi plikami, co pomoże Ci zidentyfikować obszary, w których można ulepszyć zarządzanie treścią.

• Śledź zmiany w plikach, aby sprawdzić zgodność z wymaganiami prawnymi lub zasadami bezpieczeństwa.

• Analizuj aktywność na Dysku za pomocą innych usług Google Cloud , takich jak Eventarc, Workflows, i BigQuery.

Jak działają zdarzenia

Gdy coś się dzieje na Dysku, tworzony, aktualizowany lub usuwany jest zasób interfejsu Google Drive API. Dysk używa zdarzeń, aby przekazywać aplikacji informacje o rodzaju działania i zasobie interfejsu Drive API, którego dotyczyło.

Dysk dzieli zdarzenia na kategorie według typu. Typy zdarzeń pomagają filtrować i otrzymywać tylko te informacje, których potrzebujesz, oraz umożliwiają obsługę podobnych działań w ten sam sposób.

W tabeli poniżej pokazujemy, jak przykładowe działanie na Dysku wpływa na powiązany zasób interfejsu Drive API oraz jaki typ zdarzenia otrzymuje aplikacja Dysku:

Otrzymywanie zdarzeń z Dysku Google

Tradycyjnie aplikacja Dysku Google mogła znajdować zdarzenia za pomocą interfejsu Drive API lub interfejsu Google Drive Activity API. Dzięki dodaniu zdarzeń z Dysku w interfejsie Google Workspace Events API istnieje teraz trzecia metoda otrzymywania zdarzeń:

• Subskrybuj zdarzenia za pomocą interfejsu Google Workspace Events API aby otrzymywać zdarzenia w miarę ich występowania. Więcej informacji znajdziesz w artykule Subskrybowanie zdarzeń z Dysku Google.

• Subskrybuj zdarzenia za pomocą interfejsu Drive API. Otrzymuj zdarzenia zmiany użytkownika za pomocą metody changes.watch lub zdarzenia zmiany pliku za pomocą metody files.watch.

• Wysyłaj zapytania o najnowsze zdarzenia, wywołując interfejs Google Drive Activity API.

W tabeli poniżej wyjaśniamy różnicę między subskrybowaniem zdarzeń a wysyłaniem o nie zapytań oraz powody, dla których warto subskrybować zdarzenia:

Pierwsze kroki ze zdarzeniami z Dysku

Z tego przewodnika dowiesz się, jak utworzyć subskrypcję zdarzeń Google Workspace dotyczącą zasobu Dysku i jak nią zarządzać. Dzięki temu aplikacja będzie mogła otrzymywać zdarzenia za pomocą Google Cloud Pub/Sub.

Tworzenie projektu Google Cloud

Aby utworzyć projekt Google Cloud, przeczytaj artykuł Tworzenie projektu Google Cloud.

Włączanie interfejsu Google Workspace Events API, interfejsu Google Cloud Pub/Sub API i interfejsu Google Drive API

Konfigurowanie identyfikatora klienta

Aby wygenerować identyfikator klienta OAuth 2.0, przeczytaj artykuł Tworzenie danych logowania identyfikatora klienta OAuth.

Tworzenie tematu Pub/Sub

Zanim utworzysz subskrypcję, musisz utworzyć temat Google Cloud Pub/Sub, który będzie otrzymywać odpowiednie zdarzenia, które Cię interesują. Aby utworzyć temat Pub/Sub, przeczytaj artykuł Tworzenie tematu Pub/Sub i subskrybowanie go.

Pamiętaj, aby w żądaniach odwoływać się do konta usługi Dysku (drive-api-event-push@system.gserviceaccount.com).

Tworzenie subskrypcji Dysku

Zdarzenia w chmurze są wysyłane, gdy zmieni się temat subskrypcji (lub dowolny inny plik w hierarchii tematu). Jeśli na przykład utworzysz subskrypcję na dysku współdzielonym i zmieni się plik zagnieżdżony w kilku podfolderach na tym dysku współdzielonym, zostanie wygenerowane zdarzenie. Obsługiwane zasoby i typy zdarzeń z Dysku znajdziesz w artykule Typy zdarzeń do tworzenia subskrypcji.

Poniższa aplikacja Node.js tworzy subskrypcję zdarzeń z Dysku dotyczącą pliku lub folderu, aby nasłuchiwać zdarzeń zmiany treści. Więcej informacji znajdziesz w artykule Tworzenie subskrypcji Google Workspace.

Aby uruchomić ten przykład, musisz mieć zainstalowane środowisko Node.js i npm. Musisz też mieć zainstalowane wymagane zależności, aby uruchomić ten przykład.

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

Aby utworzyć subskrypcję Dysku, użyj metody subscriptions.create interfejsu Google Workspace Events API, aby utworzyć Subscription zasób:

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

Zastąp te elementy:

• SCOPES: co najmniej 1 zakres OAuth, który obsługuje każdy typ zdarzenia w subskrypcji. Sformatowany jako tablica ciągów znaków. Aby podać kilka zakresów, rozdziel je przecinkami. Zalecamy używanie najbardziej restrykcyjnego zakresu, który nadal umożliwia działanie aplikacji. Na przykład, 'https://www.googleapis.com/auth/drive.file'.

• TARGET_RESOURCE: zasób Google Workspace , który subskrybujesz, sformatowany jako pełna nazwa zasobu. Aby na przykład zasubskrybować plik lub folder na Dysku, użyj //drive.googleapis.com/files/FileID.

• EVENT_TYPES: co najmniej 1 typ zdarzenia , który chcesz subskrybować w zasobie docelowym. Sformatuj jako tablicę ciągów znaków, np. 'google.workspace.drive.file.v3.contentChanged'.

• RESOURCE_DATA: wartość logiczna określająca, czy subskrypcja zawiera dane zasobu w ładunku zdarzenia. Ta właściwość wpływa na czas trwania subskrypcji. Więcej informacji znajdziesz w artykule Dane zdarzenia.

  • True: zawiera wszystkie dane zasobu. Aby ograniczyć liczbę uwzględnianych pól, dodaj fieldMask i określ co najmniej 1 pole zmienionego zasobu. Tylko subskrypcje zasobów Chat i Dysk obsługują uwzględnianie danych zasobu.

  • False: wyklucza dane zasobu.

• INCLUDE_DESCENDANTS: pole logiczne, które jest częścią DriveOptions. Dostępne tylko wtedy, gdy targetResource jest plikiem na Dysku lub dyskiem współdzielonym, którego typ MIME jest ustawiony na application/vnd.google-apps.folder. Nie można ustawić w folderze głównym Mojego dysku ani na dyskach współdzielonych.

  • True: subskrypcja obejmuje wszystkie pliki potomne na Dysku na liście zdarzeń.

  • False: subskrypcja jest tworzona dla pojedynczego pliku lub dysku współdzielonego określonego jako targetResource.

• TOPIC_NAME: pełna nazwa tematu Pub/Sub utworzonego w projekcie w chmurze. Ten temat Pub/Sub otrzymuje zdarzenia dotyczące subskrypcji. Sformatowany jako projects/PROJECT_ID/topics/TOPIC_ID. Pole notificationEndpoint służy do określania tematu Pub/Sub i to w nim subskrypcja dostarcza zdarzenia.

Testowanie subskrypcji Dysku

Aby sprawdzić, czy otrzymujesz zdarzenia z Dysku, możesz wywołać zdarzenie i pobrać wiadomości do subskrypcji Pub/Sub. Więcej informacji znajdziesz w artykule Testowanie subskrypcji Google Workspace.

Przetwarzanie zdarzeń z Dysku za pomocą Cloud Functions

Zdarzenia z Dysku są wysyłane do tematu Pub/Sub w utworzonej subskrypcji. Podczas tworzenia reguły upewnij się, że temat Pub/Sub reguły jest zgodny z tematem Pub/Sub w subskrypcji zdarzeń. Następnie możesz wdrożyć funkcję Cloud Run i wprowadzić zmiany w pliku, aby zobaczyć zmiany zdarzeń w logach.

Zanim utworzysz funkcję, zaktualizuj package.json dla zależności:

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

Następnie utwórz kod źródłowy funkcji:

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

• Gdy pole logiczne includeDescendants w DriveOptions ma wartość true, subskrypcje Dysku na dyskach współdzielonych i w folderach zawsze wysyłają zdarzenie, nawet jeśli plik, który wywołał zdarzenie, jest zagnieżdżony wiele poziomów poniżej folderu używanego w subskrypcji Dysku.
• Nawet jeśli utworzysz subskrypcję folderu, możesz nie otrzymywać wszystkich zdarzeń w hierarchii plików, ponieważ użytkownik lub aplikacja mogą nie mieć do nich dostępu. W takim przypadku subskrypcja pozostaje aktywna, ale nie będziesz otrzymywać żadnych zdarzeń dotyczących zasobów, do których nie masz dostępu.
• Subskrypcje są obsługiwane w przypadku zdarzeń dotyczących wszystkich plików i folderów, ale nie w przypadku folderu głównego dysków współdzielonych. Subskrypcje są obsługiwane tylko w przypadku plików i folderów wewnątrz dysków współdzielonych. Zmiany wprowadzone bezpośrednio w folderze głównym dysku współdzielonego nie będą wywoływać zdarzeń.
• Użytkownik, który autoryzuje subskrypcję, musi mieć uprawnienia do pliku odpowiadającego zdarzeniom, które subskrybuje.
• Subskrypcja otrzymuje tylko zdarzenia dotyczące zasobów, do których użytkownik ma dostęp za pomocą konta Google Workspace lub konta Google.

Powiązane artykuły

• Omówienie interfejsu Google Workspace Events API
• Tworzenie subskrypcji Google Workspace
• Subskrybowanie zdarzeń z Dysku Google